Search

Are you looking for test card numbers?

Would you like to contact support?

Tax free shopping

Learn about tax free shopping and how to support it.

Tax Free Shopping (TFS) allows your international customers to obtain a refund of the sales tax or Value-Added Tax (VAT) that you collected on the goods they purchased. This can boost your revenue and improve shopper journeys.

To offer TFS to your shoppers, you need to have a Terminal API integration. In a stand-alone integration TFS is not possible. Also, you need to collaborate with a Tax Free Shopping provider. This is an organization that collects the sales tax/VAT, refunds the shopper, pays commission to the merchant, and takes care of the paperwork with the authorities.

TFS flows

We support the following tax free journeys: 

  • Regular tax free refund: the shopper receives a Tax Free form, gets export validation at the airport, and then claims the refund from the TFS provider. 
  • Fast tax free refund: the shopper receives the refund from the TFS provider within 48 hours. The shopper still needs to get export validation.

The role of Adyen in both TFS flows is limited to passing on information between the terminal and the cash register or TFS provider.

Regular tax free refund flow

The shopper fills out a Tax Free form, at the airport takes the form to Customs for export validation (a Customs stamp), and presents the stamped form to the TFS provider to receive the refund using their chosen payment method. Adyen supports this journey by sharing the issuer country code and Bank Identification Number (BIN) of the shopper’s card with the cash register system. The cash register uses this information to notify the sales associate that a foreign card was detected and prompts them to initiate the discussion with the shopper.

Fast tax free refund flow

The shopper receives the sales tax/VAT refund from the TFS provider, on the card they used for payment, within 48 hours. (Depending on the TFS provider, the delay can be longer.) In this flow too, the shopper needs to fill out a Tax Free form and get a Customs stamp, because the TFS provider takes a guarantee on the shopper's card. Adyen supports this journey by sharing the issuer country code and BIN number with the cash register system, and by sharing the card number of the shopper’s card with the TFS provider to enable them to refund the shopper on that card.

Before you begin

  1. Contact your Account Manager or the POS Support Team to understand the tax free shopping process and to decide if you want to offer the regular or the fast refund flow (provided the TFS provider approves).

  2. Contact a TFS provider to set up a tax free process. The TFS provider will need to agree as they will pay out to your shoppers directly.

  3. Contact your cash register provider to set up the cash register software for TFS support.

  4. If you decided to support the fast refund flow, ask your Account Manager or the POS Support Team to configure a Send card number to <TFS provider> notification for you. With this notification Adyen informs your TFS provider of the shopper's card number.

Step 1: Acquire card details

