curl -X POST https://api.zbdpay.com/api/v1/transactions/purchases \
-H "x-api-key: YOUR_API_KEY" \
-H "Idempotency-Key: 2c9a7b13-58ef-4d02-8a6c-14b3f7e05d29" \
-H "Content-Type: application/json" \
-d '{
"user_id": "4ac4fd8a-cc2c-4d03-af09-a76f4e89d652",
"currency": "GEMS",
"amount": 500,
"reference_id": "order_9921",
"description": "Sunset skin"
}'
{
"success": true,
"message": "Purchase completed.",
"data": {
"transaction_id": "txn_7f2c",
"type": "purchase",
"status": "completed",
"currency": "GEMS",
"amount": 500,
"payer": { "user_id": "4ac4fd8a-cc2c-4d03-af09-a76f4e89d652" },
"movements": [
{ "movement_id": "mv_1", "to": { "party": "publisher" }, "amount": 500 }
],
"reference_id": "order_9921",
"project_id": null,
"created_at": "2026-10-01T18:20:00Z"
},
"error": null
}
Transactions
Make a Purchase
A user buys something from you with their balance.
POST
/
api
/
v1
/
transactions
/
purchases
curl -X POST https://api.zbdpay.com/api/v1/transactions/purchases \
-H "x-api-key: YOUR_API_KEY" \
-H "Idempotency-Key: 2c9a7b13-58ef-4d02-8a6c-14b3f7e05d29" \
-H "Content-Type: application/json" \
-d '{
"user_id": "4ac4fd8a-cc2c-4d03-af09-a76f4e89d652",
"currency": "GEMS",
"amount": 500,
"reference_id": "order_9921",
"description": "Sunset skin"
}'
{
"success": true,
"message": "Purchase completed.",
"data": {
"transaction_id": "txn_7f2c",
"type": "purchase",
"status": "completed",
"currency": "GEMS",
"amount": 500,
"payer": { "user_id": "4ac4fd8a-cc2c-4d03-af09-a76f4e89d652" },
"movements": [
{ "movement_id": "mv_1", "to": { "party": "publisher" }, "amount": 500 }
],
"reference_id": "order_9921",
"project_id": null,
"created_at": "2026-10-01T18:20:00Z"
},
"error": null
}
Takes value from the user’s balance and pays it to you, for example for a cosmetic, a battle pass, or an entry fee. Your backend makes the call, since your game decides what’s being bought and what it costs. The full amount goes to you, so there are no recipients to send.
Returns the same fields as Get a Transaction.
Configuration
Header Parameters
A UUID you generate for this purchase. Retrying with the same key never charges the user twice.
Body Parameters
curl -X POST https://api.zbdpay.com/api/v1/transactions/purchases \
-H "x-api-key: YOUR_API_KEY" \
-H "Idempotency-Key: 2c9a7b13-58ef-4d02-8a6c-14b3f7e05d29" \
-H "Content-Type: application/json" \
-d '{
"user_id": "4ac4fd8a-cc2c-4d03-af09-a76f4e89d652",
"currency": "GEMS",
"amount": 500,
"reference_id": "order_9921",
"description": "Sunset skin"
}'
{
"success": true,
"message": "Purchase completed.",
"data": {
"transaction_id": "txn_7f2c",
"type": "purchase",
"status": "completed",
"currency": "GEMS",
"amount": 500,
"payer": { "user_id": "4ac4fd8a-cc2c-4d03-af09-a76f4e89d652" },
"movements": [
{ "movement_id": "mv_1", "to": { "party": "publisher" }, "amount": 500 }
],
"reference_id": "order_9921",
"project_id": null,
"created_at": "2026-10-01T18:20:00Z"
},
"error": null
}
Errors
| HTTP | code | When |
|---|---|---|
400 | idempotency_key_required · validation_failed | No idempotency key, or a malformed body |
404 | user_not_found | The user doesn’t exist under your key |
409 | idempotency_key_reused | The same key was sent with a different body |
422 | insufficient_funds | The user’s balance doesn’t cover the amount. Nothing is taken |
Was this page helpful?