Merchant classic API
Version of the document
Release date Version Modifications
04.09.18 v.1.0 The first version of the document
Introduction

This documentation describes the protocol of communication between a payee and EPS payment gateway and serves as a guide for arranging acceptance of payments for goods and (or) services.
This documentation is designed for the software developers on the payee’s edge.

Glossary
Term Description
System EPS payment gateway
Payee (Recepient of payment) The company (Partner/Client) provides goods and / or services to the end user and connected to the EPS system.
Final response status The final status means that if you try to send a payment with identical parameters the response status will not change.
Payee Secret Key The payee’s secret key is used for signing requests. It is issued by the system’s staff at the time of connection.
Payee ID Key The key for identification of a payee in the system. It is issued by the system’s staff at the time of connection.
Payment System A Company (partner) connected to EPS and providing payment methods.
Type of payment method Payment methods can be two types in the system: "online" and "offline".
Online method The online method means that a payment will be made in real time. A payer will be redirected to the page of the payment system for confirmation of payment. When you use the online method, RedirectURL returns in response to initPayment request to which the payer should be redirected.
Offline method The offline methods include payment via cashier at a bank or at another payment station. When selected "Offline" method, ShowData returns in response to initPayment request. ShowData (data required to make a payment) should be displayed to a payer along with instructions for payment. In most cases it’s a payment slip.
Success URL EPS system redirects the payer to this URL after sucessful payment.
Reject URL EPS system redirects the payer to this URL after failed payment.
Waiting URL EPS system redirects the payer to this URL, if payment status is not final.
Basic principles of communication

This section describes the basic principles of communication between a payee and the System.

  • The communication is provided over HTTP 1.0;
  • JSON format is used in response to requests;
  • Request parameters are passed by the POST method.
It is required to check for compliance of the HTTP referrer and the IP address with the received data in the request. The payee must reject all requests from servers with a different IP address and/or incorrect HTTP referrer.
  Sandbox Production server
Communication URL https://api.sandbox.elementpay.io/merchant/ https://api.elementpay.io/merchant/
Client area https://client.sandbox.elementpay.io https://client.elementpay.io
The complete payment process is described below in the Sequence Diagram format:
Request format

To send a request, you should create a list of parameters and send it to the relevant method of the gateway in HTTP 1.0 format.

Example:
https://api.sandbox.elementpay.io/merchant/<method>?p1=valueN1&p2=value2&pN=valueN
Description:

<method> - method in the gateway, param1 - key, value1 - value.

Request attributes must be passed by the POST method.

Response format

During communication with the system the response always comes in JSON format and encoded in UTF-8.

If the request is successful, you will receive the response node:

{
    "response": {
        "id": 502,
        "order": "r126",
        "service": {
            "id": 77,
            "name": "PayPal",
            "type": "online"
        },
        "amount": "25.00",
        "status": 205,
        "date": "2017-02-23T06:55:40.000Z",
        "timestamp": 1424750724
    },
    "hash": "14c7aa90376ccbfd45561f03499928ee4ddfd092"
}

If the request is incorrect, you will receive the error node:

{
    "error": {
        "code": 402,
        "message": "Wrong merchant key",
        "timestamp": 1424750754
    }
}

The reply for the response node always includes the hash parameter which must be used for verification.

Algorithm for calculating of hash

Each request and response must be signed with the private key of the payee using methodology with sha1 function.

Calculation of hash for request

To receive hash for a request you must calculate using the secret key from the list of parameters with the values in the following format:

<method>?p1=value1&p2=value2&p3=valueN

Example, request getMethods:

https://api.sandbox.elementpay.io/merchant/getMethods?key=d7197e2e-6d89-11e4-8e91-d876c67f2a53&timestamp=1422959773127&hash=22cc3b22595f98dcc36309aeef691cce0c937bd5

In this case, the signature is calculated from a line:

getMethods?key=d7197e2e-6d89-11e4-8e91d876c67f2a53&timestamp=1422959773127

