1.1.4. Return Transactions¶
Return transaction diagram¶
Return request Merchant sends Return request to MoneyNetint server with specified parameters described in Return Request Parameters.
Order ID MoneyNetint server sends back the response. Merchant starts polling for status with given orderid as described in Order status asynchronous call.
Process refund MoneyNetint server determines the actual type of Return transaction(Cancel or Reversal) depending o the type of initial sale transaction. MoneyNetint 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 MoneyNetint server with approve or decline for requested return transaction.
Final Status MoneyNetint server returns status to Merchant through Order status asynchronous call.
Process Return transaction¶
For integration purposes use staging environment pne-sandbox.moneynetint.com instead of production pne-gate.moneynetint.com. Return API call returns money back to the customer. For Preauth it makes Cancel transaction, for Capture and Sale – Reversal. 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://pne-gate.moneynetint.com/paynet/api/v2/return/ENDPOINTID – for return transaction
https://pne-gate.moneynetint.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://pne-gate.moneynetint.com/paynet/api/v2/return/group/ENDPOINTGROUPID – for return transaction
https://pne-gate.moneynetint.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 MoneyNetint 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 MoneyNetint 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 MoneyNetint |
| merchant-order-id | Merchant order id |
| serial-number | Unique number assigned by MoneyNetint 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
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 MoneyNetint server and order id is returned, Merchant should poll for transaction status. When transaction is processed on MoneyNetint 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 pne-sandbox.moneynetint.com instead of production pne-gate.moneynetint.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://pne-gate.moneynetint.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://pne-gate.moneynetint.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 MoneyNetint |
| by-request-sn | Serial number assigned to the specific request by MoneyNetint. If this field exist in status request, status response return for this specific request. |
| control | Checksum used to ensure that it is MoneyNetint (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 MoneyNetint |
| merchant-order-id | Merchant order id |
| phone | Customer phone. |
| serial-number | Unique number assigned by MoneyNetint 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://pne-gate.moneynetint.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. |
| 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 MoneyNetint. 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