Cancel a conversion

Use this step-by-step guide to amend an existing unsettled conversion. Only conversion cancellations are currently supported using the Conversion amendments API.

Before you begin

• Obtain your access token API by authenticating to Airwallex using your unique Client ID and API key. You will need the access token to make API calls.
• Both pre-funding mode and post-funding mode are supported for conversion amendments. Contact your Airwallex Account Manager to change your funding mode. For more information on funding modes, see Funding and Settlement models.
• Follow the Create a conversion tutorial to create a future-dated conversion and save the conversion_id returned in the response.

Step 1: (Optional) Create an indicative amendment quote

Call Create an amendment quote API to retrieve an indicative financial adjustment resulting from the amendment.

Example request

Shell
1curl --request POST \
2--url 'https://api-demo.airwallex.com/api/v1/conversion_amendments/quote' \
3--header 'Content-Type: application/json' \
4--header 'Authorization: Bearer <your_bearer_token>' \
5--data '{ 
6  "charge_currency": "USD", 
7  "conversion_id": "a74317c0-ed25-4e6e-82b2-82baa5cd9c20", 
8  "metadata": { 
9    "reason": "rejected_trade_attempt_968059869" 
10  }, 
11  "request_id": "a08c0f2f-3f26-4443-b5df-fad15582eb94", 
12  "type": "CANCEL" 
13}'

Example response

JSON
1{
2  "charges": [
3    {
4      "amount": 1.36,
5      "awx_rate": 1.383429,
6      "client_rate": 1.390346,
7      "currency": "USD",
8      "currency_pair": "GBPUSD",
9      "type": "FEE"
10    }
11  ],
12  "conversion_id": "a74317c0-ed25-4e6e-82b2-82baa5cd9c20",
13  "metadata": {
14    "reason": "rejected_trade_attempt_968059869"
15  },
16  "request_id": "a08c0f2f-3f26-4443-b5df-fad15582eb94",
17  "short_reference_id": "C220407-AF3GJ9F",
18  "type": "CANCEL"
19}

Step 2: Create an amendment

Call Create an amendment API API to create a conversion amendment on a booked but unsettled conversion. Provide the conversion_id and specify type as CANCEL to cancel the conversion.

The financial adjustment resulting from the amendment is returned in the charges object. A charge type will either be a FEE or CREDIT. A FEE will debit your account with any associated FX loss and a CREDIT will credit your account with any associated FX Gain. See Conversion Amendments for more information on how this is calculated.

If the response returns any errors, see Error codes to learn about the troubleshooting steps.

Example request

Shell
1curl --request POST \
2--url 'https://api-demo.airwallex.com/api/v1/conversion_amendments/create' \
3--header 'Content-Type: application/json' \
4--header 'Authorization: Bearer <your_bearer_token>' \
5--data '{
6  "charge_currency": "USD", 
7  "conversion_id": "a74317c0-ed25-4e6e-82b2-82baa5cd9c20", 
8  "metadata": { 
9    "reason": "rejected_trade_attempt_968059869" 
10  }, 
11  "request_id": "a08c0f2f-3f26-4443-b5df-fad15582eb94", 
12  "type": "CANCEL" 
13}'

Example response

JSON
1{
2  "amendment_id": "9593ca22-8933-4585-9a15-078c8ce654ad",
3  "charges": [
4    {
5      "amount": 1.36,
6      "awx_rate": 1.383429,
7      "client_rate": 1.390346,
8      "currency": "USD",
9      "currency_pair": "GBPUSD",
10      "type": "FEE"
11    }
12  ],
13  "conversion_id": "a74317c0-ed25-4e6e-82b2-82baa5cd9c20",
14  "created_at": "2021-07-14T06:09:39+0000",
15  "metadata": {
16    "reason": "rejected_trade_attempt_968059869"
17  },
18  "request_id": "a08c0f2f-3f26-4443-b5df-fad15582eb94",
19  "short_reference_id": "C220407-AF3GJ9F",
20  "type": "CANCEL",
21  "updated_at": "2021-07-14T06:09:39+0000"
22}

Step 3: Retrieve an amendment

You can retrieve details of a specific conversion amendment anytime using Retrieve an amendment API. If you want to retrieve details of all conversion amendments associated with your account, see List all amendments API.

Example request

Shell
1curl --request GET \
2--url 'https://api-demo.airwallex.com/api/v1/conversion_amendments/9593ca22-8933-4585-9a15-078c8ce654ad' \
3--header 'Authorization: Bearer <your_bearer_token>'

Example response

JSON
1{
2  "amendment_id": "9593ca22-8933-4585-9a15-078c8ce654ad",
3  "charges": [
4    {
5      "amount": 1.36,
6      "awx_rate": 1.383429,
7      "client_rate": 1.390346,
8      "currency": "USD",
9      "currency_pair": "GBPUSD",
10      "type": "FEE"
11    }
12  ],
13  "conversion_id": "a74317c0-ed25-4e6e-82b2-82baa5cd9c20",
14  "created_at": "2021-07-14T06:09:39+0000",
15  "metadata": {
16    "reason": "rejected_trade_attempt_968059869"
17  },
18  "request_id": "a08c0f2f-3f26-4443-b5df-fad15582eb94",
19  "short_reference_id": "C220407-AF3GJ9F",
20  "type": "CANCEL",
21  "updated_at": "2021-07-14T06:09:39+0000"
22}