EML OMS Platform (v1.0)

The EML Payments API exposes information and processing as a suite of web services adopting the Representational State Transfer (REST) architectural style. Key API concepts are:

• Resources – The "things" that are important, such as cards and transactions.
• URIs – The name and address of a resource.
• Stateless – Each request should provide all the information necessary to complete the request such as authentication credentials.
• Uniform Interface – HTTP verbs (GET, POST, PUT and DELETE) are preferred over specifying custom verbs in URIs or request bodies.
• Representations – Some data about the current state of a resource such as a JSON object serialization or XML document.

Clients will be assigned a user name and password for API access. HTTP Basic Authentication as described in RFC 2617 will be used to pass credentials. Each user name will be granted specific rights to view and manipulate resources.

The Cache-Control response header will be used to specify caching directives. Many representations are created dynamically for each request and should not be cached. These services will return the Cache-Control: no-cache header.

Some services provide duplicate transaction checking via an optional header named Idempotency-Key. If provided, this header should contain a string that is unique across a program and is up to 255 characters in length. The idempotency key will be checked against a local store for duplicates. If a duplicate is found, the last response for that idempotency key will be returned. It is important to note that the actual contents of the transaction are not checked for duplication at this time – only the idempotency key. In addition, the keys and responses are only retained for approximately seven days.

If there is a duplicate transaction, a header named X-Eml-Duplicate will be returned with a value of true. This header is only returned if a duplicate was detected.

Example

{

"code": 500,

"message": "Server Error"

}

The services will provide localized values for strings where possible. Clients should provide the ACCEPT-LANGUAGE header to indicate their preferred language. If this header is not specified, the default is US English (en-US). Generally speaking, data will be formatted using an invariant culture. User-facing strings, such as transaction descriptions, will be localized where possible.

Resource representations in JSON and XML are available. Responses will be provided in UTF-8 encoding. Clients may specify the desired response format by providing an Accept header. JSON is the default format if no Accept header is provided.

The format of representations passed in request bodies may be specified using the Content-Type header. JSON is the default format if no Content-Type header is provided.

Response representations will contain minimal whitespace. XML representations have an element-centric structure.

Request status information will be communicated through HTTP response codes. The following table lists common response codes from HTTP/1.1 specification.

Card Identifier Card Identifier – {card_id} – Is a string value that uniquely identifies a card in several requests. When present this value is used in conjunction with the search_parameter value explained below to uniquely identify a card.

• https://webservices.storefinancial.net/api/v1/en
  • /cards
    • /{card_id}
      • /refunds
      • /refund_reversals
      • /transactions
      • /activations
      • /locks
      • /unlocks
      • /voids
      • /reloads
      • /register
      • /transfer
      • /pin
    • /new
      • /activations
      • /batch_activations
    • /{token}
      • /display
  • /agreements
  • /transmissions
    • /{card_id}
      • /resend_fax
  • /b2b
    • /payee
      • /{program}
        • /{client_payee_id}
          • /delete
      • /{client_payee_id}
        • /enroll
        • /update

Common Query String Values

These query string parameter values may be used in multiple requests.

Country Codes

The */country request field accepts values as defined in ISO 3661-1 alpha-3 code.

Sample

"location" : {

"name": "Location Name",

"province": "MB"

"country": "CAN"

},

State and Province Codes

The */state and */province request fields accept values as defined in ISO 3166-2.

Samples

State "location" : { "name": "Location Name", "state" : "CA", "country" : "USA" },

Province "location" : { "name": "Location Name", "province" : "MB", "country" : "CAN" },

Multiple Requests

For requests which can return multiple results, the following additional request and response fields will be used.

Samples

JSON Request GET https://webservices.storefinancial.net/api/v1/en/entities?skip=0&take=3 HTTP/1.1 Accept: application/json Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Response { "count" : 15; "entities" : [ { "result_field_1" : "1234567890123456"; "result_field_2" : 0.00 }; { "result_field_1" : "2345678901234567"; "result_field_2" : 10.00 }; { "result_field_1" : "3456789012345678"; "result_field_2" : 20.00 }] }

A provider wishing to take part in EML ControlPay must implement specific API endpoints that will be used during delegated authorization scenarios. The endpoint's service and message requirements are defined in this document. Before a provider will be allowed to integrate with EML's processing system, conformance to this document will be validated by a certification process.

The endpoint defined is only part of the full integration. In addition to the behaviors defined in this document, providers may wish to receive various transaction notifications like adjustments, settlements, and expirations. For further information, please review the Notifications section.

Participation

Participation in this service is restricted to registered clients. To register, clients must provide EML with the URL and authentication credentials for their externally exposed delegated authorization endpoint. EML will use TLS transport with the HTTP basic authentication scheme (https://www.ietf.org/rfc/rfc2617.txt) to connect to the specified endpoint. EML will not support custom port numbers.

Message Types

A registered client will receive the following message types with fields of the listed data types.

Data Types

Error Message and Error Handling

When error conditions arise, the provider is expected to conform to REST guidelines for using the HTTP status code. If the provider's system is operating normally, status codes will generally be in the 200 or 400 range of status codes. If the provider's system is experiencing technical difficulties, then status codes will generally be in the 500 range of status codes. A few examples of specific status codes are below and further guidelines may be found here, https://www.restapitutorial.com/lessons/restquicktips.html.

In addition to the HTTP status code, the provider is expected to return an error message in the body with provider specific information. Note that the code in the error response message should not match the HTTP status code. The response message's code is intended for a provider specific error ID that may be used for further troubleshooting. An error message should also be returned that provides more information about the specific error.

{

code: integer,

message: string

}

The Express Transfer API provides endpoints for validating and moving funds from an EML card to a non-EML card using the MasterCard® network. These endpoints are not enabled by default and must be authorized for use. Additionally, an EML program must be configured to enable the Express Transfer feature and not all cards can receive express transfers. The receiving card must be configured to receive funds. It is also possible to send funds to a non-MasterCard card that participate in the MasterCard service.

The operations support more than one type of token to use in validations and payment transfers. The type and format are listed below.