Calculation hmac:

hmac(
    "80eb8c9793949bc6682baffdb4dd5303542581ed",
    "getMethods?key=d7197e2e-6d89-11e4-8e91d876c67f2a53&timestamp=1422959773127"
)

where 80eb8c9793949bc6682baffdb4dd5303542581ed - secret key

Hash is:

22cc3b22595f98dcc36309aeef691cce0c937bd5
Calculation of hash for response

To verify the hash in response it is necessary to calculate hmac from response node. Example:

{
    "response": {
        "id": 324,
        "order": "100500",
        "service": {
            "id": 77,
            "name": "PayPal",
            "type": "online"
        },
        "amount": 10,
        "status": "203",
        "date": "2017-01-10T18:31:07.000Z",
        "timestamp": 1424613004
    },
    "hash": "1d0e3e0a6c7dc0883b5acd2a0ef4487a2c712928"
}

Calculation of hash

hmac(
    '80eb8c9793949bc6682baffdb4dd5303542581ed',
    '{"id":324,"order":"100500","service":{"id":77,"name":"PayPal","type":"online"},"amount":10,"status":"203","date":"2017-01-10T18:31:07.000Z","timestamp":1424621689}'
)

Hash is:

594e08602750b499ad5c48a9b7f537156f7dca25
Group of requests from the payee to the system
Receiving a list of payment methods (/getMethods)
Description:

The method returns a list of available payment methods for payee

URL:
Sandbox:
https://api.sandbox.elementpay.io/merchant/getMethods
Production server:
https://api.elementpay.io/merchant/getMethods
Request parameters:
Parameter Mandatory Description Format
key Payee ID Key UUID
timestamp Timestamp at the moment of forming a request Unix timestamp
hash Request signature Alphabetic (40 characters) hmac, sha1
Example of the request:
https://api.sandbox.elementpay.io/merchant/getMethods?key=d7197e2e-6d89-11e4-8e91-d876c67f2a53&timestamp=1424750824&hash=2c342a80f201383338103687a262b0597f9a892a
Example of the response:
{
    "response": {
        "methods": [
            {
                "id": 77,
                "name": "PayPal",
                "type": "online",
                "min": "1.00",
                "max": "15000.00",
                "commission": {
                    "fix": "0.00",
                    "rate": "0.00"
                },
                "category": "Electronic Money",
                "image": null,
                "attributes": []
            },
            {
                "id": 78,
                "name": "DragonPay",
                "type": "online",
                "min": "7.52",
                "max": "7517.00",
                "commission": {
                    "fix": "10.00",
                    "rate": "0.00"
                },
                "category": "Electronic Money",
                "image": null,
                "attributes": [
                    {
                        "name": "DragonPay email",
                        "description": "email for send invoice",
                        "key": "email",
                        "regexp": "^[_a-z0-9-]+(\\.[_a-z0-9-]+)*@[a-z0-9-]+(\\.[a-z0-9-]+)*(\\.[a-z]{2,4})$",
                        "required": true
                    }
                ]
            }
        ],
        "status": 200,
        "timestamp": 1424750862
    },
    "hash": "2ae1d8e4ca9764f3ebf33d0f50d313e54019f09f"
}
Response description:
Object Description
response.methods Collection of objects of payment methods
response.methods[i].id ID of the payment method in the system
response.methods[i].name Name of the payment method
response.methods[i].min Minimal payment amount in the currency of the payee
response.methods[i].max Maximum payment amount in the currency of the payee
response.methods[i].commission Object with the information about the commission of the payment method
response.methods[i].commission.fix Fixed commission charged for payment in the currency of the payee
response.methods[i].commission.rate Interest charged for payment in the currency of the payee
response.methods[i].category Category of the payment method
response.methods[i].image Logo of the payment method
response.methods[i].type Type of the payment method, interpretation in glossary
response.methods[i].attributes An array of attributes to be passed upon request to initialize payment
response.methods[i].attributes[i].name Name of the attribute
response.methods[i].attributes[i].description Description of the attribute
response.methods[i].attributes[i].key Key of the attribute that must be passed for identification of the attribute in the System.
response.methods[i].attributes[i].regexp The regular expression used to validate the attribute value
response.methods[i].attributes[i].required Requirement for the attribute when passing it in the request for the initialization of payment
response.status The status of the request
response.timestamp The timestamp
hash Response hash
Response statuses:
Status Type of the node Final Description
200 response The request has been successfully processed
401 error Invalid request hash
402 error Invalid Payee ID key
404 error Mandatory attribute is missing
405 error Invalid format of the attribute
500 error   Internal server error
Payment initialization (/initPayment)
Description

