🚧

Development mode

ePOS Payments is in development. You can find the API specification in development here. If you are interested in gaining access when available then please contact us via our support page

Overview

Send a Refund message from your ePOS system for the partial or full reimbursement of a previous payment for a customer (reverse on subsequent business day). If orginal payment transaction is not settled, then a Reversal should be sent.

The ePOS Payments API supports this functionality as follows:

  • nexo Retailer PaymentRequest message with PaymentType set as "Refund" with OriginalPOITransaction - POITransactionID - TransactionID supplied

Sample Workflow

This sequence diagram maps to the steps in the Refund sample request and response payloads that follow.

Card Not Present RefundCard Not Present Refund

Sample Refund Request Body payload

Below is an example of a nexo Refund Request payload (body only). In this example the cashier is requesting to refund a previous €12 payment based on the POI transaction identifier for that payment.

It is worth noting the following:

  • MessageCategory must be set as "Payment"
  • MessageType must be set as "Request"
  • POIID is set as "CAP" as linked refunds are card not present
  • PaymentType must be set as "Refund"
  • RequestedAmount is set as the actual amount to be refunded
  • OriginalPOITransaction POITransactionID TransactionID is set to the TransactionID returned in the response of the payment to be refunded
{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "MessageClass": "Service",
      "MessageCategory": "Payment",
      "MessageType": "Request",
      "ServiceID": "1731207545",
      "SaleID": "Salesystem-00000001",
      "POIID": "CAP"
    },
    "PaymentRequest": {
      "SaleData": {
        "OperatorID": "Operator01",
        "SaleTransactionID": {
          "TransactionID": "0022931",
          "TimeStamp": "2021-01-16T15:40:36-05:00"
        }
      },
      "PaymentTransaction": {
        "AmountsReq": {
          "Currency": "EUR",
          "RequestedAmount": "12"
        },
        "OriginalPOITransaction": {
          "POITransactionID": {
            "TransactionID": "84554264661",
            "TimeStamp": "2021-01-15T10:20:29"
          }
        }
      },
      "PaymentData": {
        "PaymentType": "Refund",
        "PaymentInstrumentData": {
          "PaymentInstrumentType": "Card",
          "CardData": {
            "EntryMode": "File"
          }
        }
      }
    }
  }
}

Sample Refund Response Body payload

Below is an example of a successful nexo Refund Response payload (body only). In this example there has been approval of the request for refunding a customer based on a previous €12 payment, with the response including the authorization code, and the merchant and cardholder receipts.

