Airwallex logo
Airwallex logoAirwallex logo

Refunds

Copy for LLMView as Markdown

The Refund API allows you to refund a succeeded payment back to the payment method used by your customer. The refund amount must be equal to or less than the amount specified in the original PaymentIntent/PaymentAttempt.

Multiple Refunds can be created until the full amount is refunded.

Data Retention Policy: You can query Refund resources for a maximum of 2 years since creation.

Endpoints
POST /api/v1/pa/refunds/create
GET /api/v1/pa/refunds/{id}
GET /api/v1/pa/refunds

Create a refund

POST /api/v1/pa/refunds/create

Copy for LLMView as Markdown

Create a Refund against a PaymentIntent/PaymentAttempt.

Request body
amountnumber

Amount of the Refund. If not specified, it will be same as the remaining amount that has been captured but not yet refunded. Please refer to supported currencies for supported minor units.

metadataobject

A set of key-value pairs that you can attach to the Refund. You can specify up to 50 keys with key names up to 50 characters long and values up to 500 characters long.

payment_attempt_idstring

PaymentAttempt unique identifier against which this Refund is created. Either this or the payment_intent_id must be provided.

payment_intent_idstring

PaymentIntent unique identifier against which this Refund is created. Either this or the payment_attempt_id must be provided.

reasonstring

Reason of the Refund. Maximum length is 128.

request_idrequiredstring

Unique request identifier specified by the merchant. Maximum length is 64.

Response body - 201 Created
acquirer_reference_numberstring

A unique number that tags a credit or debit card transaction when it goes from the merchant's bank through to the cardholder's bank.

amountnumber

Amount of the Refund

created_atstring

Time at which the Refund was created

currencystring

Currency of the Refund

failure_detailsobject

Failure details. Only applicable when status is FAILED.

failure_details.codestring

The failure code returned by Airwallex

failure_details.detailsobject

Additional details that may include original_response_code, original_response_message from provider, and other contextual information such as card details, risk factors, etc. depending on the specific error code.

failure_details.messagestring

The failure description.

failure_details.trace_idstring

The unique identifier for tracing the failure.

idstring

Unique identifier for the Refund

metadataobject

A set of key-value pairs that you can attach to the Refund. You can specify up to 50 keys with key names up to 50 characters long and values up to 500 characters long.

payment_attempt_idstring

Unique identifier of PaymentAttempt on which the Refund is created

payment_intent_idstring

Unique identifier of PaymentIntent on which the Refund is created

reasonstring

Reason of the Refund

request_idstring

Unique request identifier specified by the merchant in the last operation

statusstring

Status of the Refund. One of RECEIVED, ACCEPTED, SETTLED or FAILED

  • RECEIVED: The Refund is created, which means the requested refund amount is valid and the payment is not in dispute.
  • ACCEPTED: The Refund has been accepted by the payment method provider and can be considered completed.
  • SETTLED: The Refund has been reconciled and will show up in the Airwallex settlement report.
  • FAILED: The Refund has been rejected, which can be caused by the insufficient Airwallex receivable/available balance, or by the provider for more channel-specific reasons.
updated_atstring

Last time at which the Refund was updated

Errors
Error statusDescription
400

Bad Request. Possible error codes: validation_error, duplicate_request, invalid_status_for_operation, amount_above_limit, operation_not_supported, resource_not_found(invalid payment_attempt_id or payment_intent_id)

401

Unauthorized. Possible error codes: unauthorized

403

Forbidden

404

Not Found. Possible error codes: not_found(invalid url)

500

Server Error. Possible error codes: internal_error

POST /api/v1/pa/refunds/create
$curl --request POST \
>  --url 'https://api-demo.airwallex.com/api/v1/pa/refunds/create' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json' \
>  --data '{
>  "payment_attempt_id": "att_hkpdskz7vg1xc7uscdj",
>  "reason": "Return goods",
>  "amount": 10,
>  "request_id": "962dbd83-5e7b-4185-b668-596834395c12"
>}'
Response (201 Created)
1{
2  "id": "rfd_hkpdbybkch3ovunwjy1_1raukh",
3  "request_id": "962dbd83-5e7b-4185-b668-596834395c12",
4  "payment_intent_id": "int_hkpdskz7vg1xc7uscdj",
5  "payment_attempt_id": "att_hkpdskz7vg1xc7uscdj",
6  "amount": 10,
7  "currency": "USD",
8  "reason": "Return goods",
9  "status": "RECEIVED",
10  "created_at": "2021-01-31T06:57:10+00:00",
11  "updated_at": "2021-01-31T07:01:10+00:00"
12}
Was this section helpful?

Retrieve a refund

GET /api/v1/pa/refunds/{id}

Copy for LLMView as Markdown

Retrieve a Refund by unique identifier

Parameters
idrequiredstring

Refund unique identifier

Response body - 200 OK
acquirer_reference_numberstring

A unique number that tags a credit or debit card transaction when it goes from the merchant's bank through to the cardholder's bank.

amountnumber

Amount of the Refund

created_atstring

Time at which the Refund was created

currencystring

Currency of the Refund

failure_detailsobject

Failure details. Only applicable when status is FAILED.

failure_details.codestring

The failure code returned by Airwallex

failure_details.detailsobject

Additional details that may include original_response_code, original_response_message from provider, and other contextual information such as card details, risk factors, etc. depending on the specific error code.

failure_details.messagestring

The failure description.

failure_details.trace_idstring

The unique identifier for tracing the failure.

idstring

Unique identifier for the Refund

metadataobject

A set of key-value pairs that you can attach to the Refund. You can specify up to 50 keys with key names up to 50 characters long and values up to 500 characters long.

payment_attempt_idstring

Unique identifier of PaymentAttempt on which the Refund is created