This method is used to initialize payment by a selected payment method. The response includes information to be displayed to the user or redirect-URL to confirm the user’s intention to make payment.

URL:
Sandbox:
https://api.sandbox.elementpay.io/merchant/initPayment
Production server:
https://api.elementpay.io/merchant/initPayment
Request parameters:
Parameter Mandatory Description Parameter's format
service_id Payment method ID Int (1— 99999 characters)
amount Amount of payment in the currency of the payee Float (0.01 — 999999.99 monetary units)
order Payment ID in the payee’s system. The parameter must be unique for each payment. Alphabetic (1— 64 characters)
user_parameter   Additional parameters of payment required by the payment system, which come to "attributes" in response to “getMethods”. Must be verified by Regexp.
key Payee ID Key UUID
_successUrl   Sucess URL URL
_waitingUrl   Waiting URL URL
_rejectUrl   Reject URL URL
timestamp Timestamp at the moment of Unix timestamp request formation. Unix timestamp
hash Request signature Alphabetic (40 characters) hmac, sha1
Example of the request:
https://api.sandbox.elementpay.io/merchant/initPayment?order=order121&amount=1000.00&service_id=77&key=d7197e2e-6d89-11e4-8e91-d876c67f2a53&timestamp=1424750966&hash=21ba1970feb0944fddf4f8d19a611c5d6b61634a
Example of the response:
{
    "response": {
        "id": 513,
        "order": "order121",
        "service": {
            "id": 77,
            "name": "PayPal",
            "type": "online"
        },
        "amount": "1000.00",
        "attributes": [
            {
                "name": null,
                "description": null,
                "key": "redirectUrl",
                "value": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-4XG55868434*****D"
            }
        ],
        "status": 206,
        "timestamp": 1424751008
    },
    "hash": "096b3bbd2c61aafe2bdf9c1fa5ebd88a502c8666"
}
Response description
Object Description
response Object with response
response.id Payment ID in the system
response.order Payment ID in the payee’s system
response.service Object with information about a payment method
response.service.id Payment method ID
response.service.name Name of the payment method
response.service.type Type of the payment method: «online» or «offline»
response.amount Amount of payment in the currency of the payee
response.attributes The collection of returnable attributes
response.attributes.name Name of the attribute
response.attributes.description Description of the attribute
response.attributes.key Key of the attribute, interpretation in glossary "online" or "offline" method
response.attributes.value Value of the attribute
response.status Response status
response.timestamp Unix timestamp
hash Response hash
Statuses
Status Type of the node Final Description
204 response Payment is rejected
206 response Payment is pending
401 error Invalid request's hash
402 error Invalid Payee ID Key
404 error Required attribute is missing
405 error Invalid format of the attribute
406 error The amount of payment is less than the minimum possible at a selected payment method
407 error The amount of payment larger than the maximum possible in a selected payment method
413 error The amount of payment is less than commission
479 error This payment ID already exists in the system
483 error This payment method is not available
500 error   Internal server error
545 error This merchant is blocked, contact support
583 error The payment system provides payment method is blocked
999 response   Unknown status, contact support
Getting the status of payment(/getStatus)
Description:

