Overview

The StoredValueRedeemVoid API rolls back any stored value redemption operation that was executed as part of the checkout flow. This API is typically triggered when the webstore receives either a timeout on the redeem operation or when the order cannot be confirmed for any reason after having finished a redeem operation.

Like all other storedvalue APIs, StoredValueRedeemVoid is a synchronous API, where the client is waiting for the response. In case of timeout, the webstore or Order Management System retries the transaction for a configured number of times. If webstore receives a Failure response, then it is recommended to display a relevant error to the customer in the checkout flow.

Since redeem void is an internal operation, the customer should be shown responses related to redeem and not in relation to the void failure or timeout.

URI Summary

Action URI Template URI Example Request Content Type Response Content Type
POST vM.m/stores/{StoreID}/payments/storedvalue/redeemvoid/{TenderType}.xml /v1.0/stores/TMSUS/payments/storedvalue/redeemvoid/GS.xml application/xml or text/xml application/xml or text/xml

Request Elements

Element Required Description Type Restriction
PaymentContext Yes Unique identifier of the payment transaction for the order ComplexType  
PaymentContext/
OrderId
Yes Unique identifier of the order. The client must ensure uniqueness of OrderIds across all transactions that the client initiates with this service. String Max 20 characters
PaymentContext/
PaymentAccountUniqueId
Yes - Either PaymentAccountUniqueId or
EncryptedPaymentAccountUniqueId must be present.
Either a raw PAN (payment account number such as a credit card number) or a token representing a PAN String Max 22 characters
PaymentContext/
PaymentAccountUniqueId/
@isToken
Yes (when PaymentAccountUniqueId is present) Attribute that indicates whether the payment account number is tokenized String true or false

PaymentContext/
EncryptedPaymentAccount
UniqueId

Yes - Either PaymentAccountUniqueId or
EncryptedPaymentAccountUniqueId must be present.
Client-encrypted PAN. Used for clients who use client-side encryption to encrypt credit card numbers in the JavaScript that runs in their browser. For a webstore that is not PCI compliant, this ensures that the webstore never sees raw PANs. String Max 1000 characters
Pin No PIN for the gift card String 1 to 8 Characters. Either Pin or EncryptedPin can be used.
EncryptedPin No Encrypted PIN for the Giftcard. String Up to 1000 Characters. Either Pin or EncryptedPin can be used.
Amount Yes Currency amount to be added back to the gift card balance. Positive decimal, up to 2 decimal places Example: 4.75
Amount/
@currencyCode
Yes 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.
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 Up to 40 Characters.

Request Example

Copy this code sample.
<?xml version="1.0" encoding="UTF-8"?>
<StoredValueRedeemVoidRequest xmlns="http://api.gsicommerce.com/schema/checkout/1.0" requestId="12345">
    <PaymentContext>
        <OrderId>123456</OrderId>
        <PaymentAccountUniqueId isToken="false">8111111111111112</PaymentAccountUniqueId>
    </PaymentContext>
    <Pin>1234</Pin>
    <Amount currencyCode="USD">50.00</Amount>
</StoredValueRedeemVoidRequest>

Response Elements

Element Required Description Type Restriction
PaymentContext Yes The PaymentContext uniquely identifies a Payment Transaction for an order. ComplexType  
PaymentContext/
OrderId
Yes Unique identifier of the order. The client must ensure uniqueness of OrderIds across all transactions that the client initiates with this service. String Max 20 characters
PaymentContext/
PaymentAccountUniqueId
Yes The Payment Service Response will always return a token representing a PAN String Max 22 characters
PaymentContext/
PaymentAccountUniqueId/
@isToken
Yes (when PaymentAccountUniqueId is present) Attribute that indicates whether the payment account number is tokenized String In the the Response object this element will always be true
ResponseCode Yes Response Code returned from Payment Service. String Success, Fail, Timeout

Response Example

Copy this code sample.
<?xml version="1.0" encoding="UTF-8"?>
<StoredValueRedeemVoidReply xmlns="http://api.gsicommerce.com/schema/checkout/1.0">
    <PaymentContext>
        <OrderId>123456</OrderId>
        <PaymentAccountUniqueId isToken="true">811111Ira8rU1112</PaymentAccountUniqueId>
    </PaymentContext>
    <ResponseCode>Success</ResponseCode>
</StoredValueRedeemVoidReply>