Cancel or refund a card transfer
To use this endpoint from the browser, you’ll need to specify the
/accounts/{accountID}/transfers.write scope when generating a token.
POST
/transfers/{transferID}/reversals
|
|
Successfully initiated a reversal.
{
"createdOn": "2023-09-09T14:15:22Z",
"status": "completed"
}Successfully initiated a reversal but an error occurred while waiting for a synchronous response.
{
"cancellation": {
"createdOn": "2019-08-24T14:15:22Z",
"status": "pending"
},
"refund": {
"amount": {
"currency": "USD",
"value": 1204
},
"cardDetails": {
"completedOn": "2019-08-24T14:15:22Z",
"confirmedOn": "2019-08-24T14:15:22Z",
"failedOn": "2019-08-24T14:15:22Z",
"failureCode": "call-issuer",
"initiatedOn": "2019-08-24T14:15:22Z",
"settledOn": "2019-08-24T14:15:22Z",
"status": "initiated"
},
"createdOn": "2019-08-24T14:15:22Z",
"failureCode": "call-issuer",
"refundID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
"status": "failed",
"updatedOn": "2019-08-24T14:15:22Z"
}
}Reversal request failed, an error message will be available in the response body.
{
"error": "reversal request failed, please try again with a new idempotency key"
}Attempted to initiate a reversal using a duplicate X-Idempotency-Key header.
{
"cancellation": {
"createdOn": "2019-08-24T14:15:22Z",
"status": "pending"
},
"refund": {
"amount": {
"currency": "USD",
"value": 1204
},
"cardDetails": {
"completedOn": "2019-08-24T14:15:22Z",
"confirmedOn": "2019-08-24T14:15:22Z",
"failedOn": "2019-08-24T14:15:22Z",
"failureCode": "call-issuer",
"initiatedOn": "2019-08-24T14:15:22Z",
"settledOn": "2019-08-24T14:15:22Z",
"status": "initiated"
},
"createdOn": "2019-08-24T14:15:22Z",
"failureCode": "call-issuer",
"refundID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43",
"status": "failed",
"updatedOn": "2019-08-24T14:15:22Z"
}
}The request body could not be processed.
Request was refused due to rate limiting.
Response headers
X-Retry-In
string
<duration>
How long (in milliseconds) to wait until able to retry the request.
Headers
X-Idempotency-Key
string
<uuid>
required
Prevents duplicate reversals from being created.
Path parameters
transferID
string
<uuid>
required
Identifier for the transfer.
Body
application/json
amount
integer<int64>
Amount to reverse in cents. If null, the original transfer’s full amount will be reversed. Partial amounts will automatically trigger a refund instead of a cancellation.
Response
application/json
cancellation
object
Show child attributes
createdOn
string<date-time>
<=24 characters
status
string<enum>
Cancellation status.
Possible values:
pending,
completed
refund
object
Details of a card refund.
Show child attributes
amount
object
A representation of money containing an integer value and its currency.
Show child attributes
currency
string
<=3 characters
Pattern
A 3-letter ISO 4217 currency code.
value
integer<int64>
Quantity in the smallest unit of the specified currency. In USD this is cents, so $12.04 is 1204 and $0.99 would be 99.
cardDetails
object
Show child attributes
completedOn
string<date-time>
<=24 characters
confirmedOn
string<date-time>
<=24 characters
failedOn
string<date-time>
<=24 characters
failureCode
string<enum>
Possible values:
call-issuer,
do-not-honor,
processing-error,
invalid-transaction,
invalid-amount,
no-such-issuer,
reenter-transaction,
cvv-mismatch,
lost-or-stolen,
insufficient-funds,
invalid-card-number,
invalid-merchant,
expired-card,
incorrect-pin,
transaction-not-allowed,
suspected-fraud,
amount-limit-exceeded,
velocity-limit-exceeded,
revocation-of-authorization,
card-not-activated,
issuer-not-available,
could-not-route,
cardholder-account-closed,
unknown-issue,
duplicate-transaction
initiatedOn
string<date-time>
<=24 characters
settledOn
string<date-time>
<=24 characters
status
string<enum>
Status of the refund.
Possible values:
initiated,
confirmed,
settled,
failed,
completed
createdOn
string<date-time>
<=24 characters
failureCode
string
deprecated
This field is deprecated and will be removed in December 2023.
Possible values:
call-issuer,
do-not-honor,
processing-error,
invalid-transaction,
invalid-amount,
no-such-issuer,
reenter-transaction,
cvv-mismatch,
lost-or-stolen,
insufficient-funds,
invalid-card-number,
invalid-merchant,
expired-card,
incorrect-pin,
transaction-not-allowed,
suspected-fraud,
amount-limit-exceeded,
velocity-limit-exceeded,
revocation-of-authorization,
card-not-activated,
issuer-not-available,
could-not-route,
cardholder-account-closed,
unknown-issue,
duplicate-transaction
refundID
string<uuid>
<=36 characters
Pattern
UUID v4
status
string<enum>
Possible values:
created,
pending,
completed,
failed
updatedOn
string<date-time>
<=24 characters