First you need to make a card acquistion request, to retrieve the data that the cash register requires to determine if the shopper is eligible for a sales tax/VAT refund.

  1. Make a card acquisition request to a Terminal API endpoint. As shown in the example below, you can use a basic card acquisition request without specifying an amount.

    {
     "SaleToPOIRequest": {
       "MessageHeader": {
         "ProtocolVersion": "3.0",
         "MessageClass": "Service",
         "MessageCategory": "CardAcquisition",
         "MessageType": "Request",
         "SaleID": "POSSystemID12345",
         "ServiceID": "0207111104",
         "POIID": "MX925-284691408"
       },
       "CardAcquisitionRequest": {
         "SaleData": {
           "SaleTransactionID": {
             "TimeStamp": "2019-05-17T14:59:09.000Z",
             "TransactionID": "TxId-2019-05-17T14:59:07+00:00"
           }
         },
         "CardAcquisitionTransaction": {
    
         }
       }
     }
    }

    In the response, the data to determine eligibility for a sales tax/VAT refund are in the AdditionalResponse. You'll also need the POIData later on.

    {
     "SaleToPOIResponse": {
       "CardAcquisitionResponse": {
         "POIData": {
           "POITransactionID": {
             "TimeStamp": "2019-05-17T14:59:08.000Z",
             "TransactionID": "jM6S001558097948000"
           },
         },
         "SaleData": {
           "SaleTransactionID": {
             "TimeStamp": "2019-05-17T14:59:09.000Z",
             "TransactionID": "TxId-2019-05-17T14:59:09+00:00"
           }
         },
         "PaymentInstrumentData": {
           "CardData": {
             "PaymentBrand": "mc",
             "MaskedPan": "541333*****9999",
             "CardCountryCode": "528",
             "SensitiveCardData": {
               "ExpiryDate": "0228"
           },
           "PaymentInstrumentType": "Card"
         },
         "Response": {
           "Result": "Success",
           "AdditionalResponse": {
             "tid": "84691408",
             "transactionType": "GOODS_SERVICES",
             ...
             "cardIssuerCountryId": "528",
             ...
             "cardBin": "541333",
             "posAuthAmountValue": 0
           }
         }
       },
       "MessageHeader": {
         "SaleID": "POSSystemID12345",     
         "MessageClass": "Service",
         "MessageCategory": "CardAcquisition",
         "ServiceID": "0207111104",
         "POIID": "MX925-284691408",
         "MessageType": "Response"
       }
     } 
    }
  2. Use the following data from the AdditionalResponse part of the response to do the eligibility check:

    • Issuer country code: Pass the value of the cardIssuerCountryId field, for example 528.
    • BIN: Pass the value of the cardBin field, for example 541333.
  3. Handle the eligibility check locally on the cash register or through the TFS provider, as discussed with your TFS provider and/or cash register provider.

Step 2: Make a payment

If the shopper is eligible for a sales tax/VAT refund, you make a payment request with a reference to the card acquisition. For a payment in the regular refund flow, that is all you need to do. For a payment in the fast refund flow, the request also needs to include a tax free flag. The flag tells us to send a message to your TFS provider to refund the shopper on their card within 48 hours. Remember that for this to work, you need to ask Adyen beforehand to enable Send card number to <TFS provider> notifications for you.

Payment in the regular refund flow
  • Make a basic payment request to a Terminal API endpoint, additionally specifying:

    • A PaymentData.CardAcquisitionReference structure containing:

      • TimeStamp: the timestamp returned in the POIData.POITransactionID of the card acquistion response.
      • TransactionID: the transaction ID returned in the POIData.POITransactionID of the card acquistion response.

    The example below shows how you would make a payment request in the regular refund flow.

    {
     "SaleToPOIRequest": {
       "MessageHeader": {
         "ProtocolVersion": "3.0",
         "MessageClass": "Service",
         "MessageCategory": "Payment",
         "MessageType": "Request",
         "SaleID": "POSSystemID12345",
         "ServiceID": "0207111104",
         "POIID": "MX925-284691408"          
       },
       "PaymentRequest": {
         "SaleData": {
           "SaleTransactionID": {
             "TransactionID": "27908",
             "TimeStamp": "2019-03-07T10:11:04+00:00"
           }
         },            
         "PaymentTransaction": {
           "AmountsReq": {
             "Currency": "EUR",
             "RequestedAmount": 176.99
           }
         },        
         "PaymentData": {
           "CardAcquisitionReference": {
             "TransactionID": "jM6S001558097948000",
             "TimeStamp": "2019-05-17T12:59:08.000Z"
           }
         }
       }
     }
    }
Payment in the fast refund flow
  • Make a basic payment request to a Terminal API endpoint, additionally specifying:

    • A SaleData.SaleToAcquirerData structure containing:

      • TaxFreeIndicator: true. This flag that tells us to send a message to your TFS provider to refund the shopper on their card.
    • A PaymentData.CardAcquisitionReference structure containing:

      • TimeStamp: the timestamp returned in the POIData.POITransactionID of the card acquistion response.
      • TransactionID: the transaction ID returned in the POIData.POITransactionID of the card acquistion response.

    The example below shows how you would make a payment request in the fast refund flow.

    {
     "SaleToPOIRequest": {
       "MessageHeader": {
         "ProtocolVersion": "3.0",
         "MessageClass": "Service",
         "MessageCategory": "Payment",
         "MessageType": "Request",
         "SaleID": "POSSystemID12345",
         "ServiceID": "0207111104",
         "POIID": "MX925-284691408"          
       },
       "PaymentRequest": {
         "SaleData": {
           "SaleToAcquirerData": {
              "TaxFreeIndicator": true
           },
           "SaleTransactionID": {
             "TransactionID": "27908",
             "TimeStamp": "2019-03-07T10:11:04+00:00"
           }            
         },
         "PaymentTransaction": {
           "AmountsReq": {
             "Currency": "EUR",
             "RequestedAmount": 176.99
           }
         },        
         "PaymentData": {
           "CardAcquisitionReference": {
             "TransactionID": "jM6S001558097948000",
             "TimeStamp": "2019-05-17T12:59:08.000Z"
           }
         }
       }
     }
    }

    The request is routed to the terminal, for the shopper to complete the transaction. The rest of the TFS flow (filling out the Tax Free form, etcetera) is outside of the scope of the payment transaction.

Terminal API endpoints

For test transactions, use the endpoint below that corresponds to your integration architecture.

For more information on these architectures, see our Terminal API overview.

Local

Endpoints for local communications with the Terminal API use the format:

  • https://[TERMINAL]:8443/nexo/ on port 8443 (https).
    Replace [TERMINAL] with the IP or resolvable hostname of the terminal.

Cloud

For cloud-based communications with the Terminal API use either:

See also