API docs 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

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:
apikeybasicoauth2
header Parameters
openretailing-connection-id
required
string (connectionIDType) [ 1 .. 1024 ] characters

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

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.

Array of objects (promptingTextArray) [ 0 .. 500 ] items
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:
apikeybasicoauth2
header Parameters
openretailing-connection-id
required
string (connectionIDType) [ 1 .. 1024 ] characters

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

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.

Array of objects (promptingTextArray) [ 0 .. 500 ] items
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:
apikeybasicoauth2
header Parameters
openretailing-connection-id
required
string (connectionIDType) [ 1 .. 1024 ] characters

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

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:
apikeybasicoauth2
header Parameters
openretailing-connection-id
required
string (connectionIDType) [ 1 .. 1024 ] characters

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

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.

Array of objects (promptingTextArray) [ 0 .. 500 ] items
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:
apikeybasicoauth2
header Parameters
openretailing-connection-id
required
string (connectionIDType) [ 1 .. 1024 ] characters

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

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.

Array of objects (promptingTextArray) [ 0 .. 500 ] items
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:
apikeybasicoauth2
header Parameters
openretailing-connection-id
required
string (connectionIDType) [ 1 .. 1024 ] characters

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

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:
apikeybasicoauth2
header Parameters
openretailing-connection-id
required
string (connectionIDType) [ 1 .. 1024 ] characters

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

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:
apikeybasicoauth2
header Parameters
openretailing-connection-id
required
string (connectionIDType) [ 1 .. 1024 ] characters

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

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)
Array of objects (promptingTextArray) [ 0 .. 500 ] items
object (originalStanDataObject)

The STAN and datetime from the original transaction.

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:
apikeybasicoauth2
header Parameters
openretailing-connection-id
required
string (connectionIDType) [ 1 .. 1024 ] characters

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

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)
Array of objects (promptingTextArray) [ 0 .. 500 ] items
object (originalStanDataObject)

The STAN and datetime from the original transaction.

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:
apikeybasicoauth2
header Parameters
openretailing-connection-id
required
string (connectionIDType) [ 1 .. 1024 ] characters

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

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:
apikeybasicoauth2
path Parameters
reconciliationID
required
string (id40BaseType) [ 1 .. 40 ] characters

Reconciliation identifier for the EPS.

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}/cardSalesAccruals/data

Send a request to retrieve the sales accruals data from the EPS by card type

Authorizations:
apikeybasicoauth2
path Parameters
reconciliationID
required
string (id40BaseType) [ 1 .. 40 ] characters

Reconciliation identifier for the EPS.

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:
apikeybasicoauth2
path Parameters
reconciliationID
required
string (id40BaseType) [ 1 .. 40 ] characters

Reconciliation identifier for the EPS.

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:
apikeybasicoauth2
path Parameters
reconciliationID
required
string (id40BaseType) [ 1 .. 40 ] characters

Reconciliation identifier for the EPS.

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:
apikeybasicoauth2
path Parameters
reconciliationID
required
string (id40BaseType) [ 1 .. 40 ] characters

Reconciliation identifier for the EPS.

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:
apikeybasicoauth2
path Parameters
reconciliationID
required
string (id40BaseType) [ 1 .. 40 ] characters

Reconciliation identifier for the EPS.

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:
apikeybasicoauth2
path Parameters
reconciliationID
required
string (id40BaseType) [ 1 .. 40 ] characters

Reconciliation identifier for the EPS.

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:
apikeybasicoauth2
path Parameters
reconciliationID
required
string (id40BaseType) [ 1 .. 40 ] characters

Reconciliation identifier for the EPS.

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:
apikeybasicoauth2
header Parameters
openretailing-connection-id
required
string (connectionIDType) [ 1 .. 1024 ] characters

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

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:
apikeybasicoauth2
header Parameters
openretailing-connection-id
required
string (connectionIDType) [ 1 .. 1024 ] characters

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

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:
apikeybasicoauth2
header Parameters
openretailing-connection-id
required
string (connectionIDType) [ 1 .. 1024 ] characters

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

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:
apikeybasicoauth2
header Parameters
openretailing-connection-id
required
string (connectionIDType) [ 1 .. 1024 ] characters

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

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:
apikeybasicoauth2
header Parameters
openretailing-connection-id
required
string (connectionIDType) [ 1 .. 1024 ] characters

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

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/reversal

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:
apikeybasicoauth2
header Parameters
openretailing-connection-id
required
string (connectionIDType) [ 1 .. 1024 ] characters

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

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"
}

/balanceRequest

Send to request the balance for a gift card.

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

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

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

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"
}

Response samples

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

/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:
apikeybasicoauth2
header Parameters
openretailing-connection-id
required
string (connectionIDType) [ 1 .. 1024 ] characters

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

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)
required
string (cardAcquisitionModeENUMType) <= 9 characters

This field defines the mode in which a card should be acquired on the POI. This functionality enables swipe ahead. There are two modes: immediate and wait immediate: expect a card to be immediately acquired once POI is enabled. wait: expect POI to be enabled and waiting for a card to be acquired (swipe-ahead)

string (acquireLoyaltyENUMType) <= 9 characters

This field defines the mode in which a loyalty account should be acquired on the POI. This functionality enables acquiring both loyalty cards and/or payment cards. There are three modes: yes, no, only yes: Acquire a loyalty account no: Do not acquire a loyalty account only: Only expect a loyalty ID

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

After receiving the cardDataAvailable event, request the card acquired in the event from the EPS.

Authorizations:
apikeybasicoauth2
path Parameters
event-id-parameter
string (description40BaseType) <= 40 characters

The event ID of the event sent via SSE

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": {
    },
  • "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:
apikeybasicoauth2
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": {
    }
}

/lineDisplay

Provides the line display text to the EPS to be displayed at the POI

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

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

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
Array of objects (lineDisplayTextArray) <= 20 items

An array of line Display Text Objects.

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": [
    ]
}

/epsTokenExchange

Provides the eps token to the EPS

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

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

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
string (id80BaseType) [ 1 .. 80 ] characters

80 character ID

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

80 character ID

required
object (cardIDType)

If the request is preceded by a POI/cardReader request.

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": [
    ]
}

admin

Contains EPS Admin functions.

/workstationSettings

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

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

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

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:
apikeybasicoauth2
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
{}