Simulate payout status transition
You can conduct unit and end-to-end testing of your integration to Airwallex Payouts with Transition Payment Status API to test all the Payouts endpoints API that apply to payouts in different statuses. Please note that this sandbox simulation endpoint works in demo environment only.
Key test scenarios include:
- Creating payouts and triggering webhook event for Payout status transitions
- Canceling and retrying failed payouts
- Calling Payouts endpoints on behalf of connected accounts by specifying an open ID in the
x-on-behalf-ofheader
Step 1: Obtain your access token
Call obtain access token API to obtain an access token to use in your API requests.
Example request
Example response
Step 2: Create a payout
Create a payout by calling Create a new payment API. See more details in Step 2 in Create a payout.
Step 3: Transition payment status
API version 2024-01-31 or later
Call Transition Payment Status API and specify the payment_id in the endpoint URL to simulate the status transition of your payout.
Specify the next_status parameter in the request body to transition your payout to a subsequent status. See Payout statuses to understand the definition and sequence of payout statuses.
This endpoint supports simulating these statuses: PROCESSING, FAILED, SENT, PAID, or CANCELLED. Payout statuses that are only applicable to the payouts created and submitted for approval are not currently supported.
- The status can only be transitioned if the
next_statusspecified is the next valid status in Payout statuses. Please note thatOVERDUEcan only be simulated when the payout is not funded beyond the payment date;PAIDcan only be simulated in API version 2024-04-30 or later. - If you specified an invalid status name, you will receive an error message about invalid next status.
- When you use
FAILED, please also specify afailure_typewith an acceptable value from the table below to simulate a specific failure reason (which will be the returnedfailure_reasonin the response).
API version 2023-10-01 or earlier
Call Transition Payment Status API and specify the payment_id in the endpoint URL to simulate the status transition of your payout.
Specify the next_status parameter in the request body to transition your payout to a subsequent status. See Payout statuses to understand the definition and sequence of payout statuses.
This endpoint supports simulating these statuses: READY_FOR_DISPATCH, DISPATCHED, IN_REVIEW, SUSPENDED, or FAILED. Payout statuses that are only applicable to the payouts created and submitted for approval are not currently supported.
- If you use
IN_REVIEW,READY_FOR_DISPATCHorSUSPENDED, the status can only be transitioned if it is the next valid status in Payout statuses. - If you use
DISPATCHEDorFAILED, the status will automatically transition through intermediary statuses into the status you designate. - When you use
FAILED, please also specify afailure_typewith an acceptable value from the table below to simulate a specific failure reason (which will be the returnedfailure_reasonin the response).
| Failure_type in request | failure_reason in response |
|---|---|
| INVALID_ACCOUNT_NAME_OR_NUMBER | 90101: Invalid account name/number |
| INVALID_BANK_OR_BRANCH_CODE | 90201: Invalid bank/branch code |
| INVALID_SWIFT_BIC_CODE | 90202: Invalid SWIFT/BIC code |
| INVALID_CORRESPONDENT_BANK_INFORMATION | 90203: Invalid correspondent bank information |
| INVALID_BANK_INFORMATION | 90204: Invalid bank information |
| BENEFICIARY_NAME_MISMATCH | 90301: Beneficiary name mismatch |
| ACCOUNT_CURRENCY_MISMATCH | 90302: Account currency mismatch |
| INVALID_BENEFICIARY_DETAILS | 90401: Invalid beneficiary details |
| INVALID_SPECIAL_CHARACTER | 90402: Invalid special character |
| CHANNEL_POLICY | 90501: Channel policy |
| TM_SUSPENDED | 90502: TM suspended |
| ACCOUNT_CLOSED | 90701: Account closed |
| ACCOUNT_INACTIVE_OR_DORMANT | 90702: Account inactive or dormant |
| ACCOUNT_UNDER_RESTRICTION | 90703: Account under restriction |
| BENEFICIARY_REQUESTED | 90801: Beneficiary requested |
| BENEFICIARY_BANK_RETURNED | 90802: Beneficiary bank returned |
| INBOUND_BENFICIARY_VALIDATION_ERROR | 90901: Inbound benficiary validation error |
| INBOUND_ORDER_ERROR | 90902: Inbound order error |
| INBOUND_2B_CARD_NOT_SUPPORTED | 90903: Inbound 2B card not supported |
| INBOUND_COMPANY_REGISTRATION_NUMBER_ERROR | 90904: Inbound company registration number error |
| RECALL_REQUESTED | 91001: Recall requested |
| CLIENT_REQUESTED | 91002: Client requested |
| INVALID_PAYMENT_PURPOSE | 91101: Invalid payment purpose |
| CARD_ISSUER_ERROR | 91201: Card issuer error |
| SYSTEM_ERROR | 91401: System error |
| CHANNEL_TIMEOUT | 91402: Channel timeout |
| OTHER | 99902: Other |
Example request
Example response
Next steps
As the payout status transitions, you can then listen for the webhook events you have subscribed to, and test with the endpoints that only apply for payouts in specific statuses:
- Cancel a payment API: for payouts in
NEWorFAILEDstatus. - Retry a payment API: for payouts in
FAILEDstatus.