Processing a payout
Flow, statuses, return codes, retries, credit reversals, webhooks and sandbox testing for payouts.
This page walks through a payout from request to final status: the sequence of calls, the statuses, the return codes, what to do when the result is unknown, and how to test in Sandbox.
Sequence
- Tokenize
Tokenize the beneficiary card with Create a token.
- Create the transfer
Call Create a transfer with the token, the amount, the purpose and your
order_merchant_id. - Eligibility and credit
The platform validates the request, checks the card's eligibility with the partner when the contract requires it, then sends the credit.
- Status
The response carries the final or pending status. A webhook follows every status change.
- Pending result
Wait for the final webhook, or call Retrieve a transfer.
Example
The request below creates a transfer with Create a transfer. All fields are described there.
{
"transfer_type": "oct",
"transfer_purpose": "online_gambling_payout",
"amount": 250.00,
"currency": "EUR",
"order_merchant_id": "PAYOUT-2026-11-0041",
"merchant_contract": "69fb373bacda23a62375d5b0",
"destination_account_type": "card",
"destination_account_token": "3554757d2b2039e34d4f43950ba1ac475904492b9d03d2b964f237ad51a0ec16",
"destination_account_id": "PLAYER-0635656565",
"destination_account_first_name": "John",
"destination_account_last_name": "Doe",
"destination_account_country": "FR"
}{
"result": { "code": "980001", "description": "credit successful" },
"order_id": "69fdb213cf4304374840f155",
"transaction_id": "69fdb213cf4304374840f157",
"status": "credit_successful",
"category": "payout",
"transfer_type": "oct",
"transfer_purpose": "online_gambling_payout",
"order_amount": 250.00,
"order_currency": "EUR",
"order_merchant_id": "PAYOUT-2026-11-0041",
"payment_method_name": "visa",
"destination_account_type": "card",
"destination_account_token": "3554757d2b2039e34d4f43950ba1ac475904492b9d03d2b964f237ad51a0ec16",
"destination_account_id": "PLAYER-0635656565",
"destination_account_last_4_digits": "5987",
"destination_account_scheme": "visa",
"destination_account_funding_type": "debit",
"destination_account_country": "FR",
"is_eligible": true,
"eligibility_status": "eligibility_approved",
"is_credited": true,
"credit_date": "2026-11-16T12:30:05Z",
"credit_status": "credit_successful",
"payout_partner": "MockPay",
"merchant_contract_id": "69fb373bacda23a62375d5b0",
"psp_result_code": "0",
"psp_result_description": "Success",
"psp_transaction_id": "psp_txn_8a8294a71c33",
"network_reference_id": "654321123456",
"authorization_code": "123456"
}Status flow
A payout ends in one final state. Only credit_successful moves funds. When the eligibility check is disabled on the contract, the payout goes straight from created to credit_requested.
Statuses
| Status | Meaning | Order state | Final |
|---|---|---|---|
created | Request accepted, not yet sent. | pending | Not final |
eligibility_requested | Card eligibility being checked with the partner. | pending | Not final |
eligibility_approved | The card can receive the credit. | pending | Not final |
eligibility_declined | The card cannot receive an OCT. No credit attempted. | failed | Final |
eligibility_request_failed | Technical failure on the eligibility check. | failed | Final |
credit_requested | Credit sent, partner result pending. | pending | Not final |
credit_successful | Funds credited to the beneficiary. | closed | Final |
credit_declined | Refused by the partner or the issuer. No funds moved. | failed | Final |
credit_request_failed | Technical failure (timeout, 5xx). Result unknown. | failed | Final |
credit_request_expired | No final result within the expiry delay. | failed | Final |
credit_reversed | Funds returned by the partner after a successful credit. | closed | Final |
route_not_found | No eligible payout contract. | failed | Final |
blocked_by_router | Blocked by a routing rule. | failed | Final |
The same statuses are returned in status by Create a transfer and Retrieve a transfer, and listed in Order status.
Return codes
Payout return codes follow the return code structure. The first digit 8 is the credit phase. Error responses use the envelope described in Errors.
| Code | Status | Meaning | What to do |
|---|---|---|---|
980001 | credit_successful | Credit successful. | Nothing. The funds are on their way. |
821001 | credit_requested | Credit requested, pending at the partner. | Wait for the final webhook, or call Retrieve a transfer. |
821101 | credit_declined | Credit declined by the issuer. | Do not retry as is. Check the card and the purpose. |
821201 | credit_reversed | Credit reversed, funds returned. | Reconcile: the beneficiary did not keep the funds. |
810001 | credit_request_failed | Credit request failed (technical). | Result unknown. Call Retrieve a transfer before any new attempt. |
811001 | credit_request_expired | No final result within the expiry delay. | Same as 810001. |
840001 | eligibility_declined | Destination card not eligible for OCT. | Ask the beneficiary for another card. |
840101 | eligibility_declined | Issuer does not support money transfers. | Ask the beneficiary for another card. |
841001 | credit_declined | Destination account closed or invalid. | Ask the beneficiary for another card. |
850001 | route_not_found | Transfer purpose not supported by the contract. | Use another purpose or another contract. |
851001 | route_not_found | No payout contract for this country or currency, or merchant_contract is not a payout contract. | Check merchant_contract. |
861001 | None | Request incomplete: purpose code or beneficiary data missing for this corridor. | Complete the request. See Specification. |
861003 | None | Duplicate order_merchant_id for a payout. | Use a new order_merchant_id, and check the result of the first transfer. |
861005 | None | Both original_transaction_id and psp_original_transaction_id sent. | Send only one. |
861006 | None | This contract requires an original transaction reference. | Add one of the two reference fields. |
861007 | None | A card number was sent in an account number field. | Tokenize the card with Create a token and use destination_account_token. |
111012 | None | Invalid parameter: a field that is not accepted on a transfer was sent. | Remove the field. See Create a transfer. |
Retries and duplicates
A replayed request could pay the beneficiary twice, so a failed credit is never sent again automatically.
On credit_request_failed (810001), the partner may or may not have processed the credit. Before you submit a new transfer:
- Check the transfer
Call Retrieve a transfer and check the status.
- Check the partner
Look the payout up in your partner reporting.
- Ask if in doubt
Contact Support before you send a new transfer.
order_merchant_id is unique per API key for payouts. A duplicate is rejected with 861003.
Credit reversal
The partner can return the funds after a successful credit, for example when the account is closed or the scheme returns the credit. The transaction keeps is_credited: true and gains is_credit_reversed: true with credit_reversal_amount. The status becomes credit_reversed and a webhook is sent. Retrieve a transfer returns the reversal fields on the credit transaction.
Both legs are kept, never netted.
Webhooks
Payout webhooks use the same delivery, signature and retry policy as payment webhooks. See Accept webhooks and Webhooks workflow.
| Item | Details |
|---|---|
| Events to subscribe | credit_requestedcredit_successfulcredit_declinedcredit_request_failedcredit_request_expiredcredit_reversedeligibility_declined The other eligibility events are available too. See Payout events. |
| Default payload | request_idorder_idtransaction_idmerchant_order_idmerchant_contract_idcategorystatusaction_dateamountcurrencyconverted_amountconverted_currencytransfer_typetransfer_purposetransfer_referencepayment_methodpayout_partneris_eligibleis_creditedcredit_datecredit_statuscredit_resultcredit_reasonis_credit_reversedcredit_reversal_datecredit_reversal_statuscredit_reversal_resultcredit_reversal_amountcredit_reversal_reasoncredit_reversal_reason_codepsp_result_codepsp_result_descriptionmerchant_accountprogram_managerevent_typemerchant_data Every payout notification carries |
| Optional fields | Addable per webhook in the Console: the destination_account_* fields (never the account number), eligibility_status and eligibility_reason. |
| Always present | order_idtransaction_idstatusmerchant_account |
| Never sent | capture_total_amountrefund_total_amountis_capturableauthentication_*card_6_digits Payment-only fields. |
Handle several notifications per payout
A payout can receive several webhooks over several days: pending, final, then a reversal. Delivery is at-least-once and unordered.
- Handle duplicates idempotently on
transaction_id+status. - Order events by
action_date.
Test in Sandbox
On the sandbox payout contract, the amount sent to Create a transfer drives the result:
| Amount | Result |
|---|---|
20.12 | eligibility_declined |
25.48 | credit_declined |
| Any other amount | credit_successful |
Related pages
Updated 5 days ago