ExPay Logo

We're committed to helping your
business run better.

Merchant classic API

Version of the document
Release date Version Modifications
20.12.14 v.1.0 The first version of the document
21.02.15 v.1.1 Renamed attribute previous version: response.methods[i].attributes[j].type New version: response.methods[i].attributes[i].required
03.03.15 v.1.2 1. Added new status "999" for method (/initPayment) and (/getStatus).
2. Added status "203" for method (/getStatus)
22.03.15 v.1.3 1. Added description of «Sucess URL» to glossary.
2. Added description of «Reject URL» to glossary.
3. Added description of «Waiting URL» to glossary.
4. Added section «Redirect URL’s»
5. Added request parametr «_successUrl», «_rejectUrl» and «_waitingUrl» to (/initPayment)
30.03.15 v.1.4 Added new status «413» for methos (/initPayment)
18.02.20 v.1.5 Updated statuses of response for callbacks. Updated description of /getStatus method

Introduction

This documentation describes the protocol of communication between a payee and expay 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 Expay payment gateway
Payee (Recepient of payment) The company (Partner/Client) provides goods and / or services to the end user and connected to the expay 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 expay 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.
Sucess URL Expay system redirects the payer to this URL after sucessful payment.
Reject URL Expay system redirects the payer to this URL after failed payment.
Waiting URL Expay 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
IP-address 54.169.228.181 52.76.228.42
52.76.227.77
Communication URL https://api.sandbox.expay.asia/merchant/ https://api.expay.asia/merchant/
Client area https://client.sandbox.expay.asia/ https://client.expay.asia/

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.expay.asia/merchant/<method>?param1=value1&param2=value2&paramN=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. Example: 

{
  "response": {
    "id": 502,
    "order": "r126",
    "service": {
      "id": 77,
      "name": "PayPal",
      "type": "online"
    },
    "amount": "25.00",
    "status": 205,
    "date": "2015-02-23T06:55:40.000Z",
    "timestamp": 1424750724
  },
  "hash": "14c7aa90376ccbfd45561f03499928ee4ddfd092"
}
If the request is incorrect, you will receive the error node. Example: 

{
  "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 hmac methodology with sha1 function.

Calculation of hash for request

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

<method>?param1=value1&param2=value2&paramN=valueN

Example, request getMethods:

https://api.sandbox.expay.asia/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": "2015-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":"2015-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.expay.asia/merchant/getMethods

Production server:

https://api.expay.asia/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.expay.asia/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.expay.asia/merchant/initPayment

Production server:

https://api.expay.asia/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.expay.asia/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.expay.asia/merchant/getStatus

Production server:

https://api.expay.asia/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.expay.asia/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": "2015-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 has been paid. Waiting response from merchant's side
204 response √ Payment is rejected
205 response √ Payment has been successfully completed
206 response   Waiting for payment by the payer
207 response √ Payment is refunded
208 response   Disputable state. Payment has been paid, but merchant rejected it on "Pay" notification
209 response   Payment has been canceled by bank
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:

http(s)://sp_url/?method=check&id=502&service_id=77&amount=25.00&order=r126&timestamp=1424674668&hash=16615f7112325d80e2641120c2640783a5f77206

Example of the response:


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

http(s)://sp_url/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:

http(s)://sp_url/?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 refunded
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

RedirectURL's

Description

Expay 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)
order √ Payment ID in the payee’s system alphabetic (1 — 64 characters)

Example of the request:

http(s)://<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.1.9 [zip] (31.4 Kb)
md5: 5bf6500befa68a85117499b604261870
PrestaShop v1.7
  • PHP v5.6.x — 7.x
 v1.0.4 [zip] (80.7 Kb)
md5: e90d6254e9f2d8583866db8651be98ba
Drupal v7.67 or later
  • Drupal commerce v1.15 or later
  • PHP v5.6 or later
 v7.x-1.0.4 [tar.gz] (52.5 Kb)
md5: 9cbb422268852258cbd89ac1a42ce47d
Drupal v8.7.10 or later
  • Drupal commerce v2.15 or later
  • PHP v7.1 or later
 v8.x-1.6 [tar.gz] (9.7 Kb)
md5: 17fb34b62628ef10331b58a1ba57074e
CONNECT WITH US
038 236 005
General questions? Lost and need help? Talk to Sales

© 2014—2024 Expay Group Co. Ltd

Please feel free to contact us if you have any questions:
Contact person:
You can also email us:

info@expay.asia

Your request has been sent successfully!

We will contact you within 24 hours.
Sign up for accepting payments via expay:
Contact person:
Company information:
*By signing in you agree to the Terms & Conditions and Privacy Policy.

Your request has been sent successfully!

We will contact you within 24 hours. For more information you can
write to us at sale@expay.asia