Use the Disbursements API to send money from your merchant wallet to a user's RocketRamp wallet, for example paying out a player's winnings. You send a USD amount; RocketRamp picks the token and chain from your wallet and sends it. Disbursements are fee-free: the recipient receives exactly the amount you send, and the transfer shows up in both wallets immediately.
Do not use the merchant transfer API (/v1/merchants/transfer/*) to pay users. It needs one token on one chain, so it fails with "Insufficient balance" when your balance is split across tokens, it charges a fee taken out of what the recipient receives, and those transfers do not appear in the wallet app on either side. Disbursements fix all three.
Before you start
- API key permission: your key needs
merchant_wallet_transfers:writeto send andmerchant_wallet_transfers:readto check status. - Transfer allowance: in Settings → Wallet Security → Grant/Transfer Permission, set the allowance to at least your largest single payout. The default is 100; a payout above the allowance is refused with
amount_over_allowance. - Fund your merchant wallet. Payouts come out of your merchant wallet, not your personal (customer) account. Any USD stablecoin you hold counts: if no single holding covers a payout but your total does, RocketRamp consolidates into one token automatically before sending, in the same call.
- The recipient must already have a RocketRamp wallet (signed up with that email). Otherwise the call is refused with
recipient_not_registeredorrecipient_not_found.
Send a disbursement
Call this from your server only. Create a new UUID idempotency_key for each payout and save it with your payout record before you send.
curl -X POST https://api.coinsub.io/v1/merchants/disbursements \
-H "Merchant-ID: YOUR_MERCHANT_ID" \
-H "API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"recipient_email": "player@example.com",
"amount": 100.00,
"idempotency_key": "0f9a5b2c-1d3e-4a6b-8c7d-9e0f1a2b3c4d",
"reference": "payout-1042",
"memo": "Cash-out"
}'You can send partner_user_id instead of recipient_email (exactly one of the two). The amount is in USD.
Response (accepted, not yet settled):
{
"data": {
"id": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
"status": "initiated",
"recipient_account_id": "9b2f5a10-8c3d-4e2f-a1b6-77c0e1a2b3c4",
"idempotency_key": "0f9a5b2c-1d3e-4a6b-8c7d-9e0f1a2b3c4d",
"replayed": false
},
"status": 200
}Confirm it completed
The lifecycle is initiated → completed | failed. Check with:
curl https://api.coinsub.io/v1/merchants/disbursements/3f2504e0-4f89-41d3-9a0c-0305e82c3301 \
-H "Merchant-ID: YOUR_MERCHANT_ID" \
-H "API-Key: YOUR_API_KEY"A disbursement usually reaches completed within seconds of being accepted. Mark your payout paid only on completed; on failed, return the funds to your user once.
RocketRamp also sends a wallet_transfer (or failed_wallet_transfer) webhook carrying your reference. Treat it as a signal and confirm with the GET above before marking the payout paid.
Retry safely
If a request times out or you get a 5xx, retry with the same idempotency_key. You get the original disbursement back with "replayed": true and nothing is sent twice. Never create a new key for a retry of the same payout; that is how you pay twice.
Errors you can fix
| Status | Code | What to do |
|---|---|---|
| 400 | invalid_request | Check the fields; send exactly one of recipient_email / partner_user_id. |
| 400 | self_send | The recipient is your own merchant account. |
| 402 | insufficient_balance | Fund your merchant wallet. Funds held by in-flight disbursements are not available. |
| 404 | recipient_not_found | No RocketRamp account for that email. |
| 409 | recipient_not_registered | The user hasn't finished RocketRamp signup. |
| 409 | recipient_unavailable | Temporary; retry later. Nothing was charged. |
| 409 | no_signing_key | Grant the transfer permission in Wallet Security. |
| 409 | amount_over_allowance | Raise the allowance in Wallet Security, or lower the amount. |
| 409 | idempotency_conflict | That key is already used for something else. Do not resend this payout with a new key until you have checked whether the original was paid. Use a fresh UUID for every new payout. |
Treat a timeout or unreadable answer as "unknown", not "failed": check the status (or retry with the same key) before telling your user anything or returning their funds.
Checklist
- Key has
merchant_wallet_transfers:write; allowance covers your largest payout. - Merchant wallet funded (total balance is what matters).
- One UUID
idempotency_keyper payout, saved before sending, reused on retries. - Paid only on
completed; refunded once onfailed. - Test with a small real payout to your own RocketRamp account and confirm it appears in both wallets.