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
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
- The communication is provided over HTTP 1.0
- JSON format is used in response to requests.
- Request parameters are passed by the POST method.
Sandbox | Production server | |
IP-address | 54.169.228.181 | 52.76.228.4252.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
Example:
https://api.sandbox.expay.asia/merchant/<method>?param1=value1¶m2=value2¶mN=valueN
Response format
{
"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"
}
{
"error": {
"code": 402,
"message": "Wrong merchant key",
"timestamp": 1424750754
}
}
Algorithm for calculating of hash
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¶m2=value2¶mN=valueN
Example, request getMethods:
https://api.sandbox.expay.asia/merchant/getMethods?key=d7197e2e-6d89-11e4-8e91-d876c67f2a53×tamp=1422959773127&hash=22cc3b22595f98dcc36309aeef691cce0c937bd5
In this case, the signature is calculated from a line:
getMethods?key=d7197e2e-6d89-11e4-8e91d876c67f2a53×tamp=1422959773127
Calculation hmac:
hmac("80eb8c9793949bc6682baffdb4dd5303542581ed", "getMethods?key=d7197e2e-6d89-11e4-8e91d876c67f2a53×tamp=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×tamp=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×tamp=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×tamp=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×tamp=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×tamp=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×tamp=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) |
|
v2.1.9
[zip] (31.4 Kb) md5: 5bf6500befa68a85117499b604261870 |
PrestaShop v1.7 |
|
v1.0.4
[zip] (80.7 Kb) md5: e90d6254e9f2d8583866db8651be98ba |
Drupal v7.67 or later |
|
v7.x-1.0.4
[tar.gz] (52.5 Kb) md5: 9cbb422268852258cbd89ac1a42ce47d |
Drupal v8.7.10 or later |
|
v8.x-1.6
[tar.gz] (9.7 Kb) md5: 17fb34b62628ef10331b58a1ba57074e |