Buy Store Bundle

This method initiates a transaction to purchase a specific bundle from your reward store. Upon successful initiation, it returns a unique transaction ID, which can be used to track the status and progress of the transaction.

Endpoint

POST /v1/store/buy

Request Body

Parameter	Type	Required	Description
playerId	string	Yes	Unique identifier for the player
referenceId	string	Yes	Unique identifier for the store bundle (bundle UID)

Example Request

{
  "referenceId": "{{bundleID}}",
  "playerId": "{{playerID}}"
}

Response

Success Response

{
  "code": 200,
  "message": "Purchase successful",
  "data": {
    "transactionId": "tx-f4a7c1b9-3e5d",
    "playerId": "{{playerID}}",
    "bundleId": "{{bundleID}}",
    "status": "completed"
  }
}

Error Response

{
  "code": 4003,
  "message": "Insufficient funds"
}

Request Example

curl -X POST https://api.rapidmule.com/v1/store/buy \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceId": "{{bundleID}}",
    "playerId": "{{playerID}}"
  }'

Use Cases

• Store Purchase Flow: Complete purchase flow with inventory checks and error handling
• Stock Validation: Check bundle stock availability before initiating purchase
• Transaction Tracking: Track purchases using transaction IDs for auditing and support

Error Codes

Code	Description	Resolution
1001	Payload is null	Check request body
1002	Invalid Player	Verify playerId exists
4001	Invalid AuthKey	Verify API key
4003	Insufficient funds	Player doesn't have enough currency
9008	Bundle does not exist	Use valid bundleId
9009	Bundle out of stock	Check stock availability

Best Practices

1. Pre-purchase Validation: Always check player's currency and bundle availability before purchase
2. Error Handling: Implement comprehensive error handling for all failure scenarios
3. Transaction Logging: Store transaction IDs for auditing and support purposes
4. UI Feedback: Provide clear feedback to users about purchase success or failure
5. Inventory Refresh: Refresh player inventory after successful purchase

Important

This endpoint deducts currency from the player's inventory. Ensure proper validation before calling to prevent accidental purchases.

Related Endpoints

• Reward Stores - Get available stores and bundles
• Player Detail - Check player's inventory