Developer Docs

Paying Your Users

Send money from your merchant wallet to a user's RocketRamp wallet, for example a player's winnings.

Docs menuPaying Your Users
Quick Start Setup & Credentials Prefill API Opening the Checkout Phones & In-App Browsers Webhooks Paying Your Users Reconciliation Environments Common Mistakes Go-Live Checklist FAQ

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

  1. API key permission: your key needs merchant_wallet_transfers:write to send and merchant_wallet_transfers:read to check status.
  2. 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.
  3. 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.
  4. The recipient must already have a RocketRamp wallet (signed up with that email). Otherwise the call is refused with recipient_not_registered or recipient_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
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):

JSON
{
  "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
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

StatusCodeWhat to do
400invalid_requestCheck the fields; send exactly one of recipient_email / partner_user_id.
400self_sendThe recipient is your own merchant account.
402insufficient_balanceFund your merchant wallet. Funds held by in-flight disbursements are not available.
404recipient_not_foundNo RocketRamp account for that email.
409recipient_not_registeredThe user hasn't finished RocketRamp signup.
409recipient_unavailableTemporary; retry later. Nothing was charged.
409no_signing_keyGrant the transfer permission in Wallet Security.
409amount_over_allowanceRaise the allowance in Wallet Security, or lower the amount.
409idempotency_conflictThat 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

?