This method is used for getting the payment status in the system.

URL:
Sandbox:
https://api.sandbox.elementpay.io/merchant/getStatus
Production server:
https://api.elementpay.io/merchant/getStatus
Request parameters
Parameter Mandatory Description Parameter's format
payment_id   Payment ID in the system int (1— 999999999 characters)
order Payment ID in the payee’s system alphabetic (1 — 64 characters)
key Payee ID Key UUID
timestamp Timestamp at the moment of Unix timestamp request formation. Unix timestamp
hash Request signature Alphabetic (40 characters) hmac, sha1
Example of the request:
https://api.sandbox.elementpay.io/merchant/getStatus?payment_id=513&key=d7197e2e-6d89-11e4-8e91-d876c67f2a53&timestamp=1424751109&hash=f6a3dfe279a37ec5a9447a156ce62171e71ae950
Example of the response:
{
    "response": {
        "id": 513,
        "order": "order121",
        "service": {
            "id": 77,
            "name": "PayPal",
            "type": "online"
        },
        "amount": "1000.00",
        "status": 206,
        "date": "2017-02-24T04:10:04.000Z",
        "timestamp": 1424751146
    },
    "hash": "4345b20a1a85df84bffa14b6892f74e0e07c339d"
}
Response description
Object Description
response Object with response
response.id Payment ID in the system
response.order Payment ID in the payee’s system
response.service Object with information about the payment method
response.service.id Payment method ID
response.service.name Name of the payment method
response.service.type Type of the payment method: «online» or «offline»
response.amount Payment amount in the currency of the payee
response.status Response status
response.date Date and time of payment creation
response.timestamp Unix timestamp
hash Response hash
Response statuses
Status Type of the node Final Description
201 response Payment is in the processing queue
203 response   Payment in the processing
204 response Payment is rejected
205 response Payment has been successfully completed
206 response Waiting for payment by the payer
207 response Payment is returned
401 error Invalid hash of request
402 error Invalid Payee ID Key
404 error Mandatory attribute is missing
405 error Invalid attribute format
474 error Payment with the specified parameters is not found
500 error   Internal server error
999 response   Unknown status, contact support
Group of requests from the system to the payee
Check for the possibility of payment processing (method=check)
Description:

After payment is confirmed by the payer (user), the system sends a request for validation of payment data.

Request parameters
Parameter Mandatory Description Parameter's format
method Specifies the method to which you send a request method=check
id Payment ID in the system int (1—999999999 characters)
service_id Payment method ID int (1—999999999 characters)
amount Payment amount in the currency of the payee float (0.01 — 999999.99 monetary units)
order Payment ID in the payee’s system Alphabetic (1 — 64 characters)
timestamp Timestamp at the time of request Unix timestamp
attributes[ parameter ]   Custom additional options/parameters
hash Request hash Alphabetic (40 characters)
Example of the request:
https://api.sandbox.elementpay.io/?method=check&id=502&service_id=77&amount=25.00&order=r126&timestamp=1424674668&hash=16615f7112325d80e2641120c2640783a5f77206
Example of the responce:
{
    "response": {
        "status": 270,
        "message": "Account exist",
        "timestamp": 1424674668582
    },
    "hash": "d92bbcfee3be0cdad9e2b4cfe3cdf045fcc714fa"
}
Response parameters
Object Description
response Object with response
response.status Verification status
response.message Description of the status
response.timestamp Unix timestamp
hash Response Hash
Status codes
Status Type of the node Final Description
270 response Payment with the specified parameters can be processed
475 response Payment with the specified parameters can not be processed
401 error Invalid request hash
500 error   Internal server error
Notification about completion of payment (method=pay)
Description

Notification of the payee about completed payment

