Documentation Powered by Redocly

EPS API Collection (1.0.0)

Download OpenAPI specification:Download

E-mail: support@openretailing.org License: Conexxus and IFSF License, Copyright © IFSF and CONEXXUS, INC. 2022, All Rights Reserved.

Group: EPS APIs

Definition: Interface for using a EPS system from a point of sale system (POS), device, or site system.

Description: The Electronic Payment Server (EPS) specification is a joint standard shared by Conexxus and IFSF and supports global EPS implementations. The intent of this API group is to provide functionality necessary for global market to manage credit, debit, fleet, and other proprietary card transaction processing from the Point of Sale (POS) to EPS.

The specification supports payment inside at a POS device and payment from an outdoor payment terminal, including unattended dispensers and car washes. The PIN pad is no longer a device of the POS and the EPS can function as a standalone processor. The EPS's connection to one or more hosts or front-end processors (FEPs) segregates payment functionality within the EPS. In addition, prompts presented to the customer are the same regardless of the POS.
The specification also supports standardized messaging between a Point of Purchase/Point of Interaction (POP/POI) terminal and the EPS. The EPS specification separates payment from the other components of a fuel retailing site, such as a point of sale (POS) system or outdoor sales processor (OSP). Separating payment functionality eliminates the burden of maintaining network specific software on the POS, may reduce PCI scope, and may improve interoperability.
In addition, by using an EPS, making changes to POS software applications to add or modify features and functionality no longer require payment recertification. Software in the EPS can be updated and downloaded independently from the POS and may not require a site visit, thereby potentially reducing cost and providing greater POS independence. Card processing within the EPS is table driven and unique by merchant, which provides greater flexibility and card acceptance support. The card table supports known debit, credit, prepaid and fleet card processing using multiple entry methods, including, but not limited to magnetic stripe, ICC, RFID, and keyboard entry.

You can find out more about apis at the Open Retailing website.

Associated API Definitions in this Group:

  • (none)

Use Case Summary: The basic use case flows are:

  • Authorization
  • Completion/FinancialAdvice
  • Sale/Payment
  • Reversal
  • Refund/Return

Architecture: This API uses RESTFul Web Services, associating required functionality with resources and operations on those resources. For handling unsolicited events from the service provider to the client, it uses HTML5 constructs such as "Server Sent Events" and "Web Sockets".

Referenced Standards:

Scope: OpenRetailing

Part of: EPS API Group

Authentication

apikey

apikey security scheme as defined by Open Retailing API Implementation Guide - Security.

Security Scheme Type API Key
Header parameter name: X-Api-Key

basic

This API supports Basic Authentication.

Security Scheme Type HTTP
HTTP Authorization Scheme basic

oauth2

OAuth2 security scheme as defined by Open Retailing API Implementation Guide - Security.

Security Scheme Type OAuth2
authorizationCode OAuth Flow
Authorization URL: https://gitlab.openretailing.org
Token URL: https://gitlab.openretailing.org/oauth/token
Scopes:
  • read -

    Grants read access

  • write -

    Grants write access

  • admin -

    Grants access to admin operations

eps

Contains EPS transaction functions.

/payment

Send a payment request to the EPS. Payments perform both an authorization and completion with one message in order to collect funds from a consumer's account. Typically this message is used for indoor payments and postpay fuel transactions.

