Payouts
Simulate the payout lifecycle scenarios in the sandbox environment.
POST /api/v1/simulation/payments/{payment_id}/transition
Transition payment status
POST /api/v1/simulation/payments/{payment_id}/transition
You can use this endpoint to simulate the status transition of your payment. This is only available in the sandbox environment. Learn about the payout status lifecycle .
Unique identifier of the payment to transition the status of.
The next status to transition to. Status can be DISPATCHED, FAILED, IN_REVIEW, READY_FOR_DISPATCH, and SUSPENDED.
The type of failure to simulate.
ACCOUNT_CLOSED, ACCOUNT_CURRENCY_MISMATCH, ACCOUNT_INACTIVE_OR_DORMANT, ACCOUNT_UNDER_RESTRICTION, BENEFICIARY_BANK_RETURNED, BENEFICIARY_NAME_MISMATCH, BENEFICIARY_REQUESTED, CARD_ISSUER_ERROR, CHANNEL_POLICY, CHANNEL_TIMEOUT, CLIENT_REQUESTED, DUPLICATION_RETURN, EXCEEDED_TRANSACTION_AMOUNT_OR_LIMIT, INBOUND_2B_CARD_NOT_SUPPORTED, INBOUND_BENFICIARY_VALIDATION_ERROR, INBOUND_COMPANY_REGISTRATION_NUMBER_ERROR, INBOUND_ORDER_ERROR, INSUFFICIENT_FUNDS, INVALID_ACCOUNT_NAME_OR_NUMBER, INVALID_BANK_INFORMATION, INVALID_BANK_OR_BRANCH_CODE, INVALID_BENEFICIARY_DETAILS, INVALID_CORRESPONDENT_BANK_INFORMATION, INVALID_PAYMENT_PURPOSE, INVALID_SPECIAL_CHARACTER, INVALID_SWIFT_BIC_CODE, OTHER, RECALL_REQUESTED, SYSTEM_ERROR, TM_SUSPENDED, TRANSACTION_AMOUNT_NOT_COVERING_FEE, UNABLE_TO_APPLY
The total amount (in payment payment_currency) the beneficiary receives for this payment, and is governed by value specified in fee_paid_by, i.e. if fee_paid_by is PAYER, then the beneficiary receives the exact same payment_amount since payer is responsible for the payment fee. Otherwise, beneficiary receives payment_amount - fee as the fee is implicitly passed onto the beneficiary
The total amount (in source_currency) the payer has to pay for making this payment. For example, if fee_paid_by is PAYER and FX conversion is not involved, then this is the sum of payment_amount + fee as the payer is responsible for the fee. Otherwise this field is the same as payment_amount
The application fee options applied to this payment.
A positive integer specifying the amount of the fee expressed in the smallest unit of the currency. e.g. cents for USD. This field is required only when type is FIXED.
Specify the currency of the application fee in ISO 4217 currency code format, e.g., USD, AUD. This field is required when the type is FIXED.
When the type is PERCENTAGE and source_type is CONVERSION, the currency for the conversion if specified must be from the currency pair. If the currency is unspecified, the contra currency of the quote will be used.
The metadata of the application fee. The value should be set in key:value format. (e.g., id:1).
Required if the type is PERCENTAGE, and the value to be provided depends on the transaction context.
FX Conversions: The value acts as a markup on the FX rate, increasing the conversion cost by the specified percentage.
Others: The value represents a direct fee calculated as a percentage of the transaction amount.
Specify type of the source transaction.
CONVERSION, TRANSFER
Define the type of fee calculation. If the source_type is CONVERSION, then the type must be PERCENTAGE.
FIXED, PERCENTAGE
Application fees in this payment.
The application fee amount.
The application fee currency.
The source type this application fee is applicable to.
CONVERSION, PAYMENT
Unique identifier of the batch containing the payment.
Details of the beneficiary
Additional information about the beneficiary
Category of business activity
Business phone number
Business registration number
The identifier that you use to identify a beneficiary, usually a unique identifier. This field can be used to link transfers or beneficiaries to other records such as tax form details for filing purposes
Legal representative's personal bank account number used for declaration purposes. No funds will be sent to this account number.
Legal representative first name in chinese
Legal representative id number
Legal representative last name in chinese
Legal representative’s mobile number associated with their bank account.
Personal email
Beneficiary's first name in Chinese
Personal unique identifier number
Personal unique identifier type
Beneficiary's last name in Chinese
Personal mobile number
Account unique identifier of the recipient account used for payout processing. The account must be active and have customer_agreements.terms_and_conditions.service_agreement_type set to RECIPIENT (verify via Retrieve account details API).
Security question. Required when the email address is not registered with Interac e-Transfer autodeposit.
Security question answer. Required when the email address is not registered with Interac e-Transfer autodeposit.
Beneficiary's address details
Beneficiary's city
Beneficiary's country code (2-letter ISO 3166-2 country code)
Beneficiary's post code
Beneficiary's state
Beneficiary's street address
Beneficiary's bank account details where the payment will be credited
Account Currency
Account holder name of the beneficiary’s bank account
Bank country code (2-letter ISO 3166-2 country code)
The beneficiary’s account name known in the payment system. This is only supported in some regions and transfer methods. See detailed definitions in the Payouts Product Docs .
Account number, mostly for non-european countries, either account_number or iban should be filled
Routing code type
Routing code sub type
Routing code value
Routing code sub type value
bank account type
Specific branch of bank account
Bank name of the beneficiary's bank account
Bank State
Bank street address
The mobile number tied to the Beneficiary's bank account
Fingerprint of current beneficiary's bank account
International bank account number, mostly for european countries
Bank name of the beneficiary's intermediary bank
Intermediary bank SWIFT code / BIC,Should contain alphanumeric characters only, Should be a valid and supported SWIFT code / BIC
Which clearing system should be used for this local bank transfer.
Please refer to our payout guide for details about each option.
We suggest explicitly specifying this value, however if it's not provided we will select a default (using the specified account routing type and/or what's most often the best option).
Bank swift code
Company name of the beneficiary
beneficiary date of birth
Beneficiary's digital wallet details where the payment will be credited
Account holder name of the beneficiary’s digital wallet
Account identifier type of the beneficiary’s digital wallet
Account identifier value of the beneficiary’s digital wallet
Service provider of the beneficiary's digital wallet
Digital wallet country code (2-letter ISO 3166-2 country code)
Entity type of the beneficiary
First name of the beneficiary
Last name of the beneficiary
Type of the beneficiary, indicating the type of account or method through which the beneficiary receives funds
beneficiary_id of the beneficiary contact used to create this payment
The time this payment request was created
Actual payout dispatch date. Payouts are dispatched at this date in actual processing. This date could be later than the payment date.
Empty unless the payment is in an error state
Empty unless the payment is in an error state
The payment fee (in source_currency) for sending this payment
The payment fee currency. This should always equal to the source_currency
Denotes whether PAYER / BENEFICIARY will be liable for the the payment fee. Defaults to PAYER unless field is populated in the request
The funding information of this payment.
The funding status of this payment. Please see details in Funding Statuses .
Can be one of: FASTER_DIRECT_DEBIT, DIRECT_DEBIT.
Details about why the funding has failed. Only present when the funding is in a failure state.
Error code (details can be found here ).
A set of original information received from the local clearing system.
The original error code received from the local clearing system.
The local clearing system used for the direct debit deposit. Possible values are AU_BECS, US_ACH, GB_BACS, EU_SEPA.
The original error message received from the local clearing system.
Empty unless the funding is in an error state.
The id of the funding source, it can be null if using a wallet.
The time this payment request was last updated
A set of key-value pairs for storing your own data together with the payment.
Details of the payer
Payer's address details
Payer's country code (2-letter ISO 3166-2 country code)
Payer's city
Payer's post code
Payer's state
Payer's street address
Entity type of the payer
Additional information about the payer
Business registration number
Type of business as registered with the local government authority
Unique identifier of the person in your company
Personal email
Personal unique identifier number
Company name of the payer
Payer's date of birth
First name of the payer
Last name of the payer
payer_id of the payer contact used to create this payment
Amount to be paid
Currency the payment should be made in (3-letter ISO-4217 code)
Date when payment should be made (Copied from the request if specified)
Returned payment_id that can be used to query the status of the payment
Copied from the request if specified. Otherwise the system will populate this field automatically
Reason for the payment instruction
Bank payment reference to be shown on beneficiary's bank transaction history
Additional information about this payment, which will not be passed to the beneficiary.
A unique request identifier specified in the payment request
Short payment reference for support purposes
Amount to be received
Copied from the request if specified
The payment status. Please see details in Payout Statuses .
(For SWIFT payments only), specify who should bear SWIFT charges, either SHARED (default) or PAYER
Underlying conversion_id (if source_currency is different from payment_currency)
| Error status | Description |
|---|---|
| 400 | invalid_argument |
| 401 | credentials_invalid |
| 500 | service_unavailable |
$curl --request POST \> --url 'https://api-demo.airwallex.com/api/v1/simulation/payments/payment_id/transition' \> --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \> --header 'Content-Type: application/json' \> --data '{> "failure_type": "INVALID_ACCOUNT_NAME_OR_NUMBER",> "next_status": "DISPATCHED">}'
1{2 "amount_beneficiary_receives": 99996,3 "amount_payer_pays": 10004,4 "application_fee_options": [5 {6 "amount": "5",7 "currency": "AUD",8 "percentage": "0.1",9 "source_type": "TRANSFER",10 "type": "FIXED"11 }12 ],13 "application_fees": [14 {15 "amount": "5",16 "currency": "AUD",17 "source_type": "PAYMENT"18 }19 ],20 "batch_payment_id": "d9df6d02-4116-4376-82c7-064159cc878e",21 "beneficiary": {22 "additional_info": {23 "business_area": "Travel",24 "business_phone_number": "689342234",25 "business_registration_number": "IT593003",26 "external_identifier": "<string>",27 "legal_rep_bank_account_number": "44250100003700000000",28 "legal_rep_first_name_in_chinese": "小芳",29 "legal_rep_id_number": "110108199304203520",30 "legal_rep_last_name_in_chinese": "刘",31 "legal_rep_mobile_number": "13651362890",32 "personal_email": "[email protected]",33 "personal_first_name_in_chinese": "大明",34 "personal_id_number": "1234567890",35 "personal_id_type": "NATIONAL_ID",36 "personal_last_name_in_chinese": "李",37 "personal_mobile_number": "13651362890",38 "recipient_account_id": "<string>",39 "security_question": "What is the name of my second puppy?",40 "security_question_answer": "Scooby Doo"41 },42 "address": {43 "city": "Melbourne",44 "country_code": "AU",45 "postcode": "3000",46 "state": "VIC",47 "street_address": "15 William Street"48 },49 "bank_details": {50 "account_currency": "AUD",51 "account_name": "Lee Da Ming",52 "account_name_alias": "Lee D M",53 "account_number": "12750852",54 "account_routing_type1": "bsb",55 "account_routing_type2": "sort_code",56 "account_routing_value1": "083064",57 "account_routing_value2": "123456",58 "bank_account_category": "Checking,Savings,Vista,Maestra",59 "bank_branch": "Melbourne",60 "bank_country_code": "AU",61 "bank_name": "National Australia Bank",62 "bank_state": "<string>",63 "bank_street_address": "500 Bourke Street, Melbourne 3000, Australia",64 "binding_mobile_number": "654897612345",65 "fingerprint": "2e99758548972a8e8822ad47fa1017ff72f06f3ff6a016851f45c398732bc50c",66 "iban": "ES8023100001180000012345",67 "intermediary_bank_name": "National Australia Bank",68 "intermediary_bank_swift_code": "CTBAAU2S",69 "local_clearing_system": "ACH",70 "swift_code": "CTBAAU2S"71 },72 "company_name": "Complete Concrete Pty Ltd",73 "date_of_birth": "1976-08-26",74 "digital_wallet": {75 "account_name": "John Walker Corporation",76 "country_code": "US",77 "id_type": "account_number",78 "id_value": "1033106816639334",79 "provider": "AIRWALLEX"80 },81 "entity_type": "COMPANY",82 "first_name": "John",83 "last_name": "Walker",84 "type": "<string>"85 },86 "beneficiary_id": "<uuid>",87 "created_at": "2017-03-22T16:08:02+1100",88 "dispatch_date": "2017-03-29",89 "failure_reason": "Insufficient funds",90 "failure_type": "UNKNOWN",91 "fee_amount": 4,92 "fee_currency": "AUD",93 "fee_paid_by": "PAYER",94 "funding": {95 "deposit_type": "DIRECT_DEBIT",96 "failure_details": {97 "code": "insufficient_funds",98 "iso_code": "AM04",99 "provider_failure_details": {100 "code": "R01",101 "local_clearing_system": "US_ACH",102 "message": "INSUFFICIENT FUNDS"103 }104 },105 "failure_reason": "regulatory_reason",106 "funding_source_id": "b3856846-31b0-44d8-855d-e0eedf532282",107 "status": "FUNDED"108 },109 "last_updated_at": "2017-03-24T18:00:02+1100",110 "metadata": {111 "order_id": "0123456789"112 },113 "payer": {114 "additional_info": {115 "business_registration_number": "EU300503",116 "business_registration_type": "Partnership",117 "external_id": "1234567890",118 "personal_email": "[email protected]",119 "personal_id_number": "1234567890"120 },121 "address": {122 "city": "Melbourne",123 "country_code": "AU",124 "postcode": "3000",125 "state": "VIC",126 "street_address": "15 William Street"127 },128 "company_name": "Complete Concrete Pty Ltd",129 "date_of_birth": "1976-08-26",130 "entity_type": "COMPANY",131 "first_name": "James",132 "last_name": "Smith"133 },134 "payer_id": "<uuid>",135 "payment_amount": 10000,136 "payment_currency": "AUD",137 "payment_date": "2017-03-24",138 "payment_id": "d9af1614-a6a1-4d45-aae7-6858fc6d9ede",139 "payment_method": "SWIFT",140 "reason": "travel",141 "reference": "PMT1936398",142 "remarks": "Any information",143 "request_id": "7f687fe6-dcf4-4462-92fa-80335301d9d2",144 "short_reference_id": "20170322-9F6ML2",145 "source_amount": 10000,146 "source_currency": "CNY",147 "status": "PROCESSING",148 "swift_charge_option": "SHARED",149 "underlying_conversion_id": "d9af1614-a6a1-4d45-aae7-6858fc6d9ede"150}