Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Card identification before refunding

Before issuing an unreferenced refund, verify that the same card is used as for the payment.

Before issuing an unreferenced refund to the shopper's card, you may want to check if this is the same card that was used for the original payment. To do so, you make a card acquisition request with PaymentType Refund and compare the card alias against the card alias used for purchases. Then you either:

  • Pay the refund to the card the shopper presented for the card acquisition: You make a payment request with PaymentType Refund and a reference to the card acquisition.
  • Cancel the card acquisition. You can then ask the shopper for a different card and start again.

Before you begin

To use this flow, it is important that you:

Card identifiers

To verify that you'll be issuing the refund to the same card that was used for the payment, save the following identifiers for your payments:

  • Card alias (alias): A value that uniquely represents the shopper's card number (PAN), for example A37317672402294. With this, you can recognize the card that a shopper is using. You can't use the card alias for making payments. You receive the card alias in the AdditionalResponse.
  • Other transaction details such as the transaction amount.

Make a Refund card acquisition request

  1. Make a POST request to a Terminal API endpoint, specifying:

    • CardAcquisitionRequest: The request body with:

      Parameter Required Description
      SaleData.SaleTransactionID -white_check_mark- An object with:
      • TransactionID: Your unique reference for this request.
      • TimeStamp: Date and time of the request in UTC format.
      SaleData.TokenRequestedType Customer. This returns the card alias in the TokenValue field of the response. If you do not include the TokenRequestedType the card alias is returned only in the AdditionalResponse.
      CardAcquisitionTransaction -white_check_mark- This object contains:
      • TotalAmount: The amount you want to refund.
      • PaymentType: Refund.
    {
        "SaleToPOIRequest":{
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "MessageClass":"Service",
                "MessageCategory":"CardAcquisition",
                "MessageType":"Request",
                "ServiceID":"812",
                "SaleID":"POSSystemID12345",
                "POIID":"P400Plus-347069832"
            },
            "CardAcquisitionRequest":{
                "SaleData":{
                    "SaleTransactionID":{
                        "TransactionID":"136",
                        "TimeStamp":"2021-05-06T12:54:12.509Z"
                    },
                    "{hint:Optional, returns the card alias in TokenValue}TokenRequestedType":"Customer{/hint}"
                },
                "CardAcquisitionTransaction":{
                    "TotalAmount":24.98,
                    "PaymentType":"Refund"
                }
            }
        }
    }

    The terminal shows the refund amount with a minus sign (for example, -24.98) and asks the shopper to present their card.

  2. When you receive the response, save the following details:

    • POIData.POITransactionID.TimeStamp and POIData.POITransactionID.TransactionID: You need these details later in your payment request for an unreferenced refund.

    From the AdditionalResponse (you'll receive either a string of form-encoded key-value pairs or a Base64 string that you need to decode to get a JSON object):

    • alias: The card alias, to recognize the customer based on their card.
    Response for the Refund card acquisition
    {
        "SaleToPOIResponse": {
            "CardAcquisitionResponse": {
                "POIData": {
                    "POIReconciliationID": "1000",
                    "POITransactionID": {
                        "{hint:For use in the CardAcquisitionReference of the payment request}TimeStamp": "2021-05-06T12:54:15.000Z{/hint}",
                        "{hint:For use in the CardAcquisitionReference of the payment request}TransactionID": "CWf3001620305655003{/hint}"
                    }
                },
                "PaymentInstrumentData": {
                    "CardData": {
                        "CardCountryCode": "528",
                        "MaskedPan": "541333 **** 9999",
                        "PaymentBrand": "mc",
                        "PaymentToken": {
                            "TokenRequestedType": "Customer",
                            "TokenValue": "{hint:This is the card alias}M469509594859802{/hint}"
                        },
                        "SensitiveCardData": {
                            "ExpiryDate": "0228"
                        }
                    },
                    "PaymentInstrumentType": "Card"
                },
                "Response": {
                    "AdditionalResponse": "tid=47314497&transactionType=REFUND&backendGiftcardIndicator=false&posadditionalamounts.originalAmountValue=2498&expiryYear=2028&alias=M469509594859802&giftcardIndicator=false&posAmountGratuityValue=0&paymentMethodVariant=mc&store=A3nStoreNL&aliasType=Default&cardType=mc&iso8601TxDate=2021-05-06T12%3a54%3a15.0000000%2b0000&posOriginalAmountValue=2498&txtime=14%3a54%3a15&paymentMethod=mc&txdate=06-05-2021&cardSummary=9999&expiryMonth=02&merchantReference=136&posadditionalamounts.originalAmountCurrency=EUR&posAuthAmountCurrency=EUR&message=CARD_ACQ_COMPLETED&cardIssuerCountryId=528&posAmountCashbackValue=0&fundingSource=CREDIT&posEntryMode=CLESS_CHIP&cardBin=541333&cardScheme=mc&issuerCountry=NL&posAuthAmountValue=2498",
                    "Result": "Success"
                },
                "SaleData": {
                    "SaleTransactionID": {
                        "TimeStamp": "2021-05-06T12:54:12.509Z",
                        "TransactionID": "136"
                    }
                }
            },
            "MessageHeader": {
                ...
            }
        }
    }
  3. Search the payments stored in your back-end system for a match with the card alias returned in the card acquisition response and the refund amount.

Continue with a refund

If you decide to issue an unreferenced refund to the card that the shopper presented when you made the card acquisition request:

  1. Make a POST request to a Terminal API endpoint, specifying:

    • PaymentRequest: The request body with:

      Parameter Required Description
      PaymentTransaction.AmountsReq -white_check_mark- An object with:
      • Currency: The transaction currency.
      • RequestedAmount: The refund amount.
      PaymentData.PaymentType -white_check_mark- Refund
      PaymentData.CardAcquisitionReference -white_check_mark- An object referring to the card acquisition:
      • TimeStamp: The timestamp returned in the POIData.POITransactionID of the card acquisition response.
      • TransactionID: The transaction ID returned in the POIData.POITransactionID of the card acquisition response.
    {
        "SaleToPOIRequest":{
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "MessageClass":"Service",
                "MessageCategory":"Payment",
                "MessageType":"Request",
                "SaleID":"POSSystemID12345",
                "ServiceID":"952",
                "POIID":"P400Plus-248069832"
            },
            "PaymentRequest":{
                "SaleData":{
                    "SaleTransactionID":{
                        "TransactionID":"899",
                        "TimeStamp":"2021-05-06T12:54:45.000Z"
                    }
                },
                "PaymentTransaction":{
                    "AmountsReq":{
                        "Currency":"EUR",
                        "RequestedAmount":24.98
                    }
                },
                "PaymentData":{
                    "PaymentType":"Refund",
                    "CardAcquisitionReference":{
                        "{hint:POITransactionID.TimeStamp from the card acquisition}TimeStamp{/hint}":"2021-05-06T12:54:15.000Z",
                        "{hint:POITransactionID.TransactionID from the card acquisition}TransactionID{/hint}":"CWf3001620305655003"
                    }
                }
            }
        }
    }
  2. Check whether we received your refund request. If we received it:

    • Approved is shown on the terminal.
    • You receive a JSON response with:
    Refund payment response
    {
        "SaleToPOIResponse": {
            "MessageHeader": {...},
            "PaymentResponse": {
                "POIData": {
                    "POIReconciliationID": "1000",
                    "POITransactionID": {
                        "TimeStamp": "2021-05-06T12:54:42.000Z",
                        "TransactionID": "CWf3001620305655003.8815658961765250"
                    }
                },
                "PaymentReceipt": [...],
                "PaymentResult": {
                    "AmountsResp": {
                        "AuthorizedAmount": 24.98,
                        "Currency": "EUR"
                    },
                    "OnlineFlag": true,
                    "PaymentAcquirerData": {...},
                    "PaymentInstrumentData": {
                        "CardData": {
                            "CardCountryCode": "826",
                            "EntryMode": [
                                "Contactless"
                            ],
                            "MaskedPan": "541333 **** 9999",
                            "PaymentBrand": "mc",
                            "SensitiveCardData": {
                                "CardSeqNumb": "33",
                                "ExpiryDate": "0228"
                            }
                        },
                        "PaymentInstrumentType": "Card"
                    },
                    "PaymentType": "Refund"
                },
                "Response": {
                    "AdditionalResponse": "AID=A000000004101001&tid=47314497&transactionType=REFUND&backendGiftcardIndicator=false&posadditionalamounts.originalAmountValue=2498&expiryYear=2028&alias=M469509594859802&giftcardIndicator=false&posAmountGratuityValue=0&batteryLevel=100%25&paymentMethodVariant=mc&pspReference=8815658961765250&applicationPreferredName=mc%20en%20gbr%20gbp&store=A3nStoreNL&aliasType=Default&cardType=mc&iso8601TxDate=2021-05-06T12%3a54%3a45.0000000%2b0000&offline=false&posOriginalAmountValue=2498&txtime=14%3a54%3a45&paymentMethod=mc&txdate=06-05-2021&startYear=2017&tc=104DB3F1983EE147&cardIssueNumber=33&cardSummary=9999&expiryMonth=02&merchantReference=5&mid=1000&posadditionalamounts.originalAmountCurrency=EUR&transactionReferenceNumber=8815658961765250&posAuthAmountCurrency=EUR&cardHolderVerificationMethodResults=1F0302&cardIssuerCountryId=826&posAmountCashbackValue=0&fundingSource=CREDIT&posEntryMode=CLESS_CHIP&startMonth=01&cardBin=541333&cardScheme=mc&issuerCountry=GB&posAuthAmountValue=2498",
                    "Result": "Success"
                },
                "SaleData": {
                    "SaleTransactionID": {
                        "TimeStamp": "2021-05-06T12:54:42.229Z",
                        "TransactionID": "5"
                    }
                }
            }
        }
    }
  3. To learn the result, wait for the REFUND webhook notification.
    Refunds are always processed asynchronously. If successful, the refund is issued to the shopper's account.

Continue in a different way

If you decide not to issue an unreferenced refund to the card that the shopper presented when you made the card acquisition request, you need to cancel the card acquisition.

You can then, for example, ask the shopper for another card and start the process again.

See also