2.2. Pay365 Integration¶
2.2.1. General Sale Process Flow via Pay365 API¶
Merchant initiates a transaction by sending HTTPS POST request to the specified URL.
Payneteasy server immediately returns the response back to Merchant. The response contains paynet-order-id (for detailed request and response format see Request parameters table).
Merchant shows the Customer custom message, e.g. Your order is being processed. Please, wait….
Merchant starts polling Payneteasy server for transaction status using paynet-order-id obtained at previous step. Status polling request and response are described in “Order status”.
Payneteasy drives the transaction process with Pay365 processor.
Pay365 along with Customer’s mobile network operator sends confirmation request on Customer’s mobile phone, and if Customer confirms the transaction, Pay365 processes this payment.
After receiving transaction’s final status from Pay365, Payneteasy responds to status request with transaction’s final status.
Payneteasy also schedules the callback to merchant with all transaction details when the transaction gets it’s final status.
Checkout order Customer checks out the order on Merchant’s website.
Pay365 sale request Merchant sends Pay365 sale request to Payneteasy server with specified parameters described in “Pay365 Sale Request parameters”.
Status request Merchant is polling for status with given orderid as described in Order status. Payneteasy responds with status=processing until final status is reached.
Process sale Payneteasy server initiates the transaction with Pay365 processor.
Confirmation request Pay365 along with Customer’s mobile network operator sends confirmation request on Customer’s mobile phone.
Confirmation response Customer confirms the transaction on his mobile phone.
Sale result The bank responds to Payneteasy server with approve or decline for requested sale.
Status response Payneteasy responds to “Status request” with either approved or declined when transaction gets it’s final status.
Payment result merchant shows the customer his payment’s finish page.
Full list of possible statuses can be found here: Status List.
Callback is a guaranteed method of delivering the transaction data from Payneteasy to merchant. For details see Merchant Callbacks.
2.2.2. Process Pay365 sale transaction¶
Pay365 Sale API URL¶
For integration purposes use staging environment sandbox.payneteasy.eu instead of production gate.payneteasy.eu. Pay365 sale transactions are initiated through HTTPS POST request by using URL in the following format:
The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.
https://gate.payneteasy.eu/paynet/api/v2/sale-sms/ENDPOINTID
The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.
https://gate.payneteasy.eu/paynet/api/v2/sale-sms/group/ENDPOINTGROUPID
Request parameters¶
In order to initiate a Pay365 Sale transaction Merchant sends an HTTPS POST request with the parameters specified in Pay365 Sale request parameters table below.
| Sale request parameters | Length/Type | Comment | Necessity* |
|---|---|---|---|
| cell_phone | 15/String | Customer’s full international cell phone number, including country code. | Mandatory |
| 50/String | Customer’s email address. | Mandatory | |
| amount | 10/Numeric | Amount to be charged. The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents | Mandatory |
| currency | 3/String | Currency the transaction is charged in (three-letter currency code). Sample values are: USD for US Dollar EUR for European Euro | Mandatory |
| client_orderid | 128/String | Merchant order identifier. | Mandatory |
| order_desc | 64k/String | Brief order description | Mandatory |
| ipaddress | 45/String | Customer’s IP address, included for fraud screening purposes. | Mandatory |
| first_name | 50/String | Customer’s first name | Optional |
| last_name | 50/String | Customer’s last name | Optional |
| ssn | 32/Numeric | Last four digits of the customer’s social security number. | Optional |
| birthday | 8/Numeric | Customer’s date of birth, in the format YYYYMMDD. | Optional |
| address1 | 50/String | Customer’s address line 1. | Optional |
| city | 50/String | Customer’s city. | Optional |
| state | 2-3/String | Customer’s state . Please see Reference for a list of valid state codes. Mandatory for USA, Canada and Australia. | Conditional |
| zip_code | 10/String | Customer’s ZIP code | Optional |
| country | 2/String | Customer’s country(two-letter country code). Please see Reference for a list of valid country codes. | Optional |
| phone | 15/String | Customer’s full international phone number, including country code. | Optional |
| site_url | 128/String | URL the original Sale is made from. | Optional |
| purpose | 128/String | Destination to where the payment goes. It is useful for the merchants who let their clients to transfer money from to some type of client’s account, e.g. game or mobile phone account. Sample values are: +7123456789; gamer0001@ereality.com etc. This value will be used by fraud monitoring system. | Optional |
| server_callback_url | 128/String | URL the transaction result will be sent to. Merchant may use this URL for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. See more details at Merchant Callbacks | Optional |
| merchant_data | 64k/String | Any additional information for this transaction which may be useful in Merchant’s external systems, e.g. VIP customer, TV promo campaign lead. Will be returned in Status response and Merchant Callback. | Optional |
Please note that special characters in parameter’s values should be URL encoded (e.g. & - %26 + - %2B “ - %22).
Request example¶
client_orderid=902B4FF5
&order_desc=Test%20Order%20Description
&cell_phone=%2B9036412121
&amount=10.42
&email=john.smith%40gmail.com
¤cy=USD
&ipaddress=65.153.12.232
&first_name=John
&last_name=Smith
&site_url=www.google.com
&purpose=payment
&server_callback_url=http%3A%2F%2Fmerchantserver.com%2Fcallback.htm
&merchant_data=promo
Request authorization and debug¶
Requests to Pay365 API use OAuth 1.0a authorization with HMAC-SHA1 signature.
oAuth libraries may be helpful to speed up the integration process.
Key:
HMAC key value is the concatenation of consumer secret (Merchant control key) + & + token secret (empty string).
For example, it will look as follows:
F9F65098-1111-1111-1111-621611111111&
Request body and data string to sign:
Parameters in request body must be arranged in lexicographical order.
Unique random nonce and current timestamp are generated by merchant.
OAuth parameters must be included in request body (oauth_consumer_key, oauth_nonce, oauth_signature_method, oauth_timestamp, oauth_version).
Whole request is used as data string to calculate HMAC-SHA1 signature.
URL and parameters in data string must be percent-encoded and have the following structure:
POST&URL¶meters
Headers and signature:
Authorization header must start from Authorization: OAuth, have oauth_signature and the same OAuth parameters and values as were included in request body (oauth_consumer_key, oauth_nonce, oauth_signature_method, oauth_timestamp, oauth_version).
Merchant login is used as oauth_consumer_key in data string and authorization header, but it is not used as a part of the signing HMAC key.
HMAC-SHA1 signature in binary format must be Base64 and percent-encoded. The signature is sent in request header named ‘Authorization’.
For example, it will look as follows:
9bSeUoR5yJSSJ4KPhotT%2BofEHSQ%3D
Authorization header example:
OAuth realm="",
oauth_version="1.0",
oauth_signature_method="HMAC-SHA1",
oauth_consumer_key="merchantlogin",
oauth_timestamp="1513785920",
oauth_nonce="EqINVv5rkhx",
oauth_signature="9bSeUoR5yJSSJ4KPhotT%2BofEHSQ%3D"
For integration purposes use staging environment sandbox.payneteasy.eu instead of production gate.payneteasy.eu.
| normalized parameters |
|---|
| signature base string |
|---|
| signature |
|---|
| authorization header |
|---|
| Curl |
|---|
|
Response parameters¶
All parameters in response are encoded in application/x-www-form-urlencoded MIME format
| Pay365 Sale response parameters | Description |
|---|---|
| type | The type of response. May be async-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| paynet-order-id | Order id assigned to the order by Payneteasy |
| merchant-order-id | Merchant order id |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Merchant. |
| error-message | If status is error this parameter contains the reason for decline or error details |
| error-code | The error code is case of error status |
Response example¶
type=async-response
&serial-number=00000000-0000-0000-0000-0000000624e8
&merchant-order-id=59e1e3ca-5d44-11e1-b3d6-002522b853b4
&paynet-order-id=94935
Server callback result¶
Upon completion by the System of Pay365 Sale request processing it returns the result on the specified server_callback_url with the following parameters described in Merchant Callbacks.
Merchant may use it for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database.
The checksum is used to ensure that the callback is initiated for a particular Merchant, and not for anybody else claiming to be such Merchant. This SHA-1 checksum, the control parameter, is created by concatenation of the parameters values in the following order:
- status
- orderid
- client_orderid
- merchant_control
A complete string example may look as follows:
approved456724invoice15653E8E45B5-7682-42D8-6ECC-111111111111
Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter. For the above-mentioned example the control will take the following value:
de5395a34cb121364d0ed3c8031ec2cd70525049
All parameters are sent via GET method.
Server callback result example¶
status=declined
&error-message=Not_sufficient_funds
&error-code=107
&paynet-order-id=456724
&merchant-order-id=invoice15
2.2.3. Order status¶
Merchant must use Order status API call to get the customer’s order transaction status. After any type of transaction is sent to Payneteasy server and order id is returned, Merchant should poll for transaction status. When transaction is processed on Payneteasy server side it returns it’s status back to Merchant and at this moment the Merchant is ready to show the customer transaction result, whether it’s approved or declined.
Status API URL¶
For integration purposes use staging environment sandbox.payneteasy.eu instead of production gate.payneteasy.eu. Status API calls are initiated through HTTPS POST request by using URL in the following format:
The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.
https://gate.payneteasy.eu/paynet/api/v2/status/ENDPOINTID
The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.
https://gate.payneteasy.eu/paynet/api/v2/status/group/ENDPOINTGROUPID
Status request parameters¶
| Status call parameters | Description |
|---|---|
| login | Merchant login name |
| client_orderid | Merchant order identifier of the transaction for which the status is requested |
| orderid | Order id assigned to the order by Payneteasy |
| by-request-sn | Serial number assigned to the specific request by Payneteasy. If this field exist in status request, status response return for this specific request. |
| control | Checksum used to ensure that it is Payneteasy (and not a fraudster) that initiates the callback for a particular Merchant. This is SHA-1 checksum of the concatenation login + client-order-id + paynet-order-id + merchant-control. See Order status API call authorization through control parameter for more details about generating control checksum. |
Status response parameters¶
| Status Response Parameter | Description |
|---|---|
| type | The type of response. May be status-response |
| status | See Status List for details. |
| amount | Amount of the initial transaction. |
| paynet-order-id | Order id assigned to the order by Payneteasy |
| merchant-order-id | Merchant order id |
| phone | Customer phone. |
| serial-number | Unique number assigned by Payneteasy server to particular request from the Merchant. |
| card-type | Type of customer credit card (SMS in Pay365 integration). |
| transaction-type | Transaction type (sale). |
| receipt-id | Electronic link to receipt https://gate.payneteasy.eu/paynet/view-receipt/ENDPOINTID/receipt-id/ |
| card-exp-month | Expiration month (0 in Pay365 integration). |
| card-exp-year | Expiration year (0 in Pay365 integration). |
| Customer e-mail. | |
| paynet-processing-date | Transaction processing date. |
| order-stage | The current stage of the transaction processing. See Order Stage for details |
| error-message | If status in declined, error, filtered this parameter contains the reason for decline |
| error-code | The error code is case status in declined, error, filtered. |
| merchantdata | If provided in initial request, merchant_data parameter and its value will be included in status response. |
Status response example¶
type=status-response
&serial-number=00000000-0000-0000-0000-0000005b5044
&merchant-order-id=902B4FF5
&paynet-order-id=159884
&status=approved
&amount=10.42
&transaction-type=sale
&receipt-id=a5061379-6ff5-3565-a9ba-1b8a814d04f6
&card-exp-month=0
&card-exp-year=0
&email=john.smith%40gmail.com
&order-stage=sale_approved
&card-type=SMS
&phone=12063582043
&paynet-processing-date=2017-11-21+15%3A43%3A05+MSK
&merchantdata=promo
Status request authorization and debug¶
The checksum is used to ensure that it is Merchant (and not a fraudster) that sends the request to Payneteasy. This SHA-1 checksum, the parameter control, is created by concatenating of the values of the parameters in the following order:
- login
- client_orderid
- orderid
- merchant_control
For example assume the following values are corresponds the parameters above:
| Parameter Name | Parameter Value |
|---|---|
| login | cool_merchant |
| client_orderid | 5624444333322221111110 |
| orderid | 9625 |
| merchant_control | r45a019070772d1c4c2b503bbdc0fa22 |
The complete string example may look as follows:
cool_merchant56244443333222211111109625r45a019070772d1c4c2b503bbdc0fa22
Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter which is required for authorizing the callback. For the example control above will take the following value:
c52cfb609f20a3677eb280cc4709278ea8f7024c
| String to sign |
|---|
| Signature |
|---|
|