1.1.4. Return Transactions¶
Return transaction diagram¶
Process Return transaction¶
For integration purposes use staging environment sandbox.apropay.com instead of production gate.apropay.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 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.
The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.
Return Request Parameters¶
Note
| 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 Apropay 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. For cashier integration (Parallel form) send return request to master ENDPOINTID or ENDPOINTGROUPID with auxiliary orderid value in this parameter | Mandatory |
| client_orderid | 128/String | Unique merchant identifier of Sale (SMS) or Preauth/Capture (DMS) transaction which is send to Apropay system in the client_orderid parameter | Mandatory |
| amount | 10/Numeric | 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 | Conditional |
| 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 |
Return Response¶
Note
| 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 Apropay |
| merchant-order-id | Merchant order id |
| serial-number | Unique number assigned by Apropay 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 request authorization through control parameter¶
The checksum is used to ensure that it is a particular Merchant (and not a fraudster) that initiates the transaction. This SHA-1 checksum, the parameter control, is created by concatenation of the parameters’ values in the following order:
With amount and currency fields:
- ENDPOINTID/ENDPOINTGROUPID
- login
- client_orderid
- orderid
- minimal monetary units amount (i.e. cent, penny etc. For amount 0.94 USD value in signing string will be 94, for 10.15 USD value in signing string will be 1015)
- currency
- merchant_control
A complete string example may look as follows:
logic902B4FF5159884500EURB17F59B4-A7DC-41B4-8FF9-37D986B43D20
Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter (see Sale Request Parameters) which is required for request authorization. For the above-mentioned example the control will take the following value:
f9fcfd80c03a9ad9d813f67f11095512be4feffb
Without amount and currency fields:
- ENDPOINTID/ENDPOINTGROUPID
- login
- client_orderid
- orderid
- merchant_control
A complete string example may look as follows:
logic902B4FF5159884B17F59B4-A7DC-41B4-8FF9-37D986B43D20
Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter (see Sale Request Parameters) which is required for request authorization. For the above-mentioned example the control will take the following value:
6ef9cae82e765a7f43d4b596f8186cf20962e349
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 Apropay server and order id is returned, Merchant should poll for transaction status. When transaction is processed on Apropay 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.apropay.com instead of production gate.apropay.com. Status API calls are initiated through HTTPS POST request by using URL in the following format:
Order status call parameters¶
Note
| 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 Apropay |
| by-request-sn | Serial number assigned to the specific request by Apropay. If this field exist in status request, status response return for this specific request |
| control | Checksum used to ensure that it is Apropay (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¶
Note
| 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 Apropay |
| merchant-order-id | Merchant order id |
| phone | Customer phone |
| serial-number | Unique number assigned by Apropay 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://gate.apropay.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 |
| card-country-alpha-three-code | Three letter country code of card issuer. See Country Codes for details |
| total-reversal-amount | Total amount of processed reversals |
| reversal-amount | The amount of the last processed reversal |
| Customer e-mail | |
| first-name | Customer’s first name |
| last-name | Customer’s last name |
| country * | Customer’s country (two-letter country code). Please see Country Codes for a list of valid country codes. |
| state * | Customer’s state . Please see Country Codes for a list of valid state codes. Mandatory for USA, Canada and Australia. |
| city * | Customer’s city |
| zip_code * | Customer’s ZIP code |
| address1 * | Customer’s address line 1 |
| 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 |
| motivational-message | This is an optional message which contains extended information about the reason for the declined transaction. |
| transaction-date | Date of final status assignment for transaction. |
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
&last-name=Smith
&first-name=John
&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
&transaction-date=2023-01-10+12%3A46%3A28+MSK
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 Apropay. 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