1.2.6. Return Transactions

Return transaction diagram

Merchant -> "PaynetEasy": Return request
activate "PaynetEasy"
"PaynetEasy" --> Merchant: Order ID

"PaynetEasy" -> Acquirer: Process refund
activate Acquirer

Merchant -> "PaynetEasy": Get status by Order ID

Acquirer --> "PaynetEasy": Processing result
deactivate Acquirer

"PaynetEasy" --> Merchant: Final status
deactivate "PaynetEasy"

Return request Merchant sends Return request to PaynetEasy server with specified parameters described in Return Request Parameters.
Order ID PaynetEasy server sends back the response. Merchant starts polling for status with given orderid as described in Order status asynchronous call.
Process refund PaynetEasy server determines the actual type of Return transaction(Cancel or Reversal) depending o the type of initial sale transaction. PaynetEasy server forwards the appropriate request to bank acquirer asynchronously. The bank starts processing the transaction.
Get status by Order Id Merchant is polling for status with given orderid as described in Order status asynchronous call.
Processing result The bank responds to PaynetEasy server with approve or decline for requested return transaction.
Final Status PaynetEasy server returns status to Merchant through Order status asynchronous call.

Process Return transaction

For integration purposes use staging environment sandbox.payneteasy.com instead of production gate.payneteasy.com. Return API call returns money back to the customer. For Preauth it makes Cancel transaction, for Capture and SaleReversal. Void API call excludes transaction from clearing. Void transaction is always the result of this call. Void might not be supported by your acquirer, ask manager for detalies. Return and Void API calls are initiated through HTTPS POST request by using URL in the following format:

Return transaction request URL

The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.

https://gate.payneteasy.com/paynet/api/v2/return/ENDPOINTID – for return transaction
https://gate.payneteasy.com/paynet/api/v2/void/ENDPOINTID – for void transaction

The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.

https://gate.payneteasy.com/paynet/api/v2/return/group/ENDPOINTGROUPID – for return transaction
https://gate.payneteasy.com/paynet/api/v2/void/group/ENDPOINTGROUPID – for void transaction

Return Request Parameters

Return Request Parameter Length/Type Comment Necessity*
login 20/String Merchant login name Mandatory
orderid 20/String Unique identifier of Sale (SMS) or Preauth/Capture (DMS) order assigned by PaynetEasy system and returned in the orderidresponse parameter. Please note that return can be made On a preauth transaction if the relative capture transaction has not taken place yet; or on a capture transaction. In the latter case, processing of a return on a preauth transaction is restricted. Mandatory
client_orderid 128/String Unique merchant identifier of Sale (SMS) or Preauth/Capture (DMS) transaction which is send to PaynetEasy system in theclient_orderid parameter. Mandatory
amount 10/Numeric This optional parameter specifies amount to be reversed. 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. If this parameter is omitted, initial transaction is reversed as a whole. Amount only makes sense for reversals, not cancels. Amount cannot exceed initial transaction amount. Please note that you MUST specify currency if you specify amount! Not supported for void transactions Mandatory
currency 3/String Currency in which amount is specified (three-letter currency code). Valid parameter values are: USD for US Dollar EUR for European Euro. Not supported for void transactions Conditional
control 128/String Checksum used to ensure that it is Merchant (and not a fraudster) that initiates the return request. This is SHA-1 checksum of the concatenation login + client_orderid + orderid + merchant-control if amount is not specified, and login + client_orderid + orderid + amount_in_cents + currency + merchant-control if amount is specified. Mandatory
comment 50/String A brief description of reason Mandatory

Please note the following characters must be escaped in the parameter values: & + .

Return Response

Return Response Parameter 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.
status See Status List for 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

Return Response Example

type=async-response
&serial-number=00000000-0000-0000-0000-0000000624e8
&merchant-order-id=59e1e3ca-5d44-11e1-b3d6-002522b853b4
&paynet-order-id=94935

Return Request Debug

endpointid or groupid input your ENDPOINTID or ENDPOINTGROUPID
login
client_orderid input your Invoice Number
orderid
amount
currency
merchant_control input your Control Key
comment

String to sign
Signature
              
            
			 
		
			
		

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.com instead of production gate.payneteasy.com. 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.com/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.com/paynet/api/v2/status/group/ENDPOINTGROUPID

Order status call parameters

Status call parameter 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.

Order Status Response

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.
last-four-digits Last four digits of customer credit card number.
bin Bank BIN of customer credit card number.
card-type Type of customer credit card (VISA, MASTERCARD, etc).
gate-partial-reversal Processing gate support partial reversal (enabled or disabled).
gate-partial-capture Processing gate support partial capture (enabled or disabled).
transaction-type Transaction type (sale, reversal, capture, preauth).
processor-rrn Bank Receiver Registration Number.
processor-tx-id Acquirer transaction identifier.
receipt-id Electronical link to receipt https://gate.payneteasy.com/paynet/view-receipt/ENDPOINTID/receipt-id/
name Cardholder name.
cardholder-name Cardholder name.
card-exp-month Card expiration month.
card-exp-year Card expiration year.
card-hash-id Unique card identifier to use for loyalty programs or fraud checks.
email Customer e-mail.
bank-name Bank name by customer card BIN.
terminal-id Acquirer terminal identifier to show in receipt.
paynet-processing-date Acquirer transaction processing date.
approval-code Bank approval code.
order-stage The current stage of the transaction processing. See Order Stage
loyalty-balance The current bonuses balance of the loyalty program for current operation. if available
loyalty-message The message from the loyalty program. if available
loyalty-bonus The bonus value of the loyalty program for current operation. if available
loyalty-program The name of the loyalty program for current operation. if available
descriptor Bank identifier of the payment recipient.
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.
by-request-sn Serial number from status request, if exists in request. Warning parameter amount always shows initial transaction amount, even if status is requested by-request-sn.
verified-3d-status See 3d Secure Status List for details
verified-rsc-status See Random Sum Check Status List for details

Order Status Response Example

type=status-response
&serial-number=00000000-0000-0000-0000-0000005b5ef2
&merchant-order-id=423432-324
&processor-tx-id=1428585590552
&paynet-order-id=159874
&status=approved
&amount=390000.00
&descriptor=no
&gate-partial-reversal=enabled
&gate-partial-capture=enabled
&transaction-type=fraud
&receipt-id=2438-3c9f-a299-f185e639d827
&name=Nikolay+Popov
&cardholder-name=Nikolay+Popov
&card-exp-month=8
&card-exp-year=2017
&email=alex
&processor-rrn=509995959724
&approval-code=825335
&order-stage=reversal_approved
&last-four-digits=1111
&bin=444455
&card-type=VISA
&phone=%2B79636910155
&bank-name=UNKNOWN
&terminal-id=12345678
&paynet-processing-date=2015-04-09+16%3A14%3A46+MSK
&card-hash-id=1569311
&verified-3d-status=AUTHENTICATED
&verified-rsc-status=AUTHENTICATED

Status request authorization through control parameter

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 concatenation of these parameters values in the following order:

  • login
  • client_orderid
  • orderid
  • merchant_control

For example, assume these parameters have the values as listed below:

Parameter Description
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

Order status Debug

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

String to sign
Signature