With an undo request, you can reverse a gift card transaction that loaded funds to a gift card. The amount loaded is taken off the gift card balance. However, you can only undo the most recent load transaction and this transaction must be from the past 24 hours.
You identify the transaction you want to undo by its transaction identifier. Undoing transactions is a synchronous operation, but in an asynchronous cloud integration you receive the result asynchronously in an event notification.
You cannot use an undo request to cancel a gift card payment or to make a refund to a gift card.
See Cancel a payment and Make a refund to a gift card.
Requirements
Before you make any gift card transactions, make sure that you have:
- Built an integration that can make a payment.
- Completed the onboarding process with your gift card provider.
- Added the payment method to your Adyen account.
Undo a transaction
To undo the most recent load transaction made in the past 24 hours on a gift card:
- Get the
POITransactionID.TimeStamp
andPOITransactionID.TransactionID
of the original
transaction. -
Make a POST request to a Terminal API endpoint,
specifying:-
MessageHeader
: the standardSaleToPOIRequest.MessageHeader
object. Specify:Parameter Required Description ProtocolVersion
3.0 MessageClass
Service MessageCategory
StoredValue MessageType
Request ServiceID
Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal ( POIID
) being used.SaleID
Your unique ID for the POS system component to send this request from. POIID
The unique ID of the terminal to send this request to. Format: [device model]-[serial number].
-
StoredValueRequest.SaleData.SaleTransactionID
. This includes:Parameter Required Description TransactionID
Your reference to identify this undo request. We recommend using a unique value. TimeStamp
date and time of the request, in UTC format. -
StoredValueRequest.StoredValueData
. This includes:Parameter Required Description StoredValueTransactionType
Reverse OriginalPOITransaction
The details of the transaction that you want to undo:
POITransactionID.TimeStamp
: date and time of the original transaction.POITransactionID.TransactionID
: transaction identifier of the original transaction, in one of the formats from the table below.
Format Example tenderReference.pspReference
A7sM001574852436000.NC6HT9CRT65ZGN82 Recommended formatpspReference
.NC6HT9CRT65ZGN82 Do not forget the leading dot (.).
tenderReference
A7sM001574852436000 Only when using the same terminal as for the original transaction.
Expand viewCopy link to code blockCopy code{ "SaleToPOIRequest":{ "MessageHeader":{ "MessageType":"Request", "MessageClass":"Service", "MessageCategory":"StoredValue", "SaleID":"POSSystemID12345", "POIID":"V400m-324688179", "ProtocolVersion":"3.0", "ServiceID":"9265" }, "StoredValueRequest":{ "SaleData":{ "SaleTransactionID":{ "TransactionID":"44739", "TimeStamp":"2019-12-22T10:10:34+00:00" } }, "StoredValueData": [ { "StoredValueTransactionType": "Reverse", "OriginalPOITransaction": { "POITransactionID": { "TransactionID": "A7sM001574852436000.NC6HT9CRT65ZGN82", "TimeStamp": "2019-12-22T09:01:15+00:00" } } } ] } } } -
The undo request is sent to the Adyen payments platform for processing.
See the StoredValueRequest API reference.
Response
Once processed, your integration receives a result indicating the current state or balance of the gift card. This is provided in a synchronous API response, unless your integration uses asynchronous cloud communications.
If your integration uses asynchronous cloud communications, you receive the response as an event notification.
If the reversal is successful:
-
You receive a response with a
StoredValueResponse
object that includes:-
POIData.POITransactionID.TransactionID
: Transaction identifier for the undo request. -
StoredValueResult
:StoredValueTransactionType
: Reverse-
StoredValueAccountStatus
: theCurrentBalance
remaining on the card after undoing a load request.
-
Response.Result
: Success -
Response.AdditionalResponse
: additional transaction data. Depending on the format you used in the request, you receive either a string of form-encoded key-value pairs or a Base64 string that you need to decode to get a JSON object.
See the StoredValueResponse API reference.
{ "SaleToPOIResponse":{ "StoredValueResponse":{ "POIData":{ "POITransactionID":{ "TimeStamp":"2019-03-26T09:31:29.000Z", "TransactionID":"pZjO001522056689002.NC6HT9CRT65ZGN82" } } ..., "StoredValueResult":[ { "StoredValueTransactionType":"Reverse", "StoredValueAccountStatus": { "CurrentBalance":265.79 } } ], "Response":{ "Result":"Success", "AdditionalResponse":"tid=46742566&transactionType=REFUND&backendGiftcardIndicator=false&posAmountGratuityValue=0&giftcardIndicator=true&pspReference=NC6HT9CRT65ZGN82&storedValueApi=true¤tBalanceCurrency=USD&txtime=10%3a27%3a20&iso8601TxDate=2019-12-31T09%3a27%3a20.0000000%2b0000&posOriginalAmountValue=0&txdate=31-12-2019&merchantReference=17322&transactionReferenceNumber=NC6HT9CRT65ZGN82&posadditionalamounts.originalAmountCurrency=EUR&posAuthAmountCurrency=EUR&posAmountCashbackValue=0&posAuthAmountValue=0¤tBalanceValue=26579" } }, "MessageHeader":{ "ProtocolVersion":"3.0", "SaleID":"POSSystemID12345", "MessageClass":"Service", "MessageCategory":"StoredValue", "ServiceID":"9264", "POIID":"V400m-324688179", "MessageType":"Response" } } } -