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.

skinparam ParticipantPadding 60
Customer -> Merchant: Checkout order
activate Merchant
Merchant -> "Payneteasy": Pay365 sale request
activate "Payneteasy"
"Payneteasy" -> Pay365: Process sale
activate Pay365
"Payneteasy" --> Merchant: Order ID
deactivate Merchant
deactivate "Payneteasy"
Pay365 -> Customer: Confirmation request
activate Customer
Customer --> Pay365: Confirmation response
deactivate Customer
loop status
Merchant -> "Payneteasy": Status request
activate Merchant
activate "Payneteasy"
"Payneteasy" --> Merchant: status = PROCESSING
end
Pay365 --> "Payneteasy": Sale result
deactivate Pay365
Merchant -> "Payneteasy": Status request
"Payneteasy" --> Merchant: status = APPROVED | DECLINED
deactivate "Payneteasy"
Merchant --> Customer: Payment result
deactivate Merchant

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.

Note

Request must have content-type=application/x-www-form-urlencoded and Authorization headers.

Warning

Please note that special characters in parameter’s values should be URL encoded (e.g. & - %26 + - %2B - %22).
Sale request parameters Length/Type Comment Necessity*
cell_phone 15/String Customer’s full international cell phone number, including country code. Mandatory
email 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

Request example

client_orderid=902B4FF5
&order_desc=Test%20Order%20Description
&cell_phone=%2B9036412121
&amount=10.42
&email=john.smith%40gmail.com
&currency=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&parameters
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.
Mandatory parameters
HTTP method
version
signature method
consumer key
consumer secret
timestamp
nonce
EndpointId or GroupId
client_orderid make it or use your internal invoice ID
cell_phone
amount
email
currency
ipaddress
order_desc
Optional parameters
first_name
last_name
ssn
birthday
address1
city
state
zip_code
country
phone
site_url
purpose
server_callback_url
merchant_data

normalized parameters
signature base string
signature
authorization header
Curl
              
            

Response parameters

Note

Response has Content-Type: text/html;charset=utf-8 header. All parameters in response are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value
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

Note

Request must have content-type=application/x-www-form-urlencoded.
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

Note

Response has Content-Type: text/html;charset=utf-8 header. All parameters in response are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value
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).
email 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

endpointid or groupid input your ENDPOINTID or ENDPOINTGROUPID
login input your Login
client_orderid input your Invoice Number
orderid
merchant_control input your Control Key
by-request-sn

String to sign
Signature