Request parameters
Parameter Required Description Parameter's format
method Specifies the method to which you send a request method=pay
id Payment ID in the system int (1 — 999999999 characters)
service_id Payment method ID int (1 — 999999999 characters)
amount Payment amount in the currency of the payee float (0.01 — 999999.99 monetary units)
order Payment ID in the payee’s system Alphabetic (1 — 64 characters)
timestamp Unix timestamp at the time of the request Unix timestamp
attributes[ parameter ]   Custom additional parameters required by the payment system
hash Request hash Alphabetic (40 characters)
Example of the request
https://api.sandbox.elementpay.io/method=pay&id=502&service_id=77&amount=25.00&order=r126&timestamp=1424674671&hash=2bee2c78c27501a299106eee73e5bf528c7df71b
Example of the response
{
    "response": {
        "status": 205,
        "message": "Payment success",
        "timestamp": 1424674671372
    },
    "hash": "73f36eae3751a97522ac8639f813c37b0785dc3c"
}
Response parameters
Object Description
response Object with response
response.status Payment status
response.message Description of the status
response.timestamp Unix timestamp
hash Response Hash
Status codes
Status Type of the node Final Description
204 response Payment is rejected
205 response Payment has been successfully completed
206 response   Payment is under processing
474 response Payment with the specified parameters is not found in the payee's system
401 error Invalid request hash
500 error   Internal server error
Request for payment status (method=status)
Description

This method is used to get payment status if the system has received an ambiguous response to the notification of payment.

Request parameters
Parameter Mandatory Description Parameter's format
method Specifies the method to which you send a request method=status
id   Payment ID in the system int (1 — 999999999 characters)
order Payment ID in the payee’s system Alphabetic (1 — 64 characters)
timestamp Unix timestamp at the time of the request Unix timestamp
hash Request hash Alphabetic (40 characters)
Example of the request:
https://api.sandbox.elementpay.io/?method=status&id=502&order=r126&timestamp=14246746713&hash=caed48f13e075045c8e6364e385a2a67e7750f73
Example of the response:
{
    "response": {
        "status": 205,
        "message": "Payment success",
        "timestamp": 1424679671372
    },
    "hash": "73f36eae3751a97522ac8639f813c37b0785dc3c"
}
Response parameters
Object Description
response Object with response
response.status Payment status
response.message Description of the status
response.timestamp Unix timestamp
hash Response Hash
Status codes
Status Type of the node Final Description
201 response The payment was not paid
204 response Payment is rejected
205 response Payment has been successfully completed
206 response   Payment is under processing
207 response Payment is returned
474 response Payment with the specified parameters is not found in the payee's system
401 error Invalid request hash
500 error   Internal server error
Redirect URL's
Description

EPS system redirects the payer to «Success URL», «Reject URL» or «Waiting URL» depending on status of the payment.

Redirect URL parametrs:
Parameter Mandatory Description Parameter's format
pid Payment ID in the system int (1— 999999999 characters)
iorder Payment ID in the payee’s system alphabetic (1 — 64 characters)
Example of the request:
https://{redirect_url}?pid=123&order=435hf


CMS Plugins
Name Software Versions Downloads
Wordpress v4.3 - 5.x (PHP 7.x)
  • PHP v7.2 or later
  • WooCommerce v3.3.4 or later
v2.0.9 [zip] (30.7 Kb)
md5: 421923d90a734108069bc1f1b7ea2ead
PrestaShop v1.7
  • PHP v5.6.x — 7.x
v1.0.2 [zip] (80.3 Kb)
md5: 4457f56a3ae8d6da7c51e7d97e6d0d0b
Drupal v7.67 or later
  • Drupal commerce v1.15 or later
  • PHP v5.6 or later
v7.x-2.5 [tar.gz] (52.3 Kb)
md5: 3eaadda19e0150c85c7adfe668753562
Drupal v8.7.10 or later
  • Drupal commerce v2.15 or later
  • PHP v7.1 or later
v8.x-1.4 [tar.gz] (9.8 Kb)
md5: e679b197f6f1ccb4858b84b0b250b78d
Contact Us