Simple Pay System - Merchant API

Merchant classic API

Version of the document

Release date	Version	Modifications
07.01.19	v.1.0	The first version of the document

Introduction

This documentation describes the protocol of communication between a payee and SPS 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	SPS payment gateway
Payee (Recepient of payment)	The company (Partner/Client) provides goods and / or services to the end user and connected to the SPS 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 SPS 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	SPS system redirects the payer to this URL after sucessful payment.
Reject URL	SPS system redirects the payer to this URL after failed payment.
Waiting URL	SPS 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-sbox.simplepay.asia/merchant/	https://api.simplepay.asia/merchant/
Client area	https://client-sbox.simplepay.asia	https://client.simplepay.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-sbox.simplepay.asia/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-sbox.simplepay.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&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-sbox.simplepay.asia/merchant/getMethods

Production server:

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

Production server:

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

Production server:

https://api.simplepay.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-sbox.simplepay.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": "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-sbox.simplepay.asia/?method=check&id=502&service_id=77&amount=25.00&order=r126×tamp=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-sbox.simplepay.asia/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:

https://api-sbox.simplepay.asia/?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 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

SPS 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://?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.6 Kb) md5: a09a602740f26ff2f4e81b32ac6d86fb
PrestaShop v1.7	PHP v5.6.x — 7.x	v1.0.4 [zip] (81.3 Kb) md5: 6b0763715eb28f32aec78a1aeff1e7c5
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: b4241f453759cf57e74cbf33e4a10d51
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: 2f70d096171d49c325cd42705aa49c64