1.1.6. Return Transactions

Return transaction diagram

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

"Elecsnet" -> Acquirer: Process refund
activate Acquirer

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

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

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

Return request Merchant sends Return request to Elecsnet server with specified parameters described in Return Request Parameters.
Order ID Elecsnet server sends back the response. Merchant starts polling for status with given orderid as described in Order status asynchronous call.
Process refund Elecsnet server determines the actual type of Return transaction(Cancel or Reversal) depending o the type of initial sale transaction. Elecsnet 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 Elecsnet server with approve or decline for requested return transaction.
Final Status Elecsnet server returns status to Merchant through Order status asynchronous call.

Process Return transaction

For integration purposes use staging environment sandbox.elecsnet.ru instead of production pay.elecsnet.ru. 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 details. 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://pay.elecsnet.ru/paynet/api/v2/return/ENDPOINTID – for return transaction
https://pay.elecsnet.ru/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://pay.elecsnet.ru/paynet/api/v2/return/group/ENDPOINTGROUPID – for return transaction
https://pay.elecsnet.ru/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 Elecsnet system and returned in the order_id response 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 Elecsnet system in the client_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.
paynet-order-id Order id assigned to the order by Elecsnet
merchant-order-id Merchant order id
serial-number Unique number assigned by Elecsnet server to particular request from the Merchant.
end-point-id Entry point used for processing this transaction.
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 Elecsnet server and order id is returned, Merchant should poll for transaction status. When transaction is processed on Elecsnet 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.elecsnet.ru instead of production pay.elecsnet.ru. 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://pay.elecsnet.ru/paynet/api/v2/status/ENDPOINTID
The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.
https://pay.elecsnet.ru/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 Elecsnet
by-request-sn Serial number assigned to the specific request by Elecsnet. If this field exist in status request, status response return for this specific request.
control Checksum used to ensure that it is Elecsnet (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.
currency Currency the transaction is charged in (three-letter currency code). Example of valid parameter values are: USD for US Dollar EUR for European Euro.
paynet-order-id Order id assigned to the order by Elecsnet
merchant-order-id Merchant order id
phone Customer phone.
serial-number Unique number assigned by Elecsnet 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 Retrieval Reference Number.
processor-tx-id Acquirer transaction identifier.
receipt-id Electronic link to receipt https://pay.elecsnet.ru/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.
card-country-alpha-three-code Three letter country code of card issuer. See Card country codes for details.
total-reversal-amount Total amount of processed reversals.
reversal-amount The amount of the last processed reversal
email Customer e-mail.
bank-name Bank name by customer card BIN.
auth-response-code Response code used in Iso8583 protocol. Only returned in specific cases.
terminal-id Acquirer terminal identifier to show in receipt.
paynet-processing-date System transaction processing date.
acquirer-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 Identifier of the used processing channel. In some cases can contain bank identifier of the payment recipient.
original-gate-descriptor Original descriptor set on the gate.
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 Custom information provided by merchant in initial transaction request.
purpose Destination of payment sent by merchant in initial request.
eci Electronic Commerce Indicator of 3-D Secure authentication.
processor-auth-credit-code Approval credit code. Only returned in specific cases.
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 3-D Secure Status List for details
processor-credit-rrn Retrieval Reference Number for credit transaction.
processor-credit-arn Acquirer card reference number for credit transaction.
processor-debit-arn Acquirer card reference number for debit transaction.
ips-src-payment-product-code Code for card set by multinational financial service. (Visa/Mastercard).
ips-src-payment-product-name Decrypted code for card set by multinational financial service. (Visa/Mastercard).
ips-src-payment-type-code Type of card code set by multinational financial service. (Visa/Mastercard).
ips-src-payment-type-name Decrypted code for type of card set by multinational financial service. (Visa/Mastercard).
initial-amount Amount, set in initiating transaction, without any fees or commissions. This value can’t change during the transaction flow.

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
&original-gate-descriptor=test 12345678 3Ds Bank
&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
&card-country-alpha-three-code=RUS
&verified-3d-status=AUTHENTICATED
&eci=02
&ips-src-payment-product-code=SAP
&ips-src-payment-product-name=SAP—Platinum Mastercard® Salary– Immediate Debit
&ips-src-payment-type-code=Debit
&ips-src-payment-type-name=MASTERCARD Debit
&initial-amount=390000.00

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 Elecsnet. 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