Search...
Log inGet started
Airwallex logo
Home
Core API
Payments
Transactional FX
Payouts
Issuing
Back to home
Get started
QuickstartManage API keys
Event simulations
Simulate deposits to your Global AccountSimulate payout status transition
Simulate connected account status transitionSimulate transactions on issued cards

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-of header

Step 1: Obtain your access token

Call obtain access token API to obtain an access token to use in your API requests.

Example request

Shell

Example response

JSON

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_status specified is the next valid status in Payout statuses. Please note that OVERDUE can only be simulated when the payout is not funded beyond the payment date; PAID can 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 a failure_type with an acceptable value from the table below to simulate a specific failure reason (which will be the returned failure_reason in 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_DISPATCH or SUSPENDED, the status can only be transitioned if it is the next valid status in Payout statuses.
  • If you use DISPATCHED or FAILED, the status will automatically transition through intermediary statuses into the status you designate.
  • When you use FAILED, please also specify a failure_type with an acceptable value from the table below to simulate a specific failure reason (which will be the returned failure_reason in the response).
Failure_type in requestfailure_reason in response
INVALID_ACCOUNT_NAME_OR_NUMBER90101: Invalid account name/number
INVALID_BANK_OR_BRANCH_CODE90201: Invalid bank/branch code
INVALID_SWIFT_BIC_CODE90202: Invalid SWIFT/BIC code
INVALID_CORRESPONDENT_BANK_INFORMATION90203: Invalid correspondent bank information
INVALID_BANK_INFORMATION90204: Invalid bank information
BENEFICIARY_NAME_MISMATCH90301: Beneficiary name mismatch
ACCOUNT_CURRENCY_MISMATCH90302: Account currency mismatch
INVALID_BENEFICIARY_DETAILS90401: Invalid beneficiary details
INVALID_SPECIAL_CHARACTER90402: Invalid special character
CHANNEL_POLICY90501: Channel policy
TM_SUSPENDED90502: TM suspended
ACCOUNT_CLOSED90701: Account closed
ACCOUNT_INACTIVE_OR_DORMANT90702: Account inactive or dormant
ACCOUNT_UNDER_RESTRICTION90703: Account under restriction
BENEFICIARY_REQUESTED90801: Beneficiary requested
BENEFICIARY_BANK_RETURNED90802: Beneficiary bank returned
INBOUND_BENFICIARY_VALIDATION_ERROR90901: Inbound benficiary validation error
INBOUND_ORDER_ERROR90902: Inbound order error
INBOUND_2B_CARD_NOT_SUPPORTED90903: Inbound 2B card not supported
INBOUND_COMPANY_REGISTRATION_NUMBER_ERROR90904: Inbound company registration number error
RECALL_REQUESTED91001: Recall requested
CLIENT_REQUESTED91002: Client requested
INVALID_PAYMENT_PURPOSE91101: Invalid payment purpose
CARD_ISSUER_ERROR91201: Card issuer error
SYSTEM_ERROR91401: System error
CHANNEL_TIMEOUT91402: Channel timeout
OTHER99902: Other

Example response

JSON

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:

On this page