Authorizations:
apikey
    basic
      oauth2
        Request Body schema: application/json
        connectionID
        required
        string (connectionIDType) [ 1 .. 1024 ] characters

        The site reference ID is created by the Host. It is used in subsequent requests. It avoids the need to send all vendor information on subsequent requests.

        cardIDType (object) or cardDataObject (object)
        • If the cardInstrument is included in the message it will include either:
          • cardID, which the POS received on a previous /cardReadRequest response from the EPS.
          • cardDataObject, which has the card information that the POS acquired (manual entry, scanning, or if the POS is driving a POI)
        • If the cardInstrument is NOT included in the message:
          • The EPS will know that it needs to acquire the card data at this time. The POS would not need to send an additional message to acquire the card.
        poiID
        required
        string (id80BaseType) [ 1 .. 80 ] characters

        80 character ID

        required
        object (monetaryAmount20Object)
        splitPaymentStans
        Array of strings (description40BaseType) [ items <= 40 characters ]

        For the cases where there is a split payment.

        required
        object (posJournalEventDetailObject)
        object (monetaryAmount20Object)

        Responses

        Request samples

        Content type
        application/json
        {
        • "connectionID": "40641ee8-8c1b-47cb-9609-70ff4318f7f5",
        • "cardID": "fca511ff-1abf-472b-955d-25f8dcadec5b",
        • "poiID": "703ef3b9-dc4b-4240-a81a-85e392ac9fb6",
        • "amount": {
          },
        • "transaction": {
          }
        }

        Response samples

        Content type
        application/json
        {
        • "statusReturn": {
          },
        • "approvedAmount": {
          },
        • "timestamp": "2021-06-18T12:55:00",
        • "stan": "3579f517-ba52-4466-b40c-f27b2a50e39a"
        }

        /payment/reversal

        This is triggered when the connection is lost between the POS and EPS during the process of a transaction.

        Authorizations:
        apikey
          basic
            oauth2
              Request Body schema: application/json
              connectionID
              required
              string (connectionIDType) [ 1 .. 1024 ] characters

              The site reference ID is created by the Host. It is used in subsequent requests. It avoids the need to send all vendor information on subsequent requests.

              cardIDType (object) or cardDataObject (object)
              • If the cardInstrument is included in the message it will include either:
                • cardID, which the POS received on a previous /cardReadRequest response from the EPS.
                • cardDataObject, which has the card information that the POS acquired (manual entry, scanning, or if the POS is driving a POI)
              • If the cardInstrument is NOT included in the message:
                • The EPS will know that it needs to acquire the card data at this time. The POS would not need to send an additional message to acquire the card.
              poiID
              required
              string (id80BaseType) [ 1 .. 80 ] characters

              80 character ID

              required
              object (monetaryAmount20Object)
              splitPaymentStans
              Array of strings (description40BaseType) [ items <= 40 characters ]

              For the cases where there is a split payment.

              required
              object (posJournalEventDetailObject)
              object (monetaryAmount20Object)

              Responses

              Request samples

              Content type
              application/json
              {
              • "connectionID": "40641ee8-8c1b-47cb-9609-70ff4318f7f5",
              • "cardID": "fca511ff-1abf-472b-955d-25f8dcadec5b",
              • "poiID": "703ef3b9-dc4b-4240-a81a-85e392ac9fb6",
              • "amount": {
                },
              • "transaction": {
                }
              }

              Response samples

              Content type
              application/json
              {
              • "statusReturn": {
                },
              • "approvedAmount": {
                },
              • "timestamp": "2021-06-18T12:55:00",
              • "stan": "3579f517-ba52-4466-b40c-f27b2a50e39a"
              }

              /reversal

              Reverse one or several EPS STANs. Used when the method of payment does not cover the full balance of the transaction and the funds need to be returned to the consumer's account.

              Authorizations:
              apikey
                basic
                  oauth2
                    Request Body schema: application/json
                    connectionID
                    required
                    string (connectionIDType) [ 1 .. 1024 ] characters

                    The site reference ID is created by the Host. It is used in subsequent requests. It avoids the need to send all vendor information on subsequent requests.

                    stans
                    required
                    Array of strings (description40BaseType) [ 1 .. 500 ] items [ items <= 40 characters ]

                    Responses

                    Request samples

                    Content type
                    application/json
                    {
                    • "connectionID": "40641ee8-8c1b-47cb-9609-70ff4318f7f5",
                    • "stans": [
                      ]
                    }

                    Response samples

                    Content type
                    application/json
                    {
                    • "statusReturn": {
                      },
                    • "timestamp": "2021-06-17T14:22:00",
                    • "stan": "98f69130-5b07-4339-b670-1ccb159e3b3c"
                    }

                    /authorization

                    Send a pre-authorization request to the EPS. This will reserve the funds for the transaction. This is typically used as the first message in outside or inside pre-pay flows.

                    Authorizations:
                    apikey
                      basic
                        oauth2
                          Request Body schema: application/json
                          connectionID
                          required
                          string (connectionIDType) [ 1 .. 1024 ] characters

                          The site reference ID is created by the Host. It is used in subsequent requests. It avoids the need to send all vendor information on subsequent requests.

                          cardIDType (object) or cardDataObject (object)
                          • If the cardInstrument is included in the message it will include either:
                            • cardID, which the POS received on a previous /cardReadRequest response from the EPS.
                            • cardDataObject, which has the card information that the POS acquired (manual entry, scanning, or if the POS is driving a POI)
                          • If the cardInstrument is NOT included in the message:
                            • The EPS will know that it needs to acquire the card data at this time. The POS would not need to send an additional message to acquire the card.
                          poiID
                          required
                          string (id80BaseType) [ 1 .. 80 ] characters

                          80 character ID

                          required
                          object (monetaryAmount20Object)
                          splitPaymentStans
                          Array of strings (description40BaseType) [ items <= 40 characters ]

                          For the cases where there is a split payment.

                          required
                          object (posJournalEventDetailObject)
                          object (monetaryAmount20Object)

                          Responses

                          Request samples

                          Content type
                          application/json
                          {
                          • "connectionID": "40641ee8-8c1b-47cb-9609-70ff4318f7f5",
                          • "cardInstrument": {
                            },
                          • "poiID": "703ef3b9-dc4b-4240-a81a-85e392ac9fb6",
                          • "amount": {
                            },
                          • "transaction": {
                            }
                          }

                          Response samples

                          Content type
                          application/json
                          {
                          • "statusReturn": {
                            },
                          • "approvedAmount": {
                            },
                          • "timestamp": "2021-06-18T12:55:00",
                          • "stan": "3579f517-ba52-4466-b40c-f27b2a50e39a"
                          }

                          /authorization/reversal

                          Send a reversal for a pre-authorization. This is triggered when the connection is lost between the POS and EPS during the process of a transaction.

                          Authorizations:
                          apikey
                            basic
                              oauth2
                                Request Body schema: application/json
                                connectionID
                                required
                                string (connectionIDType) [ 1 .. 1024 ] characters

                                The site reference ID is created by the Host. It is used in subsequent requests. It avoids the need to send all vendor information on subsequent requests.

                                cardIDType (object) or cardDataObject (object)
                                • If the cardInstrument is included in the message it will include either:
                                  • cardID, which the POS received on a previous /cardReadRequest response from the EPS.
                                  • cardDataObject, which has the card information that the POS acquired (manual entry, scanning, or if the POS is driving a POI)
                                • If the cardInstrument is NOT included in the message:
                                  • The EPS will know that it needs to acquire the card data at this time. The POS would not need to send an additional message to acquire the card.
                                poiID
                                required
                                string (id80BaseType) [ 1 .. 80 ] characters

                                80 character ID

                                required
                                object (monetaryAmount20Object)
                                splitPaymentStans
                                Array of strings (description40BaseType) [ items <= 40 characters ]

                                For the cases where there is a split payment.

                                required
                                object (posJournalEventDetailObject)
                                object (monetaryAmount20Object)

                                Responses

                                Request samples

                                Content type
                                application/json
                                {
                                • "connectionID": "40641ee8-8c1b-47cb-9609-70ff4318f7f5",
                                • "cardInstrument": {
                                  },
                                • "poiID": "703ef3b9-dc4b-4240-a81a-85e392ac9fb6",
                                • "amount": {
                                  },
                                • "transaction": {
                                  }
                                }

                                Response samples

                                Content type
                                application/json
                                {
                                • "statusReturn": {
                                  },
                                • "approvedAmount": {
                                  },
                                • "timestamp": "2021-06-18T12:55:00",
                                • "stan": "3579f517-ba52-4466-b40c-f27b2a50e39a"
                                }

                                /financialAdvice

                                Send a financial advice request to the EPS. This will complete the transaction following an authorization and indicate the final amount of funds to be collected. This is typically in outside or inside pre-pay flows.

                                Authorizations:
                                apikey
                                  basic
                                    oauth2
                                      Request Body schema: application/json
                                      connectionID
                                      required
                                      string (connectionIDType) [ 1 .. 1024 ] characters

                                      The site reference ID is created by the Host. It is used in subsequent requests. It avoids the need to send all vendor information on subsequent requests.

                                      poiID
                                      required
                                      string (id80BaseType) [ 1 .. 80 ] characters

                                      80 character ID

                                      required
                                      object (monetaryAmount20Object)
                                      authorizationStan
                                      required
                                      string (description40BaseType) <= 40 characters

                                      40 character description.

                                      required
                                      object (posJournalEventDetailObject)

                                      Responses

                                      Request samples

                                      Content type
                                      application/json
                                      {
                                      • "connectionID": "40641ee8-8c1b-47cb-9609-70ff4318f7f5",
                                      • "poiID": "703ef3b9-dc4b-4240-a81a-85e392ac9fb6",
                                      • "amount": {
                                        },
                                      • "authorizationStan": "3579f517-ba52-4466-b40c-f27b2a50e39a",
                                      • "transaction": {
                                        }
                                      }

                                      Response samples

                                      Content type
                                      application/json
                                      {
                                      • "statusReturn": {
                                        },
                                      • "approvedAmount": {
                                        },
                                      • "timestamp": "2021-06-18T12:55:00",
                                      • "stan": "3579f517-ba52-4466-b40c-f27b2a50e39a"
                                      }

                                      /financialAdvice/reversal

                                      Send a financial advice (Completion) reversal to the EPS. This is triggered when the connection is lost between the POS and EPS during the process of a transaction.

                                      Authorizations:
                                      apikey
                                        basic
                                          oauth2
                                            Request Body schema: application/json
                                            connectionID
                                            required
                                            string (connectionIDType) [ 1 .. 1024 ] characters

                                            The site reference ID is created by the Host. It is used in subsequent requests. It avoids the need to send all vendor information on subsequent requests.

                                            poiID
                                            required
                                            string (id80BaseType) [ 1 .. 80 ] characters

                                            80 character ID

                                            required
                                            object (monetaryAmount20Object)
                                            authorizationStan
                                            required
                                            string (description40BaseType) <= 40 characters

                                            40 character description.

                                            required
                                            object (posJournalEventDetailObject)

                                            Responses

                                            Request samples

                                            Content type
                                            application/json
                                            {
                                            • "connectionID": "40641ee8-8c1b-47cb-9609-70ff4318f7f5",
                                            • "poiID": "703ef3b9-dc4b-4240-a81a-85e392ac9fb6",
                                            • "amount": {
                                              },
                                            • "authorizationStan": "3579f517-ba52-4466-b40c-f27b2a50e39a",
                                            • "transaction": {
                                              }
                                            }

                                            Response samples

                                            Content type
                                            application/json
                                            {
                                            • "statusReturn": {
                                              },
                                            • "approvedAmount": {
                                              },
                                            • "timestamp": "2021-06-18T12:55:00",
                                            • "stan": "3579f517-ba52-4466-b40c-f27b2a50e39a"
                                            }

                                            /refund

                                            Send a refund request to the EPS.

                                            Authorizations:
                                            apikey
                                              basic
                                                oauth2
                                                  Request Body schema: application/json
                                                  connectionID
                                                  required
                                                  string (connectionIDType) [ 1 .. 1024 ] characters

                                                  The site reference ID is created by the Host. It is used in subsequent requests. It avoids the need to send all vendor information on subsequent requests.

                                                  cardIDType (object) or cardDataObject (object)
                                                  • If the cardInstrument is included in the message it will include either:
                                                    • cardID, which the POS received on a previous /cardReadRequest response from the EPS.
                                                    • cardDataObject, which has the card information that the POS acquired (manual entry, scanning, or if the POS is driving a POI)
                                                  • If the cardInstrument is NOT included in the message:
                                                    • The EPS will know that it needs to acquire the card data at this time. The POS would not need to send an additional message to acquire the card.
                                                  poiID
                                                  required
                                                  string (id80BaseType) [ 1 .. 80 ] characters

                                                  80 character ID

                                                  required
                                                  object (monetaryAmount20Object)
                                                  required
                                                  object (posJournalEventDetailObject)

                                                  Responses

                                                  Request samples

                                                  Content type
                                                  application/json
                                                  {
                                                  • "connectionID": "40641ee8-8c1b-47cb-9609-70ff4318f7f5",
                                                  • "cardID": "fca511ff-1abf-472b-955d-25f8dcadec5b",
                                                  • "poiID": "703ef3b9-dc4b-4240-a81a-85e392ac9fb6",
                                                  • "amount": {
                                                    },
                                                  • "transaction": {
                                                    }
                                                  }

                                                  Response samples

                                                  Content type
                                                  application/json
                                                  {
                                                  • "statusReturn": {
                                                    },
                                                  • "refundAmount": {
                                                    },
                                                  • "timestamp": "2021-06-18T12:55:00",
                                                  • "stan": "3579f517-ba52-4466-b40c-f27b2a50e39a"
                                                  }

                                                  /refund/reversal

                                                  Send a refund reversal request to the EPS.

                                                  Authorizations:
                                                  apikey
                                                    basic
                                                      oauth2
                                                        Request Body schema: application/json
                                                        connectionID
                                                        required
                                                        string (connectionIDType) [ 1 .. 1024 ] characters

                                                        The site reference ID is created by the Host. It is used in subsequent requests. It avoids the need to send all vendor information on subsequent requests.

                                                        cardIDType (object) or cardDataObject (object)
                                                        • If the cardInstrument is included in the message it will include either:
                                                          • cardID, which the POS received on a previous /cardReadRequest response from the EPS.
                                                          • cardDataObject, which has the card information that the POS acquired (manual entry, scanning, or if the POS is driving a POI)
                                                        • If the cardInstrument is NOT included in the message:
                                                          • The EPS will know that it needs to acquire the card data at this time. The POS would not need to send an additional message to acquire the card.
                                                        poiID
                                                        required
                                                        string (id80BaseType) [ 1 .. 80 ] characters

                                                        80 character ID

                                                        required
                                                        object (monetaryAmount20Object)
                                                        required
                                                        object (posJournalEventDetailObject)

                                                        Responses

                                                        Request samples

                                                        Content type
                                                        application/json
                                                        {
                                                        • "connectionID": "40641ee8-8c1b-47cb-9609-70ff4318f7f5",
                                                        • "cardID": "fca511ff-1abf-472b-955d-25f8dcadec5b",
                                                        • "poiID": "703ef3b9-dc4b-4240-a81a-85e392ac9fb6",
                                                        • "amount": {
                                                          },
                                                        • "transaction": {
                                                          }
                                                        }

                                                        Response samples

                                                        Content type
                                                        application/json
                                                        {
                                                        • "statusReturn": {
                                                          },
                                                        • "refundAmount": {
                                                          },
                                                        • "timestamp": "2021-06-18T12:55:00",
                                                        • "stan": "3579f517-ba52-4466-b40c-f27b2a50e39a"
                                                        }

                                                        /reconciliation

                                                        Send to the EPS to perform a reconciliation request where a workstation needs a snapshot of stored previous transactions or to close a terminal batch. After a reconcilation where a terminal batch is closed a new termial batch is opened for future transactions.

                                                        Authorizations:
                                                        apikey
                                                          basic
                                                            oauth2
                                                              Request Body schema: application/json
                                                              connectionID
                                                              required
                                                              string (connectionIDType) [ 1 .. 1024 ] characters

                                                              The site reference ID is created by the Host. It is used in subsequent requests. It avoids the need to send all vendor information on subsequent requests.

                                                              workstationID
                                                              required
                                                              string (id80BaseType) [ 1 .. 80 ] characters

                                                              80 character ID

                                                              interval
                                                              string (intervalENUMType) <= 16 characters
                                                              Enum: "cashier" "day" "week" "month" "year" "daypart" "shift" "transaction" "sBatch" "hostBatch" "other"

                                                              Sometimes refered to as 'day part' values, refers to the scoped period of a report. Most often the value will be 'day' or 'shift', or in some cases 'cashier' if the reporting system produces such a report.

                                                              required
                                                              string or string (yesNoEENUMType) <= 6 characters

                                                              boolean definition

                                                              required
                                                              string or string (yesNoEENUMType) <= 6 characters

                                                              boolean definition

                                                              Responses

                                                              Request samples

                                                              Content type
                                                              application/json
                                                              {
                                                              • "connectionID": "d11315d2-aa2a-4740-93d9-79383d4eccad",
                                                              • "workstationID": "88888-8888-88888088888-7777777",
                                                              • "interval": "day",
                                                              • "synchronous": "no",
                                                              • "close": "yes"
                                                              }

                                                              Response samples

                                                              Content type
                                                              application/json
                                                              {
                                                              • "statusReturn": {
                                                                },
                                                              • "reconciliationID": "d11315d2-aa2a-4740-93d9-79383d4eccad"
                                                              }

                                                              /reconciliation/{reconciliationID}/salesAccruals/data

                                                              Send a request to retrieve the sales accruals data from the EPS

                                                              Authorizations:
                                                              apikey
                                                                basic
                                                                  oauth2
                                                                    header Parameters
                                                                    openretailing-connection-id
                                                                    required
                                                                    string (connectionIDType) [ 1 .. 1024 ] characters

                                                                    The Site Reference ID returned in the "connect" call.

                                                                    Responses

                                                                    Response samples

                                                                    Content type
                                                                    application/json
                                                                    {
                                                                    • "statusReturn": {
                                                                      },
                                                                    • "salesAccruals": {
                                                                      }
                                                                    }

                                                                    /reconciliation/{reconciliationID}/reversalAccruals/data

                                                                    Send a request to retrieve the reversal accural data from the EPS

                                                                    Authorizations:
                                                                    apikey
                                                                      basic
                                                                        oauth2
                                                                          header Parameters
                                                                          openretailing-connection-id
                                                                          required
                                                                          string (connectionIDType) [ 1 .. 1024 ] characters

                                                                          The Site Reference ID returned in the "connect" call.

                                                                          Responses

                                                                          Response samples

                                                                          Content type
                                                                          application/json
                                                                          {
                                                                          • "statusReturn": {
                                                                            },
                                                                          • "reversalAccruals": {
                                                                            }
                                                                          }

                                                                          /reconciliation/{reconciliationID}/loyaltySales/data

                                                                          Send a request to retrieve the loyalty sales accruals data from the EPS Data is from a day close period and specified by a reconcilationID which was returned from a previous reconciliation request.

                                                                          Authorizations:
                                                                          apikey
                                                                            basic
                                                                              oauth2
                                                                                header Parameters
                                                                                openretailing-connection-id
                                                                                required
                                                                                string (connectionIDType) [ 1 .. 1024 ] characters

                                                                                The Site Reference ID returned in the "connect" call.

                                                                                Responses

                                                                                Response samples

                                                                                Content type
                                                                                application/json
                                                                                {
                                                                                • "statusReturn": {
                                                                                  },
                                                                                • "loyaltySales": {
                                                                                  }
                                                                                }

                                                                                /reconciliation/{reconciliationID}/loyaltyReversals/data

                                                                                Send a request to retrieve the loyalty reversal accrual data from the EPS Data is from a day close period specified by a reconcilationID which was returned from a previous reconciliation request

                                                                                Authorizations:
                                                                                apikey
                                                                                  basic
                                                                                    oauth2
                                                                                      header Parameters
                                                                                      openretailing-connection-id
                                                                                      required
                                                                                      string (connectionIDType) [ 1 .. 1024 ] characters

                                                                                      The Site Reference ID returned in the "connect" call.

                                                                                      Responses

                                                                                      Response samples

                                                                                      Content type
                                                                                      application/json
                                                                                      {
                                                                                      • "statusReturn": {
                                                                                        },
                                                                                      • "loyaltyReversals": {
                                                                                        }
                                                                                      }

                                                                                      /reconciliation/{reconciliationID}/cardSummary/data

                                                                                      Send a request to retrieve the summary of card data from the EPS Data is from a day close period specified by a reconcilationID which was returned from a previous reconciliation request.

                                                                                      Authorizations:
                                                                                      apikey
                                                                                        basic
                                                                                          oauth2
                                                                                            header Parameters
                                                                                            openretailing-connection-id
                                                                                            required
                                                                                            string (connectionIDType) [ 1 .. 1024 ] characters

                                                                                            The Site Reference ID returned in the "connect" call.

                                                                                            Responses

                                                                                            Response samples

                                                                                            Content type
                                                                                            application/json
                                                                                            {
                                                                                            • "statusReturn": {
                                                                                              },
                                                                                            • "cardSummary": [
                                                                                              ]
                                                                                            }

                                                                                            /reconciliation/{reconciliationID}/exceptionLog/data

                                                                                            Send a request to retrieve a list of exceptions from the EPS Data is from a day close period specified by a reconcilationID which was returned from a previous reconciliation request.

                                                                                            Authorizations:
                                                                                            apikey
                                                                                              basic
                                                                                                oauth2
                                                                                                  header Parameters
                                                                                                  openretailing-connection-id
                                                                                                  required
                                                                                                  string (connectionIDType) [ 1 .. 1024 ] characters

                                                                                                  The Site Reference ID returned in the "connect" call.

                                                                                                  Responses

                                                                                                  Response samples

                                                                                                  Content type
                                                                                                  application/json
                                                                                                  {
                                                                                                  • "statusReturn": {
                                                                                                    },
                                                                                                  • "exceptionLog": [
                                                                                                    ]
                                                                                                  }

                                                                                                  /reconciliation/{reconciliationID}/text

                                                                                                  Send a request to retrieve from the EPS one single report with all the information available. If one of the sections contain no data, the EPS should include a message "No Data" or similar to that section

                                                                                                  Authorizations:
                                                                                                  apikey
                                                                                                    basic
                                                                                                      oauth2
                                                                                                        header Parameters
                                                                                                        openretailing-connection-id
                                                                                                        required
                                                                                                        string (connectionIDType) [ 1 .. 1024 ] characters

                                                                                                        The Site Reference ID returned in the "connect" call.

                                                                                                        Responses

                                                                                                        Response samples

                                                                                                        Content type
                                                                                                        application/json
                                                                                                        {
                                                                                                        • "statusReturn": {
                                                                                                          },
                                                                                                        • "reconciliationReport": [
                                                                                                          ]
                                                                                                        }

                                                                                                        /activation

                                                                                                        Send to request an activation from the EPS.

                                                                                                        Authorizations:
                                                                                                        apikey
                                                                                                          basic
                                                                                                            oauth2
                                                                                                              Request Body schema: application/json
                                                                                                              connectionID
                                                                                                              required
                                                                                                              string (connectionIDType) [ 1 .. 1024 ] characters

                                                                                                              The site reference ID is created by the Host. It is used in subsequent requests. It avoids the need to send all vendor information on subsequent requests.

                                                                                                              cardIDType (object) or cardDataObject (object)
                                                                                                              • If the cardInstrument is included in the message it will include either:
                                                                                                                • cardID, which the POS received on a previous /cardReadRequest response from the EPS.
                                                                                                                • cardDataObject, which has the card information that the POS acquired (manual entry, scanning, or if the POS is driving a POI)
                                                                                                              • If the cardInstrument is NOT included in the message:
                                                                                                                • The EPS will know that it needs to acquire the card data at this time. The POS would not need to send an additional message to acquire the card.
                                                                                                              poiID
                                                                                                              required
                                                                                                              string (id80BaseType) [ 1 .. 80 ] characters

                                                                                                              80 character ID

                                                                                                              required
                                                                                                              object (monetaryAmount20Object)
                                                                                                              required
                                                                                                              object (posJournalEventDetailObject)

                                                                                                              Responses

                                                                                                              Request samples

                                                                                                              Content type
                                                                                                              application/json
                                                                                                              {
                                                                                                              • "connectionID": "40641ee8-8c1b-47cb-9609-70ff4318f7f5",
                                                                                                              • "cardInstrument": {
                                                                                                                },
                                                                                                              • "poiID": "703ef3b9-dc4b-4240-a81a-85e392ac9fb6",
                                                                                                              • "amount": {
                                                                                                                },
                                                                                                              • "transaction": {
                                                                                                                }
                                                                                                              }

                                                                                                              Response samples

                                                                                                              Content type
                                                                                                              application/json
                                                                                                              {
                                                                                                              • "statusReturn": {
                                                                                                                },
                                                                                                              • "timestamp": "2021-06-18T12:55:00",
                                                                                                              • "stan": "3579f517-ba52-4466-b40c-f27b2a50e39a"
                                                                                                              }

                                                                                                              /activation/reversal

                                                                                                              Send an activation reversal to the EPS. This is triggered when the connection is lost between the POS and EPS during the process of a transaction.

                                                                                                              Authorizations:
                                                                                                              apikey
                                                                                                                basic
                                                                                                                  oauth2
                                                                                                                    Request Body schema: application/json
                                                                                                                    connectionID
                                                                                                                    required
                                                                                                                    string (connectionIDType) [ 1 .. 1024 ] characters

                                                                                                                    The site reference ID is created by the Host. It is used in subsequent requests. It avoids the need to send all vendor information on subsequent requests.

                                                                                                                    cardIDType (object) or cardDataObject (object)
                                                                                                                    • If the cardInstrument is included in the message it will include either:
                                                                                                                      • cardID, which the POS received on a previous /cardReadRequest response from the EPS.
                                                                                                                      • cardDataObject, which has the card information that the POS acquired (manual entry, scanning, or if the POS is driving a POI)
                                                                                                                    • If the cardInstrument is NOT included in the message:
                                                                                                                      • The EPS will know that it needs to acquire the card data at this time. The POS would not need to send an additional message to acquire the card.
                                                                                                                    poiID
                                                                                                                    required
                                                                                                                    string (id80BaseType) [ 1 .. 80 ] characters

                                                                                                                    80 character ID

                                                                                                                    required
                                                                                                                    object (monetaryAmount20Object)
                                                                                                                    required
                                                                                                                    object (posJournalEventDetailObject)

                                                                                                                    Responses

                                                                                                                    Request samples

                                                                                                                    Content type
                                                                                                                    application/json
                                                                                                                    {
                                                                                                                    • "connectionID": "40641ee8-8c1b-47cb-9609-70ff4318f7f5",
                                                                                                                    • "cardInstrument": {
                                                                                                                      },
                                                                                                                    • "poiID": "703ef3b9-dc4b-4240-a81a-85e392ac9fb6",
                                                                                                                    • "amount": {
                                                                                                                      },
                                                                                                                    • "transaction": {
                                                                                                                      }
                                                                                                                    }

                                                                                                                    Response samples

                                                                                                                    Content type
                                                                                                                    application/json
                                                                                                                    {
                                                                                                                    • "statusReturn": {
                                                                                                                      },
                                                                                                                    • "timestamp": "2021-06-18T12:55:00",
                                                                                                                    • "stan": "3579f517-ba52-4466-b40c-f27b2a50e39a"
                                                                                                                    }

                                                                                                                    /deActivation

                                                                                                                    Send to perform a single card deactivation.

                                                                                                                    Authorizations:
                                                                                                                    apikey
                                                                                                                      basic
                                                                                                                        oauth2
                                                                                                                          Request Body schema: application/json
                                                                                                                          connectionID
                                                                                                                          required
                                                                                                                          string (connectionIDType) [ 1 .. 1024 ] characters

                                                                                                                          The site reference ID is created by the Host. It is used in subsequent requests. It avoids the need to send all vendor information on subsequent requests.

                                                                                                                          cardIDType (object) or cardDataObject (object)
                                                                                                                          • If the cardInstrument is included in the message it will include either:
                                                                                                                            • cardID, which the POS received on a previous /cardReadRequest response from the EPS.
                                                                                                                            • cardDataObject, which has the card information that the POS acquired (manual entry, scanning, or if the POS is driving a POI)
                                                                                                                          • If the cardInstrument is NOT included in the message:
                                                                                                                            • The EPS will know that it needs to acquire the card data at this time. The POS would not need to send an additional message to acquire the card.
                                                                                                                          poiID
                                                                                                                          required
                                                                                                                          string (id80BaseType) [ 1 .. 80 ] characters

                                                                                                                          80 character ID

                                                                                                                          required
                                                                                                                          object (posJournalEventDetailObject)

                                                                                                                          Responses

                                                                                                                          Request samples

                                                                                                                          Content type
                                                                                                                          application/json
                                                                                                                          {
                                                                                                                          • "connectionID": "40641ee8-8c1b-47cb-9609-70ff4318f7f5",
                                                                                                                          • "cardInstrument": {
                                                                                                                            },
                                                                                                                          • "poiID": "703ef3b9-dc4b-4240-a81a-85e392ac9fb6",
                                                                                                                          • "amount": {
                                                                                                                            },
                                                                                                                          • "transaction": {
                                                                                                                            }
                                                                                                                          }

                                                                                                                          Response samples

                                                                                                                          Content type
                                                                                                                          application/json
                                                                                                                          {
                                                                                                                          • "statusReturn": {
                                                                                                                            },
                                                                                                                          • "timestamp": "2021-06-18T12:55:00",
                                                                                                                          • "stan": "3579f517-ba52-4466-b40c-f27b2a50e39a"
                                                                                                                          }

                                                                                                                          /deActivation/reversal

                                                                                                                          Send a deactivation reversal to the EPS. This is triggered when the connection is lost between the POS and EPS during the process of a transaction.

                                                                                                                          Authorizations:
                                                                                                                          apikey
                                                                                                                            basic
                                                                                                                              oauth2
                                                                                                                                Request Body schema: application/json
                                                                                                                                connectionID
                                                                                                                                required
                                                                                                                                string (connectionIDType) [ 1 .. 1024 ] characters

                                                                                                                                The site reference ID is created by the Host. It is used in subsequent requests. It avoids the need to send all vendor information on subsequent requests.

                                                                                                                                cardIDType (object) or cardDataObject (object)
                                                                                                                                • If the cardInstrument is included in the message it will include either:
                                                                                                                                  • cardID, which the POS received on a previous /cardReadRequest response from the EPS.
                                                                                                                                  • cardDataObject, which has the card information that the POS acquired (manual entry, scanning, or if the POS is driving a POI)
                                                                                                                                • If the cardInstrument is NOT included in the message:
                                                                                                                                  • The EPS will know that it needs to acquire the card data at this time. The POS would not need to send an additional message to acquire the card.
                                                                                                                                poiID
                                                                                                                                required
                                                                                                                                string (id80BaseType) [ 1 .. 80 ] characters

                                                                                                                                80 character ID

                                                                                                                                required
                                                                                                                                object (posJournalEventDetailObject)

                                                                                                                                Responses

                                                                                                                                Request samples

                                                                                                                                Content type
                                                                                                                                application/json
                                                                                                                                {
                                                                                                                                • "connectionID": "40641ee8-8c1b-47cb-9609-70ff4318f7f5",
                                                                                                                                • "cardInstrument": {
                                                                                                                                  },
                                                                                                                                • "poiID": "703ef3b9-dc4b-4240-a81a-85e392ac9fb6",
                                                                                                                                • "amount": {
                                                                                                                                  },
                                                                                                                                • "transaction": {
                                                                                                                                  }
                                                                                                                                }

                                                                                                                                Response samples

                                                                                                                                Content type
                                                                                                                                application/json
                                                                                                                                {
                                                                                                                                • "statusReturn": {
                                                                                                                                  },
                                                                                                                                • "timestamp": "2021-06-18T12:55:00",
                                                                                                                                • "stan": "3579f517-ba52-4466-b40c-f27b2a50e39a"
                                                                                                                                }

                                                                                                                                /recharge

                                                                                                                                Send to perform a single recharge of a gift card

                                                                                                                                Authorizations:
                                                                                                                                apikey
                                                                                                                                  basic
                                                                                                                                    oauth2
                                                                                                                                      Request Body schema: application/json
                                                                                                                                      connectionID
                                                                                                                                      required
                                                                                                                                      string (connectionIDType) [ 1 .. 1024 ] characters

                                                                                                                                      The site reference ID is created by the Host. It is used in subsequent requests. It avoids the need to send all vendor information on subsequent requests.

                                                                                                                                      cardIDType (object) or cardDataObject (object)
                                                                                                                                      • If the cardInstrument is included in the message it will include either:
                                                                                                                                        • cardID, which the POS received on a previous /cardReadRequest response from the EPS.
                                                                                                                                        • cardDataObject, which has the card information that the POS acquired (manual entry, scanning, or if the POS is driving a POI)
                                                                                                                                      • If the cardInstrument is NOT included in the message:
                                                                                                                                        • The EPS will know that it needs to acquire the card data at this time. The POS would not need to send an additional message to acquire the card.
                                                                                                                                      poiID
                                                                                                                                      required
                                                                                                                                      string (id80BaseType) [ 1 .. 80 ] characters

                                                                                                                                      80 character ID

                                                                                                                                      required
                                                                                                                                      object (monetaryAmount20Object)
                                                                                                                                      required
                                                                                                                                      object (posJournalEventDetailObject)

                                                                                                                                      Responses

                                                                                                                                      Request samples

                                                                                                                                      Content type
                                                                                                                                      application/json
                                                                                                                                      {
                                                                                                                                      • "connectionID": "40641ee8-8c1b-47cb-9609-70ff4318f7f5",
                                                                                                                                      • "cardInstrument": {
                                                                                                                                        },
                                                                                                                                      • "poiID": "703ef3b9-dc4b-4240-a81a-85e392ac9fb6",
                                                                                                                                      • "amount": {
                                                                                                                                        },
                                                                                                                                      • "transaction": {
                                                                                                                                        }
                                                                                                                                      }

                                                                                                                                      Response samples

                                                                                                                                      Content type
                                                                                                                                      application/json
                                                                                                                                      {
                                                                                                                                      • "statusReturn": {
                                                                                                                                        },
                                                                                                                                      • "timestamp": "2021-06-18T12:55:00",
                                                                                                                                      • "stan": "3579f517-ba52-4466-b40c-f27b2a50e39a"
                                                                                                                                      }

                                                                                                                                      /recharge/revesal

                                                                                                                                      Send a recharge reversal to the EPS. This is triggered when the connection is lost between the POS and EPS during the process of a transaction.

                                                                                                                                      Authorizations:
                                                                                                                                      apikey
                                                                                                                                        basic
                                                                                                                                          oauth2
                                                                                                                                            Request Body schema: application/json
                                                                                                                                            connectionID
                                                                                                                                            required
                                                                                                                                            string (connectionIDType) [ 1 .. 1024 ] characters

                                                                                                                                            The site reference ID is created by the Host. It is used in subsequent requests. It avoids the need to send all vendor information on subsequent requests.

                                                                                                                                            cardIDType (object) or cardDataObject (object)
                                                                                                                                            • If the cardInstrument is included in the message it will include either:
                                                                                                                                              • cardID, which the POS received on a previous /cardReadRequest response from the EPS.
                                                                                                                                              • cardDataObject, which has the card information that the POS acquired (manual entry, scanning, or if the POS is driving a POI)
                                                                                                                                            • If the cardInstrument is NOT included in the message:
                                                                                                                                              • The EPS will know that it needs to acquire the card data at this time. The POS would not need to send an additional message to acquire the card.
                                                                                                                                            poiID
                                                                                                                                            required
                                                                                                                                            string (id80BaseType) [ 1 .. 80 ] characters

                                                                                                                                            80 character ID

                                                                                                                                            required
                                                                                                                                            object (monetaryAmount20Object)
                                                                                                                                            required
                                                                                                                                            object (posJournalEventDetailObject)

                                                                                                                                            Responses

                                                                                                                                            Request samples

                                                                                                                                            Content type
                                                                                                                                            application/json
                                                                                                                                            {
                                                                                                                                            • "connectionID": "40641ee8-8c1b-47cb-9609-70ff4318f7f5",
                                                                                                                                            • "cardInstrument": {
                                                                                                                                              },
                                                                                                                                            • "poiID": "703ef3b9-dc4b-4240-a81a-85e392ac9fb6",
                                                                                                                                            • "amount": {
                                                                                                                                              },
                                                                                                                                            • "transaction": {
                                                                                                                                              }
                                                                                                                                            }

                                                                                                                                            Response samples

                                                                                                                                            Content type
                                                                                                                                            application/json
                                                                                                                                            {
                                                                                                                                            • "statusReturn": {
                                                                                                                                              },
                                                                                                                                            • "timestamp": "2021-06-18T12:55:00",
                                                                                                                                            • "stan": "3579f517-ba52-4466-b40c-f27b2a50e39a"
                                                                                                                                            }

                                                                                                                                            /balance

                                                                                                                                            Send to request the balance for a gift card.

                                                                                                                                            Authorizations:
                                                                                                                                            apikey
                                                                                                                                              basic
                                                                                                                                                oauth2
                                                                                                                                                  header Parameters
                                                                                                                                                  openretailing-connection-id
                                                                                                                                                  required
                                                                                                                                                  string (connectionIDType) [ 1 .. 1024 ] characters

                                                                                                                                                  The Site Reference ID returned in the "connect" call.

                                                                                                                                                  Responses

                                                                                                                                                  Response samples

                                                                                                                                                  Content type
                                                                                                                                                  application/json
                                                                                                                                                  {
                                                                                                                                                  • "statusReturn": {
                                                                                                                                                    },
                                                                                                                                                  • "timestamp": "2021-06-18T12:55:00",
                                                                                                                                                  • "stan": "3579f517-ba52-4466-b40c-f27b2a50e39a"
                                                                                                                                                  }

                                                                                                                                                  /cardReadRequest

                                                                                                                                                  Request the EPS to retrieve card information from POI. POI must not be locked by other workstation. The EPS must lock the POI if the request is accepted.

                                                                                                                                                  Authorizations:
                                                                                                                                                  apikey
                                                                                                                                                    basic
                                                                                                                                                      oauth2
                                                                                                                                                        Request Body schema: application/json
                                                                                                                                                        connectionID
                                                                                                                                                        required
                                                                                                                                                        string (connectionIDType) [ 1 .. 1024 ] characters

                                                                                                                                                        The site reference ID is created by the Host. It is used in subsequent requests. It avoids the need to send all vendor information on subsequent requests.

                                                                                                                                                        workstationID
                                                                                                                                                        required
                                                                                                                                                        string (id80BaseType) [ 1 .. 80 ] characters

                                                                                                                                                        80 character ID

                                                                                                                                                        poiID
                                                                                                                                                        required
                                                                                                                                                        string (id80BaseType) [ 1 .. 80 ] characters

                                                                                                                                                        80 character ID

                                                                                                                                                        required
                                                                                                                                                        string or string (followUpRequestEENUMType) <= 13 characters

                                                                                                                                                        Most common ID types.

                                                                                                                                                        object (monetaryAmount20Object)

                                                                                                                                                        Responses

                                                                                                                                                        Request samples

                                                                                                                                                        Content type
                                                                                                                                                        application/json
                                                                                                                                                        {
                                                                                                                                                        • "connectionID": "d11315d2-aa2a-4740-93d9-79383d4eccad",
                                                                                                                                                        • "workstationID": "12312321321321321312321332",
                                                                                                                                                        • "poiID": "3e08c0a1-c08b-41b6-a9b9-78cb81b868d9",
                                                                                                                                                        • "followUpRequest": "payment"
                                                                                                                                                        }

                                                                                                                                                        Response samples

                                                                                                                                                        Content type
                                                                                                                                                        application/json
                                                                                                                                                        {
                                                                                                                                                        • "statusReturn": {
                                                                                                                                                          },
                                                                                                                                                        • "cards": [
                                                                                                                                                          ]
                                                                                                                                                        }

                                                                                                                                                        /cardReadRequest

                                                                                                                                                        Request the EPS to cancel an outstanding card read request. Information about the workstation and the poi can be found in the header

                                                                                                                                                        Authorizations:
                                                                                                                                                        apikey
                                                                                                                                                          basic
                                                                                                                                                            oauth2
                                                                                                                                                              header Parameters
                                                                                                                                                              poiID
                                                                                                                                                              required
                                                                                                                                                              string (id80BaseType) [ 1 .. 80 ] characters

                                                                                                                                                              The Point of Interaction ID for the device performing the operation.

                                                                                                                                                              openretailing-connection-id
                                                                                                                                                              required
                                                                                                                                                              string (connectionIDType) [ 1 .. 1024 ] characters

                                                                                                                                                              The Site Reference ID returned in the "connect" call.

                                                                                                                                                              openretailing-workstation-id
                                                                                                                                                              required
                                                                                                                                                              string (id80BaseType) [ 1 .. 80 ] characters

                                                                                                                                                              The universal workstation ID assigned to the workstation. (Possible UUID)

                                                                                                                                                              Responses

                                                                                                                                                              Response samples

                                                                                                                                                              Content type
                                                                                                                                                              application/json
                                                                                                                                                              {
                                                                                                                                                              • "statusReturn": {
                                                                                                                                                                }
                                                                                                                                                              }

                                                                                                                                                              admin

                                                                                                                                                              Contains EPS Admin functions.

                                                                                                                                                              /workstationSettings

                                                                                                                                                              Each workstation must provide its own settings.
                                                                                                                                                              See POI Registration section of the Implementation Guide.

                                                                                                                                                              Authorizations:
                                                                                                                                                              apikey
                                                                                                                                                                basic
                                                                                                                                                                  oauth2
                                                                                                                                                                    Request Body schema: application/json
                                                                                                                                                                    connectionID
                                                                                                                                                                    required
                                                                                                                                                                    string (connectionIDType) [ 1 .. 1024 ] characters

                                                                                                                                                                    The site reference ID is created by the Host. It is used in subsequent requests. It avoids the need to send all vendor information on subsequent requests.

                                                                                                                                                                    workstationID
                                                                                                                                                                    required
                                                                                                                                                                    string (id80BaseType) [ 1 .. 80 ] characters

                                                                                                                                                                    80 character ID

                                                                                                                                                                    required
                                                                                                                                                                    string or string (workstationTypeEENUMType) <= 21 characters

                                                                                                                                                                    Types of workstations supported by the EPS.

                                                                                                                                                                    object (cashbackOptionsObject)

                                                                                                                                                                    Cashback option of EPS workstation

                                                                                                                                                                    Responses

                                                                                                                                                                    Request samples

                                                                                                                                                                    Content type
                                                                                                                                                                    application/json
                                                                                                                                                                    {
                                                                                                                                                                    • "connectionID": "d11315d2-aa2a-4740-93d9-79383d4eccad",
                                                                                                                                                                    • "workstationID": "88888-8888-88888088888-7777777",
                                                                                                                                                                    • "workstationType": "pointOfService"
                                                                                                                                                                    }

                                                                                                                                                                    Response samples

                                                                                                                                                                    Content type
                                                                                                                                                                    application/json
                                                                                                                                                                    {
                                                                                                                                                                    • "statusReturn": {
                                                                                                                                                                      }
                                                                                                                                                                    }

                                                                                                                                                                    SSE

                                                                                                                                                                    /sseEvents

                                                                                                                                                                    Returns a URL to reveive an event stream to notify the selected events to the client.
                                                                                                                                                                    Event data field conforms to the schema described in ..\schemas\apiEventDefinitions.yaml where each type of event returned is described.
                                                                                                                                                                    See POI Registration section in Implementation Guide.

                                                                                                                                                                    Authorizations:
                                                                                                                                                                    apikey
                                                                                                                                                                      basic
                                                                                                                                                                        oauth2
                                                                                                                                                                          header Parameters
                                                                                                                                                                          openretailing-connection-id
                                                                                                                                                                          required
                                                                                                                                                                          string (connectionIDType) [ 1 .. 1024 ] characters

                                                                                                                                                                          The Site Reference ID returned in the "connect" call.

                                                                                                                                                                          Responses

                                                                                                                                                                          Response samples

                                                                                                                                                                          Content type
                                                                                                                                                                          application/json
                                                                                                                                                                          {}