Terminal-2 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.

Requirements

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 cannot 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:

    • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. Specify:

      Parameter Required Description
      ProtocolVersion -white_check_mark- 3.0
      MessageClass -white_check_mark- Service
      MessageCategory -white_check_mark- CardAcquisition
      MessageType -white_check_mark- Request
      ServiceID -white_check_mark- 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 -white_check_mark- Your unique ID for the POS system component to send this request from.
      POIID -white_check_mark- The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

    • CardAcquisitionRequest: The request body with:

      Parameter Required Description
      SaleData.SaleTransactionID -white_check_mark- An object with:
      • TransactionID: your reference to identify the refund. We recommend using a unique value.
      • TimeStamp: date and time of the request in UTC format.
      SaleData.TokenRequestedType Customer. Returns the card alias in the TokenValue field of the response. Note that the card alias is always returned in the AdditionalResponse.
      CardAcquisitionTransaction -white_check_mark- This object contains:
      • TotalAmount: the amount you want to refund.
      • 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 (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):

    • alias: The card alias, to recognize the customer based on their card.

  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:

    • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. Specify:

      Parameter Required Description
      ProtocolVersion -white_check_mark- 3.0
      MessageClass -white_check_mark- Service
      MessageCategory -white_check_mark- Payment
      MessageType -white_check_mark- Request
      ServiceID -white_check_mark- 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 -white_check_mark- Your unique ID for the POS system component to send this request from.
      POIID -white_check_mark- The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

    • 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 time stamp returned in the POIData.POITransactionID of the card acquisition response.
      • TransactionID: The transaction ID returned in the POIData.POITransactionID of the card acquisition response.

  2. Check whether we received your refund request. If we received it:

    • The terminal shows Approved.
    • You receive a JSON response with:

  3. To learn the result, wait for the REFUND_WITH_DATA webhook.
    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