🚧

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 Credit message from your ePOS system to credit money to a customer's card.

The ePOS Payments API supports this functionality as follows:

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

Sample Workflow

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

Card Present CreditCard Present Credit

Sample Credit Request Body payload

Below is an example of a nexo Credit Request payload (body only). In this example the cashier is requesting to credit €17 to a cardholder's card at the payment terminal

It is worth noting the following:

  • MessageCategory must be set as "Payment"
  • MessageType must be set as "Request"
  • POIID is set as "AUTO" as credits are card present
  • PaymentType must be set as "Refund"
  • RequestedAmount is set as the actual amount to be credited
{
  "SaleToPOIRequest": {
    "MessageHeader": {
      "MessageClass": "Service",
      "MessageCategory": "Payment",
      "MessageType": "Request",
      "ServiceID": "1731207545",
      "SaleID": "Salesystem-00000001",
      "POIID": "AUTO"
    },
    "PaymentRequest": {
      "SaleData": {
        "OperatorID": "Operator02",
        "SaleTransactionID": {
          "TransactionID": "6001596",
          "TimeStamp": "2020-11-11T10:11:15+01:00"
        },
        "TokenRequestedType": "Customer"
      },
      "PaymentTransaction": {
        "AmountsReq": {
          "Currency": "EUR",
          "RequestedAmount": "17"
        }
      },
      "PaymentData": {
        "PaymentType": "Refund"
      }
    }
  }
}

Sample Credit Response Body payload

Below is an example of a successful nexo Credit Response payload (body only). In this example there has been approval of the request for crediting €17 to a cardholder's card, 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": "54094601",
      "ProtocolVersion": "3.1",
      "SaleID": "Salesystem-00000001",
      "ServiceID": "1731207545"
    },
    "PaymentResponse": {
      "POIData": {
        "POITransactionID": {
          "TimeStamp": "2020-11-11T10:19:47.096",
          "TransactionID": "770235346506"
        }
      },
      "PaymentReceipt": [
        {
          "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": "11.11.2020            10:19:36"
              },
              {
                "EndOfLineFlag": true,
                "Text": "        MERCHANT RECEIPT"
              },
              {
                "EndOfLineFlag": true,
                "Text": "--------------------------------"
              },
              {
                "EndOfLineFlag": true,
                "Text": "TERMINAL: 54094601"
              },
              {
                "EndOfLineFlag": true,
                "Text": "DEVICE NAME: 54094601"
              },
              {
                "EndOfLineFlag": true,
                "Text": "MERCHANT: 123456"
              },
              {
                "EndOfLineFlag": true,
                "Text": "PAN: XXXXXXXXXXXX0037"
              },
              {
                "EndOfLineFlag": true,
                "Text": "AID: A000000333010101"
              },
              {
                "EndOfLineFlag": true,
                "Text": "CARD TYPE: UPI"
              },
              {
                "EndOfLineFlag": true,
                "Text": "             REFUND"
              },
              {
                "EndOfLineFlag": true,
                "Text": "EMV CHIP"
              },
              {
                "EndOfLineFlag": true,
                "Text": "REFERENCE: 7703"
              },
              {
                "EndOfLineFlag": true,
                "Text": "AMOUNT: EUR 17,00"
              },
              {
                "EndOfLineFlag": true,
                "Text": "AUTHORISATION CODE: 122191"
              },
              {
                "EndOfLineFlag": true,
                "Text": "              (00)"
              },
              {
                "EndOfLineFlag": true,
                "Text": "            APPROVED"
              },
              {
                "EndOfLineFlag": true,
                "Text": "   NO CARDHOLDER VERIFICATION"
              },
              {
                "EndOfLineFlag": true,
                "Text": " PLEASE RETAIN FOR YOUR RECORDS"
              }
            ]
          },
          "RequiredSignatureFlag": true
        },
        {
          "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": "11.11.2020            10:19:36"
              },
              {
                "EndOfLineFlag": true,
                "Text": "       CARDHOLDER RECEIPT"
              },
              {
                "EndOfLineFlag": true,
                "Text": "--------------------------------"
              },
              {
                "EndOfLineFlag": true,
                "Text": "TERMINAL: 54094601"
              },
              {
                "EndOfLineFlag": true,
                "Text": "DEVICE NAME: 54094601"
              },
              {
                "EndOfLineFlag": true,
                "Text": "MERCHANT: 123456"
              },
              {
                "EndOfLineFlag": true,
                "Text": "PAN: XXXXXXXXXXXX0037"
              },
              {
                "EndOfLineFlag": true,
                "Text": "AID: A000000333010101"
              },
              {
                "EndOfLineFlag": true,
                "Text": "CARD TYPE: UPI"
              },
              {
                "EndOfLineFlag": true,
                "Text": "             REFUND"
              },
              {
                "EndOfLineFlag": true,
                "Text": "EMV CHIP"
              },
              {
                "EndOfLineFlag": true,
                "Text": "REFERENCE: 7703"
              },
              {
                "EndOfLineFlag": true,
                "Text": "AMOUNT: EUR 17,00"
              },
              {
                "EndOfLineFlag": true,
                "Text": "AUTHORISATION CODE: 122191"
              },
              {
                "EndOfLineFlag": true,
                "Text": "              (00)"
              },
              {
                "EndOfLineFlag": true,
                "Text": "            APPROVED"
              },
              {
                "EndOfLineFlag": true,
                "Text": "   NO CARDHOLDER VERIFICATION"
              },
              {
                "EndOfLineFlag": true,
                "Text": " PLEASE RETAIN FOR YOUR RECORDS"
              }
            ]
          },
          "RequiredSignatureFlag": true
        }
      ],
      "PaymentResult": {
        "AmountsResp": {
          "AuthorizedAmount": "17",
          "Currency": "EUR"
        },
        "PaymentAcquirerData": {
          "AcquirerID": "1",
          "AcquirerPOIID": "54094601",
          "ApprovalCode": "122191",
          "MerchantID": "123456"
        },
        "PaymentInstrumentData": {
          "CardData": {
            "EntryMode": "ICC",
            "MaskedPAN": "XXXXXXXXXXXX0037",
            "PaymentBrand": "UPI",
            "PaymentToken": {
              "TokenRequestedType": "Customer",
              "TokenValue": "8364002647870037"
            },
            "SensitiveCardData": {
              "ExpiryDate": "1030"
            }
          },
          "PaymentInstrumentType": "Card"
        },
        "PaymentType": "Refund"
      },
      "Response": {
        "Result": "Success"
      },
      "SaleData": {
        "SaleTransactionID": {
          "TimeStamp": "2020-11-11T10:11:15+01:00",
          "TransactionID": "6001596"
        }
      }
    }
  }
}

Did this page help you?