Overview
A PaymentAuthCancelRequest message should be sent to cancel an authorization if an order is canceled. This removes any holds or pending charges on the customer's account.
An alternate request format, PaymentSettlementRequestList, groups several events together in a single message, and is intended for clients using the Webhooks Implementation for Asynchronous Messages. If you are using the Webhooks implemention, see Payment Authorization Cancel List Event, below.
URI Summary
| Action | URI Template | URI Example | Non-URI Request | Response |
|---|---|---|---|---|
| POST | /v[M.m]/stores/[StoreID]/ payments/auth/cancel/[TenderType].[format] |
/v1.0/stores/ABCXYZ/ payments/auth/cancel/VC.xml |
XML | 200 + XML response |
Tender Types
In the URI, use the appropriate Tender Types code for the transaction. This is generally the tender type that was originally used for the payment authorization that is being canceled. Tender types that can be used with this request include PY (PayPal), KL (Klarna), and various tender types that identify credit cards.
When submitting an authorization cancel for a digital wallet (including Apple Pay) transaction, do not use the DW tender type. Instead, use the specific tender type of the credit card used in this transaction. This value can be found in the TenderType field of the CreditCardAuthReply message that you received in response to the original digital wallet auth request.
Request Examples
The request is a PaymentAuthCancelRequest message.
Request with a Payment Account Number
Use this format for an authorization cancel request of a payment transaction that involves a card number, such as a credit card, private label credit card, or Apple Pay transaction.
<?xml version="1.0" encoding="UTF-8"?>
<PaymentAuthCancelRequest requestId="123" xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<PaymentContext>
<OrderId>12345</OrderId>
<PaymentAccountUniqueId isToken="true">4111110PASeK1111</PaymentAccountUniqueId>
</PaymentContext>
<Amount currencyCode="USD">100.00</Amount>
</PaymentAuthCancelRequest>Request without a Payment Account Number
Use this format for an authorization cancel request of a payment transaction without a card number, such as a PayPal or Klarna transaction.
<?xml version="1.0" encoding="UTF-8"?>
<PaymentAuthCancelRequest requestId="123" xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<PaymentContextBase>
<OrderId>12345</OrderId>
</PaymentContextBase>
<Amount currencyCode="USD">100.00</Amount>
</PaymentAuthCancelRequest>Request with a Reference Transaction Id
Use this format for an authorization cancel request when the authorization was created outside of Radial systems.
<?xml version="1.0" encoding="UTF-8"?>
<PaymentAuthCancelRequest requestId="123" xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<PaymentContextBase>
<OrderId>12345</OrderId>
</PaymentContextBase>
<Amount currencyCode="USD">100.00</Amount>
<ReferenceTransactionId>75a68dd9-8602-1a33-aab4-7705099786f0</ReferenceTransactionId>
</PaymentAuthCancelRequest>Request Elements
| Element | Required | Description | Type | Restriction |
|---|---|---|---|---|
| PaymentAuthCancelRequest/ @requestId |
Yes | RequestId is used to uniquely identify a request, including as part of idempotent duplicate request processing. The value must be unique. It is recommended to use a variant 4 UUID for the request id. The same request id should only be reused if a read timeout occurs when attempting to receive a response from the payment service, or the payment service responds with a fault response. In all other cases a new request id must be sent for retried requests, including responses such as Fail, Timeout or PaymentProcessorTimeout. | String | Max 40 characters |
| PaymentContext | Choice of PaymentContext (when a PaymentAccountUniqueId value is available) or PaymentContextBase (when a PaymentAccountUniqueId value is not available) | Sequence of OrderId, PaymentAccountUniqueId | ComplexType | |
| PaymentContext/ OrderId |
Yes (when PaymentContext is present) | Order ID | String | Max 20 characters |
| PaymentContext/ PaymentAccountUniqueId |
Yes (when PaymentContext is present) | Tokenized payment account number (for example, a credit card number) | String | Max 22 characters |
| PaymentContext/ PaymentAccountUniqueId/ @isToken |
Yes (when PaymentContext is present) | Attribute that indicates whether the payment account number is tokenized | String | true |
| PaymentContextBase | Choice of PaymentContext (when a PaymentAccountUniqueId value is available) or PaymentContextBase (when a PaymentAccountUniqueId value is not available) | Sequence of OrderId | ComplexType | |
| PaymentContextBase/ OrderId |
Yes (when PaymentContextBase is present) | Order ID | String | Max 20 characters |
| Amount | Yes | Amount authorized on the credit card | String |
Positive decimal, up to two decimal places (for example, 4.75) |
| Amount/ @currencyCode |
Yes | Attribute that indicates the type of currency used for the order | String | 3-character ISO 4217 code (for example, USD, CAD, EUR). See
http://en.wikipedia.org/ wiki/ISO_4217. |
| ReferenceTransactionId | No | External reference ID of the authorization to be cancelled | String | May not be empty if included. |
HTTP Reply
<?xml version="1.0" encoding="UTF-8"?>
<AckReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<Received/>
</AckReply>Queue Format
q.Payments.AuthCancels.Status.<RABBIT_MQ_USERNAME>
Response Example
The response is a PaymentAuthCancelReply message.
With a Payment Account Number)
<?xml version="1.0" encoding="UTF-8"?>
<PaymentAuthCancelReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<PaymentContext>
<OrderId>12345</OrderId>
<PaymentAccountUniqueId isToken="true">4111110PASeK1111</PaymentAccountUniqueId>
</PaymentContext>
<TenderType>VC</TenderType>
<ResponseCode>Success</ResponseCode>
<Amount currencyCode="USD">1.00</Amount>
<ExtendedResponseCode/>
<StoreId>ABCXYZ</StoreId>
</PaymentAuthCancelReply>Without a Payment Account Number
<?xml version="1.0" encoding="UTF-8"?>
<PaymentAuthCancelReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<PaymentContextBase>
<OrderId>12345</OrderId>
</PaymentContextBase>
<TenderType>PY</TenderType>
<ResponseCode>Success</ResponseCode>
<Amount currencyCode="USD">100.00</Amount>
<ExtendedResponseCode/>
<StoreId>ABCXYZ</StoreId>
</PaymentAuthCancelReply>Response Elements
| Element | Required | Description | Type | Restriction |
|---|---|---|---|---|
| PaymentContext | Choice of PaymentContext or PaymentContextBase. The same element that was used in the request is returned in the reply. | |||
| PaymentContext/ OrderId |
Yes (when PaymentContext is present) | Order ID | String | Max 20 characters |
| PaymentContext/ PaymentAccountUniqueId |
Yes (when PaymentContext is present) | Tokenized payment account number (for example, credit card number) | String | Max 22 characters |
| PaymentContext/ PaymentAccountUniqueId/ @isToken |
Yes (when PaymentContext is present) | Attribute that indicates whether the payment account number is tokenized | String | true |
| PaymentContextBase | Choice of PaymentContextBase or PaymentContext. The same element that was used in the request is returned in the reply. | |||
|
PaymentContextBase/ |
Yes (when PaymentContextBase is present) | Order ID | String | Max 20 characters |
| TenderType | Yes | Tender type identifier | String | 2 to 4 characters |
| ResponseCode | Yes | Authorization cancel response code | String | Success
Fail Timeout |
| Amount | Yes | Amount authorized on the credit card | String |
Positive decimal, up to two decimal places (for example, 4.75) |
| Amount/ @currencyCode |
Yes | Attribute that indicates the type of currency used for the order | String | 3-character ISO 4217 code (for example, USD, CAD, EUR). See
http://en.wikipedia.org/ wiki/ISO_4217. |
| ExtendedResponseCode | Yes | Additional response code details for failures | String | |
| StoreId | Yes | Store identifier | String | Max 100 characters |
Payment Authorization Cancel List Event
The xml response (mentioned below) contains a list of PaymentAuthCancelReply messages all clubbed under one parent element and is available only for clients using Asynchronous API Operations through Webhooks. This message cannot be obtained from a queue in RabbitMQ and hence the queue format is not applicable for the list event. In case you want to sign up for these events please contact customer service.
However, the individual PaymentAuthCancelReply message continues to live on RabbitMQ server and can be accessed using the information provided above.
Response Example
The response is a list of PaymentAuthCancelReply messages. Instead of returning single PaymentAuthCancelReply message, a list/batch of messsages are getting returned.
With a Payment Account Number
<?xml version="1.0" encoding="UTF-8"?>
<PaymentAuthCancelReplyList xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<PaymentAuthCancelReply>
<PaymentContext>
<OrderId>12345</OrderId>
<PaymentAccountUniqueId isToken="true">4111110PASeK1111</PaymentAccountUniqueId>
</PaymentContext>
<TenderType>VC</TenderType>
<ResponseCode>Success</ResponseCode>
<Amount currencyCode="USD">1.00</Amount>
<ExtendedResponseCode/>
<StoreId>ABCXYZ</StoreId>
</PaymentAuthCancelReply>
<PaymentAuthCancelReply>
<PaymentContext>
<OrderId>12890</OrderId>
<PaymentAccountUniqueId isToken="true">4222220PASeK2222</PaymentAccountUniqueId>
</PaymentContext>
<TenderType>VC</TenderType>
<ResponseCode>Success</ResponseCode>
<Amount currencyCode="USD">25.00</Amount>
<ExtendedResponseCode/>
<StoreId>ABC</StoreId>
</PaymentAuthCancelReply>
</PaymentAuthCancelReplyList>
Without a Payment Account Number
<?xml version="1.0" encoding="UTF-8"?>
<PaymentAuthCancelReplyList xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
<PaymentAuthCancelReply>
<PaymentContextBase>
<OrderId>12345</OrderId>
</PaymentContextBase>
<TenderType>PY</TenderType>
<ResponseCode>Success</ResponseCode>
<Amount currencyCode="USD">100.00</Amount>
<ExtendedResponseCode/>
<StoreId>ABCXYZ</StoreId>
</PaymentAuthCancelReply>
<PaymentAuthCancelReply>
<PaymentContextBase>
<OrderId>906735</OrderId>
</PaymentContextBase>
<TenderType>PY</TenderType>
<ResponseCode>Success</ResponseCode>
<Amount currencyCode="USD">200.00</Amount>
<ExtendedResponseCode/>
<StoreId>ABC</StoreId>
</PaymentAuthCancelReply>
</PaymentAuthCancelReplyList>Response Elements
| Element | Required | Description | Type | Restriction |
|---|---|---|---|---|
| PaymentAuthCancelReplyList | A wrapper/parent object for all the PaymentAuthCancelReply elements | Sequence of PaymentAuthCancelReply elements | ComplexType | |
| PaymentAuthCancelReply | A wrapper/parent object for all the sub-elements such as PaymentContextBase, TenderType, ResponseCode, Amount, ExtendedResponseCode, StoreId etc. | Sequence of PaymentContextBase, TenderType, ResponseCode, Amount, ExtendedResponseCode, StoreId | ComplexType | |
| PaymentContext | Choice of PaymentContext or PaymentContextBase. The same element that was used in the request is returned in the reply. | |||
| PaymentContext/ OrderId |
Yes (when PaymentContext is present) | Order ID | String | Max 20 characters |
| PaymentContext/ PaymentAccountUniqueId |
Yes (when PaymentContext is present) | Tokenized payment account number (for example, credit card number) | String | Max 22 characters |
| PaymentContext/ PaymentAccountUniqueId/ @isToken |
Yes (when PaymentContext is present) | Attribute that indicates whether the payment account number is tokenized | String | true |
| PaymentContextBase | Choice of PaymentContextBase or PaymentContext. The same element that was used in the request is returned in the reply. | |||
|
PaymentContextBase/ |
Yes (when PaymentContextBase is present) | Order ID | String | Max 20 characters |
| TenderType | Yes | Tender type identifier | String | 2 to 4 characters |
| ResponseCode | Yes | Authorization cancel response code | String | Success
Fail Timeout |
| Amount | Yes | Amount authorized on the credit card | String |
Positive decimal, up to two decimal places (for example, 4.75) |
| Amount/ @currencyCode |
Yes | Attribute that indicates the type of currency used for the order | String | 3-character ISO 4217 code (for example, USD, CAD, EUR). See
http://en.wikipedia.org/ wiki/ISO_4217. |
| ExtendedResponseCode | Yes | Additional response code details for failures | String | |
| StoreId | Yes | Store identifier | String | Max 100 characters |