Airwallex logo

API Integration

In addition to the user interface in the webapp, Airwallex offers merchants an API solution for our Pay By Link product. Pay by Link enables merchants to issue payment links (URL or QR code) to share with their customers and accept payments very easily with a redirect to our secure hosted payment page. Merchants can customize the payment links, choose the amount, the currency, and the expiration date. Merchants can also choose to make the link reusable or one-off.

Below are the main steps to generate the payment links:

Workflow

Our API allows merchants to:

FeaturesPay By Link API
Create links
Update a payment link
Get the payments links the merchant created
Activate payment links
Deactivate payments links
Delete payment links
Get link information
Handle errors with relevant error codes

Our Pay By Link API is a typical REST API with JSON. To get started with our API, merchants will need their account ID provided at onboarding to proceed.

Overall Flow

PBL-overall flow

In order to start using the Merchant Links API, merchants will need to complete its configuration with the Merchant Config API first. The first two steps should be complete in webapp. To proceed with the link creation, merchants will need to call the Merchant Links API.

Merchant Links API

This API is used for CRUD operations on payment links and allows merchants to perform the following actions described below.

  • Create Payment Link will allow merchants to generate payment links and choose among the following parameter: "code", “expiryDate", "reusable", "amount", "minAmount", "title", "description", "merchantRef"
  • Update Payment Link will allow merchants to make changes to an existing payment link.
  • Retrieve Merchant's Payment Links will allow merchants to obtain the payments details made from a given linkID.
  • Get list of PaymentLinks will return the links that a merchant has created previously. This endpoint will return all links that are not DELETED.
  • Activate Link will allow merchants to activate a given payment link ID.
  • Deactivate Link will allow merchants to deactivate a given payment link ID.
  • Delete Link will allow merchants to delete a given payment link ID.

Send a PaymentLink

This endpoint of the main API is used to send emails to merchants and shoppers. There are two different emails that can be generated as part of the Pay by Link product. One email is sent to notify merchants whenever there is a successful payment from a payment link previously created by the merchant. The second link is sent to the shopper as a payment receipt and will contain the main payment details.

Please note that merchants can also subscribe to webhooks to receive notifications about successful payments (payment_intent.succeeded). See Notifications and Webhooks .

Error Processing

In general, all API calls can be failed and in this case, merchants will get a specific HTTP status and error code and error message in the body.

Error codeError description
OTHER_ERRORsome other errors, it should contain trace-id in the message for debug
INPUT_MISSINGrequested input field is missing
INPUT_TOO_LONGrequested input field is too long
CODE_BAD_SYMBOLSrequested code had unsupported symbols
CODE_NOT_FOUNDrequested code not found
CODE_NOT_UNIQUErequested code not unique in the system
EMAIL_NOT_VALIDrequested shopper email is not valid or is too long
BAD_EXPIRYexpiry date in the past
ACTIVATION_FAILEDcan't activate link (current status not DEACTIVATED)
DEACTIVATION_FAILEDcan't deactivate link (current status not ACTIVE)
INTENT_CREATEDintent already created for one-time links
LINK_FORBIDDENlink belongs to another merchant
LINK_NOT_FOUNDlink not found
LINK_NOT_ACTIVElink not active
CONFIG_NOT_FOUNDmerchant config not found
CORE_FAILEDpayment core failed to create intent
CONFIG_CENTER_FAILEDconfig centre failed to provide merchant available currency
AMOUNT_WRONGrequested amount is wrong (less than min or other currency)
MERCHANT_NOT_ENABLED_PAmerchant config is not full in config-centre or no active PMPs configured
HEADER_MISSINGmissing required header
ARGUMENT_MISMATCHfailed to deserialize JSON from the body