payment_intent_idstring

Unique identifier of PaymentIntent on which the Refund is created

reasonstring

Reason of the Refund

request_idstring

Unique request identifier specified by the merchant in the last operation

statusstring

Status of the Refund. One of RECEIVED, ACCEPTED, SETTLED or FAILED

  • RECEIVED: The Refund is created, which means the requested refund amount is valid and the payment is not in dispute.
  • ACCEPTED: The Refund has been accepted by the payment method provider and can be considered completed.
  • SETTLED: The Refund has been reconciled and will show up in the Airwallex settlement report.
  • FAILED: The Refund has been rejected, which can be caused by the insufficient Airwallex receivable/available balance, or by the provider for more channel-specific reasons.
updated_atstring

Last time at which the Refund was updated

Errors
Error statusDescription
400

Bad Request. Possible error codes: validation_error

401

Unauthorized. Possible error codes: unauthorized

403

Forbidden

404

Not Found. Possible error codes: not_found(invalid url), resource_not_found

500

Server Error. Possible error codes: internal_error

GET /api/v1/pa/refunds/{id}
$curl --request GET \
>  --url 'https://api-demo.airwallex.com/api/v1/pa/refunds/rfd_hkpdbybkch3ovunwjy1_1raukh' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'
Response (200 OK)
1{
2  "id": "rfd_hkpdbybkch3ovunwjy1_1raukh",
3  "request_id": "962dbd83-5e7b-4185-b668-596834395c12",
4  "payment_intent_id": "int_hkpdskz7vg1xc7uscdj",
5  "payment_attempt_id": "att_hkpdskz7vg1xc7uscdj",
6  "amount": 10,
7  "currency": "USD",
8  "reason": "Return goods",
9  "status": "ACCEPTED",
10  "created_at": "2021-01-31T06:57:10+00:00",
11  "updated_at": "2021-01-31T07:01:10+00:00"
12}
Was this section helpful?

Get list of refunds

GET /api/v1/pa/refunds

Copy for LLMView as Markdown

Retrieve list of Refunds.

Parameters
currencystring

Refund currency

from_created_atstring

The start time of created_at in ISO8601 format. The timestamp must include an explicit timezone (e.g. Z or -04:00).

page_numinteger

Page number starting from 0

page_sizeinteger

Number of Refunds to be listed per page. Default value is 10. Maximum is 1000. The value greater than the maximum will be capped to the maximum.

payment_attempt_idstring

PaymentAttempt unique identifier of the Refunds

payment_intent_idstring

PaymentIntent unique identifier of the Refunds

statusstring

Refund status

to_created_atstring

The end time of created_at in ISO8601 format. The timestamp must include an explicit timezone (e.g. Z or -04:00).

Response body - 200 OK
has_moreboolean

A flag which identifies whether there are more results.

itemsarray

List items

items.acquirer_reference_numberstring

A unique number that tags a credit or debit card transaction when it goes from the merchant's bank through to the cardholder's bank.

items.amountnumber

Amount of the Refund

items.created_atstring

Time at which the Refund was created

items.currencystring

Currency of the Refund

items.failure_detailsobject

Failure details. Only applicable when status is FAILED.

items.failure_details.codestring

The failure code returned by Airwallex

items.failure_details.detailsobject

Additional details that may include original_response_code, original_response_message from provider, and other contextual information such as card details, risk factors, etc. depending on the specific error code.

items.failure_details.messagestring

The failure description.

items.failure_details.trace_idstring

The unique identifier for tracing the failure.

items.idstring

Unique identifier for the Refund

items.metadataobject

A set of key-value pairs that you can attach to the Refund. You can specify up to 50 keys with key names up to 50 characters long and values up to 500 characters long.

items.payment_attempt_idstring

Unique identifier of PaymentAttempt on which the Refund is created

items.payment_intent_idstring

Unique identifier of PaymentIntent on which the Refund is created

items.reasonstring

Reason of the Refund

items.request_idstring

Unique request identifier specified by the merchant in the last operation

items.statusstring

Status of the Refund. One of RECEIVED, ACCEPTED, SETTLED or FAILED

  • RECEIVED: The Refund is created, which means the requested refund amount is valid and the payment is not in dispute.
  • ACCEPTED: The Refund has been accepted by the payment method provider and can be considered completed.
  • SETTLED: The Refund has been reconciled and will show up in the Airwallex settlement report.
  • FAILED: The Refund has been rejected, which can be caused by the insufficient Airwallex receivable/available balance, or by the provider for more channel-specific reasons.
items.updated_atstring

Last time at which the Refund was updated

Errors
Error statusDescription
400

Bad Request. Possible error codes: validation_error

401

Unauthorized. Possible error codes: unauthorized

403

Forbidden

404

Not Found. Possible error codes: not_found(invalid url)

500

Server Error. Possible error codes: internal_error

GET /api/v1/pa/refunds
$curl --request GET \
>  --url 'https://api-demo.airwallex.com/api/v1/pa/refunds' \
>  --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
>  --header 'Content-Type: application/json'
Response (200 OK)
1{
2  "has_more": false,
3  "items": [
4    {
5      "id": "rfd_hkpdbybkch3ovunwjy1_1raukh",
6      "request_id": "962dbd83-5e7b-4185-b668-596834395c12",
7      "payment_intent_id": "int_hkpdskz7vg1xc7uscdj",
8      "payment_attempt_id": "att_hkpdskz7vg1xc7uscdj",
9      "amount": 10,
10      "currency": "USD",
11      "reason": "Return goods",
12      "status": "SETTLED",
13      "created_at": "2021-01-31T06:57:10+00:00",
14      "updated_at": "2021-01-31T07:01:10+00:00"
15    }
16  ]
17}
Was this section helpful?