Generate card issuing transactions
Why do we want generate a card issuing transaction?
Generating a card issuing transaction triggers all production scenarios in the demo environment, including:
- Transaction can be retrieved via API endpoints: get transactions for a single card API, get single transaction API, and get list of financial transactions API.
- Issuing and remote authorization webhook events are triggered.
What production scenario are we simulating?
This simulation API generates transactions for Airwallex issued cards. A platform account can call this API on behalf of a connected account using the x-on-behalf-of
header.
Payments status transition simulation endpoint schema
Most issuing transactions are two-step transactions which involve the creation of a transaction, and the capturing of the approved payment from your multi-currency wallet. There are two simulation endpoints that emulate this process:
- Create card issuing transaction (POST /api/v1/simulation/issuing/create): Create a transaction to be approved or failed based on the issuing authorization controls of your account.. For example, if you set a limit in $100 of spending on your account and you attempt to make a $110 transaction, then this payment will fail. This endpoint simulates the production behaviour of our payment networks.
- Capture card issuing transaction (POST /api/v1/simulation/issuing/{transaction_id}/capture): If a transaction is in the approved state, then this endpoint deducats the balance from your multi-currency wallet balance.
Create card issuing transaction (POST /api/v1/simulation/issuing/create)
POST /api/v1/simulation/issuing/create
The request body supports in the following parameters:
- Provide either the card_id or card_number. If both are provided, then card_id will be prioritised.
- card_id (string, optional): The card_id is the unique identifier of an Airwallex issued card. You can get the card_id from our Get all cards API API endpoint. Alternatively, you can select the card_id from the URL on the webapp after selecting a card (https://demo.airwallex.com/app1/cards/myCards/83bf74e8-2419-4c59-821e-83735c704140 ). If your account does not own the card then the transaction will fail.
- card_number (string, optional): 16-digit card number. If your account does not own the card then the transaction will fail.
- transaction_amount (number, required): Transaction amount that will be spent on the card. Maximum amount is $9,999.99.
- transaction_currency (string, required): Currency code, only including
USD
,AUD
,GBP
,EUR
,CAD
,JPY
,HKD
,CNY
,SGD
,NZD
, andCHF
. - Merchant_category_code (string, optional): 4-digit Visa MCC (learn more ).
- auth_code (string, optional): 6-digit authorization code for transaction for testing. Otherwise, authorization code be generated if not provided.
- merchant_info (string, optional): Description of merchant with an exact string length of 43 characters. If nothing is provided, ‘CARD_TX_GENERATOR TEST’ will be the default value.
Example request body:
curl --location --request POST 'https://api-demo.airwallex.com/api/v1/simulation/issuing/create' \
--header 'Authorization: Bearer [jwt_token]' \
--header 'Content-Type: application/json' \
--data-raw '{
"card_id": "be816f8f-e9b1-4db9-9b5e-5a0c33a62099",
"card_number": null,
"transaction_amount": 1999,
"transaction_currency": "AUD",
"merchant_info": "Test transaction today 999"
}'
The response will replicate the response structure of an issuing transaction schema as seen in the get single transaction API schema endpoint.
{
"transaction_id": "5d6f2fa3-a6c6-4954-ab79-9f5a79274be5",
"transaction_type": "AUTHORIZATION",
"transaction_date": 1648599979509,
"posted_date": 1648599979509,
"card_id": "be816f8f-e9b1-4db9-9b5e-5a0c33a62099",
"transaction_amount": -1999,
"transaction_currency": "AUD",
"billing_amount": -1999,
"billing_currency": "AUD",
"merchant": {
"name": "Test transaction today 99",
"city": "9____________",
"country": "_____",
"category_code": "7531"
},
"auth_code": "286174",
"retrieval_ref": "668207078866",
"masked_card_number": "************2987",
"status": "PENDING",
"card_nickname": "",
"network_transaction_id": "0437765251063887"
}
Capture card issuing transaction (POST /api/v1/simulation/issuing/capture)
POST /api/v1/simulation/issuing/{transaction_id}/capture
Example request body:
curl --location --request POST 'https://api-demo.airwallex.com/api/v1/simulation/issuing/5d6f2fa3-a6c6-4954-ab79-9f5a79274be5/capture' \
--header 'Authorization: Bearer [jwt_token]'
Example response body:
{
"transaction_id": "93182aca-9173-4fb9-8937-59e5331103db",
"transaction_type": "CLEARING",
"transaction_date": 1648599979972,
"posted_date": 1648599992814,
"card_id": "be816f8f-e9b1-4db9-9b5e-5a0c33a62099",
"transaction_amount": -1999,
"transaction_currency": "AUD",
"billing_amount": -1999,
"billing_currency": "AUD",
"merchant": {
"name": "CARD_TX_GENERATOR REMOT",
"city": "E AUTH TEST",
"country": "AWX",
"category_code": "7531"
},
"auth_code": "737341",
"retrieval_ref": "100210002585",
"masked_card_number": "************2987",
"status": "APPROVED",
"card_nickname": "",
"network_transaction_id": "0437765251063887"
}
How to use the Issuing Transaction Simulation API?
The payment status transition simulation endpoint works with Airwallex public APIs.
Step 1: Use our authentication endpoint API and obtain an access token to call our API endpoints.
Sample request:
curl --location --request POST 'https://api-demo.airwallex.com/api/v1/authentication/login' \
--header 'Content-Type: application/json' \
--header 'x-client-id: [client_id]' \
--header 'x-api-key: [api_key]' \
--header 'Authorization: Bearer [jwt_token] \
--data-raw ''
Sample response:
{
"expires_at": "2022-02-22T06:48:39+0000",
"token": "[jwt_token]"
}
Step 2: Create an issuing transaction with the create issuing transaction simulation endpoint. It will be approved or failed depending on the issuing authorization controls. The response will replicate the response structure of an issuing transaction schema as seen in the get single transaction schema API endpoint.
Example request body:
curl --location --request POST 'https://api-demo.airwallex.com/api/v1/simulation/issuing/create' \
--header 'Authorization: Bearer [jwt_token]' \
--header 'Content-Type: application/json' \
--data-raw '{
"card_id": "be816f8f-e9b1-4db9-9b5e-5a0c33a62099",
"card_number": null,
"transaction_amount": 1999,
"transaction_currency": "AUD",
"merchant_info": "Test transaction today 999"
}'
The response will replicate the response structure of an issuing transaction schema as seen in the get single transaction API schema endpoint.
{
"transaction_id": "5d6f2fa3-a6c6-4954-ab79-9f5a79274be5",
"transaction_type": "AUTHORIZATION",
"transaction_date": 1648599979509,
"posted_date": 1648599979509,
"card_id": "be816f8f-e9b1-4db9-9b5e-5a0c33a62099",
"transaction_amount": -1999,
"transaction_currency": "AUD",
"billing_amount": -1999,
"billing_currency": "AUD",
"merchant": {
"name": "Test transaction today 99",
"city": "9____________",
"country": "_____",
"category_code": "7531"
},
"auth_code": "286174",
"retrieval_ref": "668207078866",
"masked_card_number": "************2987",
"status": "PENDING",
"card_nickname": "",
"network_transaction_id": "0437765251063887"
}
Step 3: If the transaction has been approved, then the payment can be captured to deduct the value from your multi-currency wallet.
Example request body:
curl --location --request POST 'https://api-demo.airwallex.com/api/v1/simulation/issuing/5d6f2fa3-a6c6-4954-ab79-9f5a79274be5/capture' \
--header 'Authorization: Bearer [jwt_token]'
Example response body:
{
"transaction_id": "93182aca-9173-4fb9-8937-59e5331103db",
"transaction_type": "CLEARING",
"transaction_date": 1648599979972,
"posted_date": 1648599992814,
"card_id": "be816f8f-e9b1-4db9-9b5e-5a0c33a62099",
"transaction_amount": -1999,
"transaction_currency": "AUD",
"billing_amount": -1999,
"billing_currency": "AUD",
"merchant": {
"name": "CARD_TX_GENERATOR REMOT",
"city": "E AUTH TEST",
"country": "AWX",
"category_code": "7531"
},
"auth_code": "737341",
"retrieval_ref": "100210002585",
"masked_card_number": "************2987",
"status": "APPROVED",
"card_nickname": "",
"network_transaction_id": "0437765251063887"
}