It is worth noting the following:

  • Result is "Success"
  • PaymentReceipt holds the Customer and/or Merchant payment receipts
{
  "SaleToPOIResponse": {
    "MessageHeader": {
      "MessageCategory": "Payment",
      "MessageClass": "Service",
      "MessageType": "Response",
      "POIID": "CAP",
      "SaleID": "Salesystem-00000001",
      "ServiceID": "1731207545"
    },
    "PaymentResponse": {
      "POIData": {
        "POITransactionID": {
          "TimeStamp": "2021-01-16T15:40:50",
          "TransactionID": "84554264663"
        }
      },
      "PaymentReceipt": [
        {
          "DocumentQualifier": "CustomerReceipt",
          "OutputContent": {
            "OutputFormat": "Text",
            "OutputText": [
              {
                "EndOfLineFlag": true,
                "Text": "          Test_STORE           "
              },
              {
                "EndOfLineFlag": true,
                "Text": "         Address Line 1          "
              },
              {
                "EndOfLineFlag": true,
                "Text": "       Address Line 2        "
              },
              {
                "EndOfLineFlag": true,
                "Text": "            Country             "
              },
              {
                "EndOfLineFlag": true,
                "Text": "--------------------------------"
              },
              {
                "EndOfLineFlag": true,
                "Text": ""
              },
              {
                "EndOfLineFlag": true,
                "Text": "15.01.21                   15:40"
              },
              {
                "EndOfLineFlag": true,
                "Text": "      CUSTOMER RECEIPT          "
              },
              {
                "EndOfLineFlag": true,
                "Text": "--------------------------------"
              },
              {
                "EndOfLineFlag": true,
                "Text": "TERMINAL: 12345                 "
              },
              {
                "EndOfLineFlag": true,
                "Text": "MERCHANT: 123456                "
              },
              {
                "EndOfLineFlag": true,
                "Text": "PAN: XXXXXXXXXXXX1732           "
              },
              {
                "EndOfLineFlag": true,
                "Text": "CARD TYPE: Mastercard           "
              },
              {
                "EndOfLineFlag": true,
                "Text": "REFUND                          "
              },
              {
                "EndOfLineFlag": true,
                "Text": "MANUAL ENTRY                    "
              },
              {
                "EndOfLineFlag": true,
                "Text": "AMOUNT:                12,00 EUR"
              },
              {
                "EndOfLineFlag": true,
                "Text": "REFERENCE: 7006                 "
              },
              {
                "EndOfLineFlag": true,
                "Text": "AUTHORISATION CODE: 311437      "
              },
              {
                "EndOfLineFlag": true,
                "Text": "              (00)              "
              },
              {
                "EndOfLineFlag": true,
                "Text": "          APPROVED              "
              },
              {
                "EndOfLineFlag": true,
                "Text": "   NO CARDHOLDER VERIFICATION   "
              },
              {
                "EndOfLineFlag": true,
                "Text": " PLEASE RETAIN FOR YOUR RECORDS "
              }
            ]
          },
          "RequiredSignatureFlag": ""
        },
        {
          "DocumentQualifier": "CashierReceipt",
          "OutputContent": {
            "OutputFormat": "Text",
            "OutputText": [
              {
                "EndOfLineFlag": true,
                "Text": "          Test_STORE           "
              },
              {
                "EndOfLineFlag": true,
                "Text": "         Address Line 1          "
              },
              {
                "EndOfLineFlag": true,
                "Text": "       Address Line 2        "
              },
              {
                "EndOfLineFlag": true,
                "Text": "            Country             "
              },
              {
                "EndOfLineFlag": true,
                "Text": "--------------------------------"
              },
              {
                "EndOfLineFlag": true,
                "Text": ""
              },
              {
                "EndOfLineFlag": true,
                "Text": "15.01.21                   15:40"
              },
              {
                "EndOfLineFlag": true,
                "Text": "        MERCHANT RECEIPT         "
              },
              {
                "EndOfLineFlag": true,
                "Text": "--------------------------------"
              },
              {
                "EndOfLineFlag": true,
                "Text": "TERMINAL: 12345                 "
              },
              {
                "EndOfLineFlag": true,
                "Text": "MERCHANT: 123456                "
              },
              {
                "EndOfLineFlag": true,
                "Text": "PAN: XXXXXXXXXXXX1732           "
              },
              {
                "EndOfLineFlag": true,
                "Text": "CARD TYPE: Mastercard           "
              },
              {
                "EndOfLineFlag": true,
                "Text": "REFUND                          "
              },
              {
                "EndOfLineFlag": true,
                "Text": "MANUAL ENTRY                    "
              },
              {
                "EndOfLineFlag": true,
                "Text": "AMOUNT:                12,00 EUR"
              },
              {
                "EndOfLineFlag": true,
                "Text": "REFERENCE: 7006                 "
              },
              {
                "EndOfLineFlag": true,
                "Text": "AUTHORISATION CODE: 311437      "
              },
              {
                "EndOfLineFlag": true,
                "Text": "              (00)              "
              },
              {
                "EndOfLineFlag": true,
                "Text": "          APPROVED              "
              },
              {
                "EndOfLineFlag": true,
                "Text": "   NO CARDHOLDER VERIFICATION   "
              },
              {
                "EndOfLineFlag": true,
                "Text": " PLEASE RETAIN FOR YOUR RECORDS "
              }
            ]
          },
          "RequiredSignatureFlag": ""
        }
      ],
      "PaymentResult": {
        "AmountsResp": {
          "AuthorizedAmount": "12",
          "Currency": "EUR"
        },
        "OnlineFlag": "True",
        "PaymentAcquirerData": {
          "AcquirerPOIID": "12345",
          "ApprovalCode": "311437",
          "MerchantID": "123456"
        },
        "PaymentInstrumentData": {
          "CardData": {
            "EntryMode": "File",
            "MaskedPAN": "XXXXXXXXXXXX1732",
            "PaymentBrand": "M",
            "SensitiveCardData": {
              "ExpiryDate": "1224"
            }
          },
          "PaymentInstrumentType": "Card"
        },
        "PaymentType": "Refund"
      },
      "Response": {
        "Result": "Success"
      },
      "SaleData": {
        "SaleTransactionID": {
          "TimeStamp": "2021-01-16T15:40:36-05:00",
          "TransactionID": "0022931"
        }
      }
    }
  }
}

Did this page help you?