Payouts
How to pay out money to a player, when to return their balance and what works in the test environment today.
A payout sends money to the merchant's customer, to their payment details. The merchant's server creates it with one request: the amount plus the fee is reserved from the merchant's available balance, and the payout gets a moderation decision. The outcome comes in a payout.updated notification or is learned by reading the payout.
Steps
- Pick a payout service from the service list: it has
direction: PAYOUT, and its recipient fields start withbeneficiary.. Exactly one destination detail is sent. Create the payout. The
Idempotency-Keyheader is required:curl -sS -X POST https://api.paydex.co.uk/api/v1/payouts \ -H "Authorization: Bearer $PAYDEX_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 7c1d9e42-3a5b-4f80-b6d2-91e4a0c58f17" \ -d '{ "reference": "withdrawal-2001", "service": "payout_pix_brl_direct", "amountMinor": "15000", "customer": { "id": "player-1001", "country": "BR" }, "fields": { "beneficiary.pix_key": "player1001@example.com", "beneficiary.tax_id": "52998224725" }, "metadata": { "withdrawalId": "W-2001" } }'A new payout gets a 201 response. Request and response fields: reference.
Wait for the outcome: a
payout.updatednotification (Notifications) or reading the payout. Read a payout that is not in a final status yourself as well, even if you wait for notifications: an undelivered notification (30 attempts ran out or the address was disabled) is not resent, and an address enabled after the payout was created gets the first notification only when the payout changes.curl -sS https://api.paydex.co.uk/api/v1/payouts/po_3m8q2w7k9x4t6v5n2b8c4d \ -H "Authorization: Bearer $PAYDEX_API_KEY"- Return the balance to the player only on
FAILED,REJECTEDandCANCELLED: payout statuses.
Retry key
Without the Idempotency-Key header no payout is created: a 400 error with the rule idempotency_key_required. Without a key, a retry after a dropped connection would pay out twice. The key works as for a payment (Retrying a request), but more strictly:
- A header or body shape error does not take the key: send the corrected request with the same key. If this same body is already recorded under the key, the recorded answer comes instead of the shape error.
- A refusal on the merits takes the key: service, amount limits, beneficiary fields checked against the service, a requisite value (422
identifier_invalid, for example an IBAN or a tax ID), balance, payout reference, and for payout creation also an error about the API key or the merchant (401 with a rule, 403) and a notification address without an environment secret (409callback_secret_missing). A retry with the same key gets the same error, so send the corrected request with a new key. - A 5xx response or a dropped connection is not a refusal: the payout may have been created. Do not return the balance to the player; retry the same request with the same key, and the retry returns the payout if it exists.
The payout reference is unique for the merchant in the environment, separately from payments: payout 1001 does not clash with deposit 1001.
Money
The fee is charged on top of the amount: amountMinor is what the player receives, feeMinor is the fee. If the available balance does not cover the amount plus the fee, no payout is created: a 409 error with the rule insufficient_balance. The available balance grows from successful payments of the environment, test ones in the test environment. Cancellation returns the reserve to the available balance.
Moderation
The moderation mode is set for each environment of the merchant: a staff member approves the payout, or it is approved at once. By default a staff member approves in the live environment, and payouts are approved at once in the test environment. The decision is in the approval field.
- A payout to the same customer, to the same details and for the same amount waits for staff even in the "at once" mode (
approval: PENDING) if the previous one was created less than 24 hours ago and did not close without money (FAILED,REJECTED,CANCELLED). A successful previous payout counts too. - A payout to a blocked customer or blocked details is created and immediately gets
REJECTEDwith the reasoncustomer_blocked, without a reserve. The response is 201: the payout has an ID, and staff see it too.
Payout statuses
| Status | Meaning | Player balance |
|---|---|---|
CREATED | The payout is created and the reserve is held; it waits for moderation or sending | Do not return |
PROCESSING | The payout is sent, the outcome is not known yet | Do not return: the money may have left |
SUCCEEDED | The money left | Paid out |
FAILED | The money did not leave | Return |
REJECTED | Rejected on our side before sending; reason names why | Return |
CANCELLED | Cancelled by you before sending | Return |
A payout never leaves SUCCEEDED, FAILED, REJECTED or CANCELLED. Treat an unknown status as PROCESSING. While inReview is true, the outcome is being decided on our side: do not return the balance and do not treat the payout as paid. While a payout is not final, do not create a new one instead of it: if the first one goes out, the money goes out twice.
Cancellation
A payout in CREATED that has not been sent yet can be cancelled:
curl -sS -X POST https://api.paydex.co.uk/api/v1/payouts/po_3m8q2w7k9x4t6v5n2b8c4d/cancel \
-H "Authorization: Bearer $PAYDEX_API_KEY"The cancelled payout gets CANCELLED with the reason cancelled_by_merchant, the reserve returns to the available balance, and a moderation decision that was waiting for staff becomes WITHDRAWN. Repeating the cancellation returns the same payout. A sent or closed payout cannot be cancelled: a 409 error with the rule payout_not_cancellable.
Live environment
A live key gets a 403 error with the rule live_payouts_closed.