Store Transactions

When a player purchases a bundle with Buy Store Bundle, RapidMule creates a provision (transaction) that tracks fulfilment. These endpoints let you read and advance that provision through its lifecycle: check its status, mark it complete once your system has delivered the goods, cancel a pending provision, or refund a completed one.

All four endpoints identify the provision by its provisionUid and return the same transaction object.

Transaction Status

Returns the current status of a provision.

Endpoint

POST /v1/store/transaction-status

Request Body

Parameter	Type	Required	Description
provisionUid	string	Yes	Unique identifier of the provision (transaction)

Example Request

{
  "provisionUid": "{{provisionID}}"
}

Response

{
"code": 200,
"data": {
  "playerId": "4f9c9e5569524cb18e77d5b804b1e35a",
  "provisionUid": "a1f7c9d2b3e04f60a1234567890abcde",
  "cost": 50,
  "costDeliverableUid": "41c8680620d94498b295e53e7db96045",
  "referenceType": "Store",
  "status": "Completed",
  "createDate": 1751980800000,
  "updateDate": 1751980800000
}
}

Response Fields

Field	Type	Description
playerId	string	Player the transaction belongs to
provisionUid	string	Unique identifier of the provision
cost	number	Amount charged for the purchase
costDeliverableUid	string	UID of the deliverable used as currency
referenceType	string	Source of the transaction, e.g. Store
status	string	Transaction status: Pending, Completed, Refunded, or Failed
createDate	long	Unix timestamp (ms) when the transaction was created
updateDate	long	Unix timestamp (ms) when the transaction was last updated

Request Example

curl -X POST https://api.rapidmule.com/v1/store/transaction-status \
  -H "AuthKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provisionUid": "{{provisionID}}"}'

Complete Transaction

Marks a pending provision as Completed. Call this once your system has successfully delivered the purchased goods to the player.

Endpoint

POST /v1/store/complete-transaction

Request Body

Parameter	Type	Required	Description
provisionUid	string	Yes	Unique identifier of the provision to complete

Request Example

curl -X POST https://api.rapidmule.com/v1/store/complete-transaction \
  -H "AuthKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provisionUid": "{{provisionID}}"}'

Cancel Transaction

Cancels a pending provision that has not yet been completed.

Endpoint

POST /v1/store/cancel-transaction

Request Body

Parameter	Type	Required	Description
provisionUid	string	Yes	Unique identifier of the provision to cancel

Request Example

curl -X POST https://api.rapidmule.com/v1/store/cancel-transaction \
  -H "AuthKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provisionUid": "{{provisionID}}"}'

Refund Transaction

Refunds a completed store transaction. This reverses the delivered items and returns the spent currency to the player. Only completed store transactions can be refunded.

Endpoint

POST /v1/store/refund-transaction

Request Body

Parameter	Type	Required	Description
provisionUid	string	Yes	Unique identifier of the provision to refund

Request Example

curl -X POST https://api.rapidmule.com/v1/store/refund-transaction \
  -H "AuthKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provisionUid": "{{provisionID}}"}'

Use Cases

• Delivery Confirmation: Complete the transaction only after your system fulfils the reward
• Abandoned Checkout: Cancel a provision that was never fulfilled
• Customer Support: Refund a completed purchase on request or dispute
• Reconciliation: Poll transaction status to keep your ledger in sync

Error Codes

Code	Description	Resolution
1002	Invalid transaction id	Provide a valid provisionUid
4001	Invalid AuthKey	Verify API key
9004	Transaction does not exist	Check the provisionUid
9002	Transaction already completed	Cannot re-complete or cancel a completed transaction
9003	Transaction already failed	The transaction is in a failed state
9010	Transaction already refunded	The transaction has already been refunded
9008	Only completed transactions can be refunded	Complete the transaction before refunding
9009	Only store transactions can be refunded	The provision is not a store purchase

Refund Side Effects

Refunding removes the delivered items from the player's inventory and returns the currency they spent. Make sure the transaction is genuinely eligible before calling refund.

Related Endpoints

• Buy Store Bundle - Start a purchase and create the provision
• Reward Stores - List stores and bundles