1.1.2. Preauth/Capture Transactions¶
- Direct Integration
- Preauth Transaction General Flow
- Process Preauth transaction
- Preauth transaction by ENDPOINTID
- Preauth transaction by ENDPOINTGROUPID
- Preauth Request Parameters
- Preauth Request with Cardholder Data Example
- Preauth Request with Card Recurring Payment ID Example
- Preauth Response
- Preauth Response Example
- Preauth Postman Collection
- Preauth Request Debug
- 3DS redirect
- Server callback result
- Server callback result example
- Process Capture Transaction
- Preauth and Capture request authorization through control parameter
- Order status
- Payment Form Integration
Direct Integration¶
Preauth Transaction General Flow¶
Merchant Site initiates a Pre-auth transaction by sending corresponding HTTPS POST request to the specified URL
The System processes the transaction and sends corresponding response (depending on 3DS/non-3DS processing type). Upon successful completion of a preauth transaction the bank blocks the specified amount in the credit card account and does not allow the cardholder to use this blocked money. It is important to know that the block remains for a definite period of time depending on whether this is a debit or a credit card (usually the maximum block period is 7 days for debit cards and 28 days for credit cards).
Merchant sends Capture transaction in order to deduct the locked amount from credit card.
System processes capture transaction and returns corresponding response. In this case the money is actually transferred from the bank-issuer account to the bank-acquirer account, which means the end of the transaction.
Merchant is using single entry point for both 3DS and non-3DS Preauth transactions. Actually the Merchant can not know beforehand if the sale will be driven through 3DS authorization scheme. The Merchant should use Apropay API as described below.
Checkout order Customer checks out the order on Merchant’s website
Process Preauth Merchant sends Preauth request to Apropay server with specified parameters described in Preauth Request Parameters. Merchant must make sure redirect_url is passed. This is the URL the Customer will be redirected after 3DS transaction is processed. redirect_url is not used if the transaction goes through non-3DS process.
Order status = processing Apropay Server immediately returns response with order status processing. See details at Preauth Response
Get Order status Merchant starts polling Apropay server for transaction status using paynet-order-id obtained at previous step. Status polling request and response are described in Order status asynchronous call
Is 3DS auth required? Apropay Gateway determines if 3DS authorization required for the incoming sale transaction.
Non-3DS Preauth process In case the gate is non-3DS Apropay returns empty html parameter and Merchant should keep polling Apropay server until approved or declined status is returned. See non-3DS Preauth transaction diagram for details.
3DS Preauth process In case the gate is 3DS Apropay returns non-empty html parameter Merchant should follow 3DS sale process starting from step 5 described in 3DS Preauth transaction diagram.
Non-3DS Preauth transaction diagram¶
Merchant is using single entry point for both 3DS and non-3DS Preauth transactions. Actually the Merchant can not know beforehand if the Preauth will be driven through 3DS authorization scheme. The Merchant should use Apropay API as described in General Preauth Process Flow.
Preauth request Customer checks out the order and Merchant sends non-3DS Preauth request to Apropay server with specified parameters described in Preauth Request Parameters.
Order Id Apropay server sends back the response with orderid. Merchant shows the customer a message like Your order is being processed. Please, wait… and starts polling for status with given orderid as described in Order status asynchronous call.
Process Preauth Apropay server forwards Preauth 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.
Preauth approved or declined The bank responds to Apropay server with approve or decline for requested Preauth
Return Status – approved or declined Apropay server returns status to Merchant through Order status asynchronous call.
3DS Preauth transaction diagram¶
Merchant is using single entry point for both 3DS and non-3DS Preauth transactions. Actually the Merchant can not know beforehand if the Preauth will be driven through 3DS authorization scheme. The Merchant should use Apropay API as described in General Preauth Process Flow.
Checkout order Customer checks out the order on Merchant’s website Process 3DS Preauth. Merchant sends 3DS Preauth request to Apropay server with specified parameters described in Preauth Request Parameters. Merchant must make sure redirect_url is passed. This is the URL the Customer will be redirected after transaction is processed.
Get auth form Apropay server requests 3DS authentication form from the Issuer Bank
Return 3DS form HTML Issuer Bank returns HTML to 3DS extra authentication form from the Issuer Bank to Apropay server
Return 3DS response with auth form Apropay server returns response including auth form HTML to Merchant. See details at Preauth Response
Show 3DS form to customer Merchant shows Customer Issuer Bank’s extra authentication form
Customer submits additional auth information Customer follows Issuer Bank’s process to provide additional authorization information. The most usual way it’s accomplished is sending SMS message with a secret code to customer’s mobile phone which number is known to Issuer Bank. Customer then supplies this secret code through the auth form.
Authorized The Issuer Bank verifies that extra authorization information supplied by the Customer is correct and replies back to Apropay server.
Process Preauth Apropay server forwards Preauth request to bank acquirer. The bank starts processing the transaction.
Preauth approved or declined The bank responds to Apropay server with approve or decline for requested Preauth
Show auto-submit order form Apropay server creates order and redirects customer’s browser to auto-submit form with supplied order id. The form’s action is redirect_url passed at step 2.
Auto-submit form with order id and status Customer’s browser automatically submits the form with order id and status to Merchant’s redirect_url passed at step 2. Status may be either approved or declined
Process Preauth transaction¶
For integration purposes use staging environment sandbox.apropay.com instead of production gate.apropay.com. Preauth transactions are initiated through HTTPS POST request by using URL in the following format:
Preauth transaction by ENDPOINTID¶
The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.
https://gate.apropay.com/paynet/api/v2/preauth/ENDPOINTID – for pre-auth transaction
Preauth transaction by ENDPOINTGROUPID¶
The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.
https://gate.apropay.com/paynet/api/v2/preauth/group/ENDPOINTGROUPID – for pre-auth transaction
Preauth Request Parameters¶
In order to initiate a Preauth transaction Merchant sends an HTTPS POST request with the parameters specified in Preauth Request Parameters Table below
Note
Request must have content-type=application/x-www-form-urlencoded.
Acquirer can redefine the necessity of some fields so they become mandatory instead of optional
Leading and trailing whitespace in input parameters will be omitted
Please note the following characters must be escaped in the parameter values: & + “.
| Preauth Request Parameter | Length/Type | Comment | Necessity* |
|---|---|---|---|
| client_orderid | 128/String | Merchant order identifier | Mandatory |
| order_desc | 125/String | Brief order description | 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 |
| address1 | 50/String | Customer’s address line 1 | Mandatory |
| city | 50/String | Customer’s city | Mandatory |
| zip_code | 10/String | Customer’s ZIP code | Mandatory |
| country | 2/String | Customer’s country(two-letter country code). Please see Reference for a list of valid country codes | Mandatory |
| phone | 15/String | Customer’s full international phone number, including country code | Mandatory |
| 50/String | Customer’s email address | Mandatory | |
| ipaddress | 45/String | Customer’s IP address, included for fraud screening purposes | Mandatory |
| control | 40/String | Checksum generated by SHA-1. See Request authorization through control parameter for more details | Mandatory |
| cvv2 | 3-4/Numeric | Customer’s CVV2 code. CVV2 (Card Verification Value) is a three- or four-digit number AFTER the credit card number in the signature area of the card | Mandatory |
| credit_card_number | 20/Numeric | Customer’s credit card number. Send either combination of credit_card_number, card_printed_name, expire_month and expire_year or card_recurring_payment_id, not all | Conditional |
| card_recurring_payment_id | Long | Customer’s tokenized cardholder’s data ID. Send either card_recurring_payment_id or combination of credit_card_number, card_printed_name, expire_month and expire_year, not all. To create card_recurring_payment_id see Process Card Registration via v4/create-card-ref | Conditional |
| card_printed_name | 64k/String | Card printed name. | Conditional |
| expire_month | 2/Numeric | Credit card expiration month. | Conditional |
| expire_year | 4/Numeric | Credit card expiration year. | Conditional |
| first_name | 50/String | Customer’s first name. Depends on Acquirer’s side | Conditional |
| last_name | 50/String | Customer’s last name. Depends on Acquirer’s side | Conditional |
| state | 2-3/String | Customer’s state . Please see Reference for a list of valid state codes. Mandatory for USA, Canada and Australia | Conditional |
| redirect_url | 1024/String | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. You should not use this parameter to retrieve results from Apropay gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead. Pass http://google.com if you use non-3DS schema for transactions processing and you have no need to return customer anywhere. See more details at Statuses. This parameter becomes Mandatory if both redirect_success_url and redirect_fail_url are missing | Conditional |
| redirect_success_url | 1024/String | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is approved. You should not use this parameter to retrieve results from Apropay gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead. Pass http://google.com if you use non-3DS schema for transactions processing and you have no need to return customer anywhere. This parameter becomes Mandatory if redirect_url parameter is missing | Conditional |
| redirect_fail_url | 1024/String | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is declined or filtered. You should not use this parameter to retrieve results from Apropay gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead. Pass http://google.com if you use non-3DS schema for transactions processing and you have no need to return customer anywhere. This parameter becomes Mandatory if redirect_url parameter is missing | Conditional |
| 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 |
| cell_phone | 15/String | Customer’s full international cell phone number, including country code | Optional |
| site_url | 128/String | URL the original Preauth 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 a credit card 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 | 1024/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 Preauth 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 |
Preauth Request with Cardholder Data Example¶
credit_card_number=4538977399606732
&card_printed_name=CARD HOLDER
&expire_month=12
&expire_year=2099
&cvv2=123
&client_orderid=902B4FF5
&order_desc=Test Order Description
&first_name=John
&last_name=Smith
&ssn=1267
&birthday=19820115
&address1=100 Main st
&city=Seattle
&state=WA
&zip_code=98102
&country=US
&phone=%2B12063582043
&cell_phone=%2B19023384543
&email=john.smith@gmail.com
¤cy=USD
&amount=10.42
&ipaddress=65.153.12.232
&site_url=www.google.com
&purpose=user_account1
&redirect_url=http://doc.apropay.com/doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&merchant_data=VIP customer
&control=768eb8162fc361a3e14150ec46e9a6dd8fbfa483
Preauth Request with Card Recurring Payment ID Example¶
card_recurring_payment_id=1491927
&cvv2=123
&client_orderid=34T43R77N
&order_desc=Test Order Description
&amount=777
¤cy=USD
&ipaddress=65.153.12.232
&redirect_url=http://doc.apropay.com/doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&control=218d377897ce25c2ac69d99de42bc6902eb5bcd8
Preauth Response¶
Note
Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Preauth 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 |
| 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 |
| end-point-id | Endpoint id used for the transaction |
Preauth Response Example¶
type=async-response
&serial-number=00000000-0000-0000-0000-000002d53397
&merchant-order-id=902B4FF5
&paynet-order-id=6666821
&end-point-id=2489
Preauth Request Debug¶
Possible transaction flow scenarios can be tested with E-Commerce test cards
| String to sign |
|---|
| Signature |
|---|
|
3DS redirect¶
If your gate supports 3-D Secure you need to send status request and process html return parameter to send customer to 3-D Secure Authorisation. The simplified schema looks like:
html field is always present for 3DS gates in status response, whether clients card supports 3-D Secure or not.
Upon completion of 3DS authorization process by the Customer he/she is automatically redirected to redirect_url. The redirection is performed as an HTTPS POST request with the parameters specified in the following table.
| 3DS redirect Parameter | Description |
|---|---|
| status | See Status List for details |
| orderid | Order id assigned to the order by Apropay |
| merchant_order | Merchant order id |
| client_orderid | Merchant order id |
| error_message | If status is declined or error this parameter contains the reason for decline or error details |
| control | Checksum used to ensure that it is Apropay (and not a fraudster) that initiates the request. This is SHA-1 checksum of the concatenation status + orderid + client_orderid + merchant-control |
| descriptor | Gate descriptor |
If Merchant has passed server_callback_url in original Preauth request Apropay will call this URL. Merchant may use it for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. The parameters sent to this URL are specified in Sale, Return Callback Parameters
Server callback result¶
Upon completion by the System of 3DS request processing it returns the result on the specified server_callback_url with the following parameters described in Sale, Return Callback Parameters
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:
approvedS279G323P4T1209294c258d6536ababe653E8E45B5-7682-42D8-6ECC-FB794F6B11B1
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:
e04bd50531f45f9fc76917ac78a82f3efaf0049c
All parameters are sent via GET method.
Server callback result example¶
status=declined
&error-message=Decline, refer to card issuer
&error-code=107
&paynet-order-id=S279G323P4T1209294
&merchant-order-id=c258d6536ababe65
&motivational-message=Sorry, your payment has been declined.
Process Capture Transaction¶
The Capture operation initiates after successful complete of the Preauth operation to deduct blocked amount from the customer’s card.
For integration purposes use staging environment sandbox.apropay.com instead of production gate.apropay.com. Capture transactions are initiated through HTTPS POST request by using URL in the following format:
Capture Transaction by ENDPOINTID¶
The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.
https://gate.apropay.com/paynet/api/v2/capture/ENDPOINTID – for capture transaction
Capture Transaction by ENDPOINTGROUPID¶
The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.
https://gate.apropay.com/paynet/api/v2/capture/group/ENDPOINTGROUPID – for capture transaction
Capture Request¶
Note
Request must have content-type=application/x-www-form-urlencoded.
| Capture Request Parameter | Description | Necessity |
|---|---|---|
| login | Merchant login name | Mandatory |
| client_orderid | Merchant order identifier of the transaction for which the status is requested | Mandatory |
| orderid | Order id assigned to the order by Apropay | Mandatory |
| 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 + merchant-order-id + paynet-order-id + amount_in_cents(if sent) + currency(if amount sent) + merchant-control | Mandatory |
| amount | 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 | Optional |
| currency | Currency the transaction is charged in (three-letter currency code). Sample values are: USD for US Dollar EUR for European Euro | Optional |
Capture Response¶
Note
Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Capture 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 |
| 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 |
| end-point-id | Endpoint id used for the transaction |
Capture Response Example¶
type=async-response
&serial-number=00000000-0000-0000-0000-000002d53397
&merchant-order-id=902B4FF5
&paynet-order-id=6666821
&end-point-id=2489
Preauth and Capture 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:
- ENDPOINTID/ENDPOINTGROUPID
- client_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)
- merchant_control
A complete string example may look as follows:
59I6email@client.com3E8E45B5-2-42D8-6ECC-FBF6B11B1
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:
5b1da0a20a1b9ff4d66caaba15a3e7ee13
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.
See more details at Statuses
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:
The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.
https://gate.apropay.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.apropay.com/paynet/api/v2/status/group/ENDPOINTGROUPID
Order status call parameters¶
Note
Request must have content-type=application/x-www-form-urlencoded.
| Status Call Parameter | Description | Necessity |
|---|---|---|
| login | Merchant login name | Mandatory |
| client_orderid | Merchant order identifier of the transaction for which the status is requested | Mandatory |
| orderid | Order id assigned to the order by Apropay | Conditional |
| 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 | Mandatory |
| 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. Include this parameter to get the status response with the particular transaction stage (can be used in specific cases). To get the latest transaction status, don’t include this parameter in status request | Optional |
In most common cases, the best option is to include both client_orderid and orderid parameters to status request. Order status can be requested with only client_orderid if it’s unique to merchant and orderid is not received. If orderid is not received in response, but this response contains an error, see the received error message to get the information why transaction was not created in the system.
Order Status Response¶
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
* - these parameters are not defined by default. Please contact tech support to include these fields in callback.
| Status Response Parameters | Description |
|---|---|
| type | The type of response. May be status-response |
| status | See Status List for details |
| amount | Actual transaction amount. This value can be changed during the transaction flow |
| currency | Currency of the initial transaction |
| paynet-order-id | Order id assigned to the order by Apropay |
| merchant-order-id | Merchant order id |
| phone | Customer phone |
| html | HTML code of 3DS authorization form, encoded in application/x-www-form-urlencoded MIME format. Merchant must decode this parameter before showing the form to the Customer. The Apropay System returns the following response parameters when it gets 3DS authorization form from the Issuer Bank. It contains auth form HTML code which must be passed through without any changes to the client’s browser. This parameter exists and has value only when the redirection HTML is already available. For non-3DS this never happens. For 3DS HTML has value after some short time after the processing has been started |
| redirect-to | For 3DS authorization the merchant can redirect the customer to URL provided in this parameter instead of rendering the page provided in html parameter. The redirect-to parameter is returned only if the html parameter is returned. Merchant should use GET HTTP method to redirect. This parameter must be used to work with 3DS 2.0 |
| 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 Receiver Registration Number |
| processor-tx-id | Acquirer transaction identifier |
| receipt-id | Electronic link to receipt https://gate.apropay.com/paynet/view-receipt/ENDPOINTID/receipt-id/ |
| 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 source card issuer. See Country Codes for details |
| 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 |
| purpose | Destination to where the payment goes. It is useful for the merchants who let their clients to transfer money from a credit card 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 |
| 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 for details |
| 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 |
| original-gate-descriptor | Descriptor, which is set on gate level in the system |
| 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 assigned to the specific request by Apropay. If this field exist in status request, status response return for this specific request |
| verified-3d-status | See 3-D Secure Status List for details |
| eci | Electronic Commerce Indicator (Visa) |
| 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) |
| merchantdata | If provided in initial request, merchant_data parameter and its value will be included in status response |
| initial-amount | Amount, set in initiating transaction, without any fees or commissions. This value can’t change during the transaction flow |
| seller-commission | Total commission for processed transaction. This is optional parameter. Please contact your manager in Apropay, if you would like to receive it |
| acquirer-commission | Acquirer commission for processed transaction. This is optional parameter. Please contact your manager in Apropay, if you would like to receive it |
| 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-0000005b5eec
&merchant-order-id=6132tc
&processor-tx-id=9568-47ed-912d-3a1067ae1d22
&paynet-order-id=161944
&status=approved
&amount=7.56
&descriptor=no
&original-gate-descriptor=test 12345678 3Ds Bank
&gate-partial-reversal=enabled
&gate-partial-capture=enabled
&transaction-type=cancel
&receipt-id=2050-3c93-a061-8a19b6c0068f
&name=FirstName
&cardholder-name=FirstName
&card-exp-month=3
&card-exp-year=2028
&email=no
&last-name=Smith
&first-name=John
&processor-rrn=510458047886
&approval-code=380424
&order-stage=cancel_approved
&last-four-digits=1111
&bin=444455
&card-type=VISA
&phone=%2B79685787194
&bank-name=UNKNOWN
&paynet-processing-date=2015-04-14+10%3A23%3A34+MSK
&by-request-sn=00000000-0000-0000-0000-0000005b5ece
&card-hash-id=1569311
&card-country-alpha-three-code=RUS
&merchantdata=promo
&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=7.56
&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 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
Order status Debug¶
Possible transaction flow scenarios can be tested with E-Commerce test cards
| String to sign |
|---|
| Signature |
|---|
|
Payment Form Integration¶
Payment Form integration is relevant for merchants who are not able to accept customer card details (merchant’s website must complete PCI DSS certification). In case of Payment Form integration merchant is released of accepting payment details and all this stuff is completely implemented on the Apropay gateway side. In addition merchant may customize the look and feel of the Payment Form. Merchant must send the template to his/her Manager for approval before it could be used.
Merchant Site initiates a Pre-auth transaction by sending corresponding HTTPS POST request to the specified URL
The System processes the transaction and sends corresponding response (depending on 3D/non-3DS processing type). Upon successful completion of a preauth transaction the bank blocks the specified amount in the credit card account and does not allow the cardholder to use this blocked money. It is important to know that the block remains for a definite period of time depending on whether this is a debit or a credit card (usually the maximum block period is 7 days for debit cards and 28 days for credit cards).
Merchant sends Capture transaction in order to deduct the locked amount from credit card.
System processes capture transaction and returns corresponding response. In this case the money is actually transferred from the bank-issuer account to the bank-acquirer account, which means the end of the transaction.
Merchant is using single entry point for both 3DS and non-3DS Preauth transactions. Actually the Merchant can not know beforehand if the sale will be driven through 3DS authorization scheme. The Merchant should use Apropay API as described below.
Payment Form API URL¶
For integration purposes use staging environment sandbox.apropay.com instead of production gate.apropay.com. Payment Form transactions are initiated through HTTPS POST request by using URL in the following format:
Form Transaction by ENDPOINTID¶
The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.
https://gate.apropay.com/paynet/api/v2/preauth-form/ENDPOINTID - for preauth transactions
Form Transaction by ENDPOINTGROUPID¶
The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.
https://gate.apropay.com/paynet/api/v2/preauth-form/group/ENDPOINTGROUPID - for preauth transactions
General Payment Form Process Flow¶
Checkout – Customer proceeds to order checkout.
Merchant initiates a transaction by sending HTTPS POST request to the specified URL. It should be /preauth-form/ENDPOINTID if DMS transaction should be accomplished.
Apropay gateway returns response which contains an additional parameter redirect-url. This is the URL where merchant must redirect Customer’s browser to.
See details about response format in Payment Form Response.
Merchant sends HTTP 302 redirect to Customer’s browser using URL which is obtained from the redirect-url response parameter.
Customer fills in payment details and submits the Payment Form.
Apropay gateway processes the transaction according to 3D or Non 3D process.
When sale authorization is completed Apropay gateway redirects the Customer’s browser to redirect_url request parameter provided by merchant in the original request accomplished at step 2. See details in Payment Form final redirect.
Payment form fields¶
This form contains the following fields:
| Form field name | Description |
|---|---|
| credit_card_number | Customer’s credit card number 4455555555555544 |
| expire_month | Credit card expiration month 01 or 12 |
| expire_year | Credit card expiration year 2016 |
| cvv2 | Card security code 432 |
Initiating a transaction with Payment Form¶
Merchant must supply the following parameters to initiate a sale transaction using payment form template.
Payment Form Request Parameters¶
Note
Request must have content-type=application/x-www-form-urlencoded.
Acquirer can redefine the necessity of some fields, so they become mandatory instead of optional.
Leading and trailing whitespace in input parameters will be omitted.
| Request parameter name | Length/Type | Comment | Necessity* |
|---|---|---|---|
| client_orderid | 128/String | Merchant order identifier | Mandatory |
| order_desc | 64k/String | Brief order description | Mandatory |
| amount | 10/Numeric | Amount to be charged. The amount has to be specified in the highest units with . delimiter. 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 |
| address1 | 50/String | Customer’s address line 1 | Mandatory |
| city | 50/String | Customer’s city | Mandatory |
| zip_code | 10/String | Customer’s ZIP code | Mandatory |
| country | 2/String | Customer’s country(two-letter country code). Please see Country Codes for a list of valid country codes | Mandatory |
| phone | 15/String | Customer’s full international phone number, including country code | Mandatory |
| 50/String | Customer’s email address | Mandatory | |
| ipaddress | 45/String | Customer’s IP address, included for fraud screening purposes | Mandatory |
| control | 40/String | Checksum generated by SHA-1. See Request authorization through control parameter for more details | Mandatory |
| first_name | 50/String | Customer’s first name. Depends on Acquirer’s side | Conditional |
| last_name | 50/String | Customer’s last name. Depends on Acquirer’s side | Conditional |
| state | 2/String | Customer’s state (two-letter state code). Please see Country Codes for a list of valid state codes. Mandatory for USA, Canada and Australia | Conditional |
| redirect_url | 1024/String | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. You should not use this parameter to retrieve results from Apropay gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead. See more details at Statuses. This parameter becomes Mandatory if both redirect_success_url and redirect_fail_url are missing | Conditional |
| redirect_success_url | 1024/String | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is approved. You should not use this parameter to retrieve results from Apropay gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead. Pass http://google.com if you use non-3DS schema for transactions processing and you have no need to return customer anywhere. This parameter becomes Mandatory if redirect_url parameter is missing | Conditional |
| redirect_fail_url | 1024/String | URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected only in case if the transaction is declined or filtered. You should not use this parameter to retrieve results from Apropay gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead. Pass http://google.com if you use non-3DS schema for transactions processing and you have no need to return customer anywhere. This parameter becomes Mandatory if redirect_url parameter is missing | Conditional |
| ssn | 4/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 |
| cell_phone | 15/String | Customer’s full international cell phone number, including country code | Optional |
| site_url | 128/String | URL the original sale is made from | Optional |
| server_callback_url | 1024/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 |
| preferred_language | 2/String | Customer’s two-letter language code for multi-language payment forms | Optional |
| merchant_form_data | 128/String | Parameters sent in merchant_form_data API parameter are parsed into macros with the same name, the parameter is url-encoded, example: testparam%3Dtest1%26mynewparam%3Dtest2 and is parsed into $MFD_testparam = test1 and $MFD_mynewparam = test2 macros in the form. Parameter name characters[a-zA-Z0-9], parameter value characters[a-zA-Z0-9], control characters [=&], 2MB max size. For example, this parameter can be used to display payment form in light/dark mode depending on the value passed by Connecting Party (e.g. pass merchant_form_data=theme%3Ddark in request and $MFD_theme macro placeholder on payment form will be changed to dark. | Optional |
| minimum_transaction_amount | 10/Numeric | This parameter can be used to limit the minimum transaction amount, if transaction amount is submitted by customer on the form. Contact support manager to enable this feature. Value format is the same as in the amount parameter. | Optional |
| maximum_transaction_amount | 10/Numeric | This parameter can be used to limit the maximum transaction amount, if transaction amount is submitted by customer on the form. Contact support manager to enable this feature. Value format is the same as in the amount parameter. | Optional |
Payment Form Response¶
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.
| Response parameter name | Description |
|---|---|
| type | The type of response. May be async-form-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 |
| error-message | If status is declined or error this parameter contains the reason for decline or error details |
| error-code | The error code in case of declined or error status |
| redirect-url | The URL to the page where the Merchant should redirect the client’s browser. Merchant should send HTTP 302 redirect, see General Payment Form Process Flow |
Payment Form final redirect¶
Upon completion of Payment Form process by the Customer he/she is automatically redirected to redirect_url. The redirection is performed as an HTTPS POST request with the parameters specified in the following table.
| Redirect parameter name | Description |
|---|---|
| status | See Status List for details |
| orderid | Order id assigned to the order by Apropay |
| merchant_order | Merchant order id |
| client_orderid | Merchant order id |
| error_message | If status is declined or error this parameter contains the reason for decline or error details |
| control | Checksum used to ensure that it is Apropay (and not a fraudster) that initiates the request. This is SHA-1 checksum of the concatenation status + orderid + client_orderid + merchant-control |
| descriptor | Gate descriptor |
| processor-tx-id | Acquirer transaction identifier |
| amount | Actual transaction amount. |
| bin | Bank BIN of customer credit card number |
| type | The type of response. |
| card-type | Type of customer credit card |
| phone | Customer phone |
| last-four-digits | Last four digits of customer credit card number |
| card-holder-name | Cardholder name |
| error_code | Error Code |
If Merchant has passed server_callback_url in original Payment Form request Apropay will call this URL. Merchant may use it for custom processing of the transaction completion, e.g. to collect sales data in Merchant’s database. The parameters sent to this URL are specified in Sale, Return Callback Parameters
Payment Form Template Sample¶
<html>
<head>
<script type="text/javascript">
function isCCValid(r){var n=r.length;if(n>19||13>n)return!1;
for(i=0,s=0,m=1,l=n;i<l;i++)d=parseInt(r.substring(l-i-1,l-i),10)*m,s+=d>=10?d%10+1:d,1==m?m++:m--;
return s%10==0?!0:!1}
</script>
</head>
<body>
<h3>Order #$!MERCHANT_ORDER_ID - $!ORDERDESCRIPTION</h3>
<h3>Total amount: $!AMOUNT $!CURRENCY to $!MERCHANT</h3>
<form action="${ACTION}" method="post">
<div>Cardholder name: <input name="${CARDHOLDER}" type="text" maxlength="64"/></div>
<div><label for="cc-number">Credit Card Number</label> <input id="cc-number" name="${CARDNO}" type="text" maxlength="19" autocomplete="cc-number"/></div>
<div>Card verification value: <input name="${CVV2}" type="text" maxlength="4" autocomplete="off"/></div>
<div>
Expiration date:
<select class="expiry-month" name="${EXPMONTH}" size="1" autocomplete="cc-exp-month" >
<option value="01">January</option><option value="02">February</option><option value="03">March</option>
<option value="04">April</option><option value="05">May</option><option value="06">June</option>
<option value="07">July</option><option value="08">August</option><option value="09">September</option>
<option value="10">October</option><option value="11">November</option><option value="12">December</option>
</select>
<select class="expiry-year" id="cc-exp-year" name="${EXPYEAR}" size="1" autocomplete="cc-exp-year">
${EXPIRE_YEARS}
</select>
</div>
$!{INTERNAL_SECTION}
#if($!card_error)
<div style="color: red;">$!card_error</div>
#end
<input name="submit" onclick="return isCCValid(document.getElementById('cardnumber').value);" type="submit" value="Pay"/>
</form>
</body>
</html>
Payment form autofill¶
If you want to use autofill in your payment form, certain element attributes <id> <autocomplete> <label for> should be hardcoded in the following manner:
<label for="cc-number">Credit Card Number</label><span class="form-label-comment">The 13-19 digits on the front of your card</span>
<input class="card-number-field" id="cc-number" name="${CARDNO}" type="text" maxlength="19" autocomplete="cc-number" />
Our default payment form template supports autocomplete. In case if you want to add additional fields for autocomplete, this specification should be used for naming references.
Payment form macros¶
| Field Name Macro | Field Value Macro | Description |
|---|---|---|
| ${CARDNO} | ${CARDNOVALUE} | Customer’s credit card number |
| ${EXPMONTH} | n/a | Credit card expiration month |
| ${EXPYEAR} | n/a | Credit card expiration year |
| ${CVV2} | ${CVV2VALUE} | Card security code 432 |
| ${CARDHOLDER} | ${CARDHOLDER_VALUE} | Card printed name |
| ${MERCHANT} | n/a | End point display name |
| ${SKIN_VERSION} | n/a | CSS skin version |
| ${ORDERDESCRIPTION} | n/a | Order description |
| ${CUSTOMER_FIRST_NAME} | n/a | Customer first name sent by merchant via input parameters |
| ${CUSTOMER_LAST_NAME} | n/a | Customer last name sent by merchant via input parameters |
| ${CUSTOMER_EMAIL} | n/a | Customer E-mail address sent by merchant via input parameters |
| ${AMOUNT} | n/a | Amount |
| ${CURRENCY} | n/a | Currency |
| ${DESTINATION_PURPOSE} | n/a | Purpose sent by Merchant via input parameters. |
| ${PAYNET_ORDER_ID} | n/a | Apropay order id |
| ${MERCHANT_ORDER_ID} | n/a | Merchant order id |
| ${refresh_interval} | n/a | Refresh interval recommended by system |
| ${uuid} | n/a | Internal |
| ${INTERNAL_SECTION} | n/a | Internal for iFrame integration |
| ${CUSTOMER_IP_COUNTRY_ISO_CODE} | n/a | Customer country defined by IP Address |
| ${PREFERRED_LANGUAGE} | n/a | Customer language sent by merchant via input parameters |
| ${BROWSER_LANGUAGE} | n/a | Customer language defined by browser settings |
| ${CUSTOMER_LANGUAGE} | n/a | Customer language sent by merchant via input parameters or defined by browser settings if first is not set |
| ${MERCHANT_FORM_DATA} | n/a | Parameters sent in merchant_form_data API parameter are parsed into macros with the same name, the parameter is url-encoded, example: testparam%3Dtest1%26mynewparam%3Dtest2 and is parsed into $MFD_testparam = test1 and $MFD_mynewparam = test2 macros in the form. Parameter name characters[a-zA-Z0-9], parameter value characters[a-zA-Z0-9], control characters [=&], 2MB max size. For example, this parameter can be used to display payment form in light/dark mode depending on the value passed by Connecting Party (e.g. pass merchant_form_data=theme%3Ddark in request and $MFD_theme macro placeholder on payment form will be changed to dark. |
| ${MIN_AMOUNT} | n/a | This macro has the value provided in minimum-transaction-amount parameter in initial request. It can be used to validate the transaction amount before payment form is submitted. Contact support manager to enable this feature. |
| ${MAX_AMOUNT} | n/a | This macro has the value provided in maximum-transaction-amount parameter in initial request. It can be used to validate the transaction amount before payment form is submitted. Contact support manager to enable this feature. |
| ${CUSTOMER_ZIP_CODE} | n/a | Generates a ZIP code to send to the processor if it was not received from the client |
Wait Page Template Sample¶
<html>
<head>
<script type="text/javascript">
function fc(t) {
document.getElementById("seconds-remaining").innerHTML = t;
(t > 0) ? setTimeout(function(){fc(--t);}, 1000) : document.checkform.submit();}
</script>
</head>
<body onload="fc($!refresh_interval)">
<h3>Order #$!MERCHANT_ORDER_ID - $!ORDERDESCRIPTION</h3>
<h3>Total amount: $!AMOUNT $!CURRENCY to $!MERCHANT</h3>
Please wait, your payment is being processed, remaining <span id="seconds-remaining"> </span> seconds.
<form name="checkform" method="post">
<input type="hidden" name="tmp" value="$!uuid"/>
$!{INTERNAL_SECTION}
<input type="submit" value="Check" />
</form>
</body>
</html>
Wait Page macros¶
| Field Name Macro | Field Value Macro | Description |
|---|---|---|
| ${MERCHANT} | n/a | End point display name |
| ${SKIN_VERSION} | n/a | CSS skin version |
| ${ORDERDESCRIPTION} | n/a | Order description |
| ${AMOUNT} | n/a | Amount |
| ${CURRENCY} | n/a | Currency |
| ${PAYNET_ORDER_ID} | n/a | Apropay order id |
| ${MERCHANT_ORDER_ID} | n/a | Merchant order id |
| ${refresh_interval} | n/a | Refresh interval recommended by system |
| ${uuid} | n/a | Internal |
| ${INTERNAL_SECTION} | n/a | Internal for iFrame integration |
| ${CUSTOMER_IP_COUNTRY_ISO_CODE} | n/a | Customer country defined by IP Address |
| ${PREFERRED_LANGUAGE} | n/a | Customer language send by merchant via input parameters |
| ${BROWSER_LANGUAGE} | n/a | Customer language defined by browser settings |
| ${CUSTOMER_LANGUAGE} | n/a | Customer language send by merchant via input parameters or defined by browser settings if first is not set |
Finish Page Template Sample¶
<html>
<head>
</head>
<body>
<h3>Processing of the payment has finished</h3>
<h3>Order Invoice: $!{MERCHANT_ORDER_ID}</h3>
<h3>Order ID: $!{PAYNET_ORDER_ID}</h3>
<h3>Status: $!{STATUS}</h3>
#if($ERROR_MESSAGE)
<h3>Error: $!{ERROR_MESSAGE}</h3>
#end
</body>
</html>
Finish Page Macros¶
| Field Name Macro | Field Value Macro | Description |
|---|---|---|
| ${STATUS} | n/a | Order status |
| ${PAYNET_ORDER_ID} | n/a | System order id |
| ${MERCHANT_ORDER_ID} | n/a | Merchant order id |
| ${ERROR_MESSAGE} | n/a | Contains the reason for decline or error details |
| ${SKIN_VERSION} | n/a | CSS skin version |
| ${CUSTOMER_IP_COUNTRY_ISO_CODE} | n/a | Customer country defined by IP Address |
| ${PREFERRED_LANGUAGE} | n/a | Customer language send by merchant via input parameters |
| ${BROWSER_LANGUAGE} | n/a | Customer language defined by browser settings |
| ${CUSTOMER_LANGUAGE} | n/a | Customer language send by merchant via input parameters or defined by browser settings if first is not set |
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:
- ENDPOINTID/ENDPOINTGROUPID
- client_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)
- merchant_control
A complete string example may look as follows:
59I6email@client.com3E8E45B5-2-42D8-6ECC-FBF6B11B1
Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter (see Payment Form Request Parameters) which is required for request authorization. For the above-mentioned example the control will take the following value:
d02e67236575a8e02dea5e094f3c8f12f0db43d7
Payment Form Request Debug¶
Possible transaction flow scenarios can be tested with E-Commerce test cards
| 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 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.
See more details at Statuses
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:
The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.
https://gate.apropay.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.apropay.com/paynet/api/v2/status/group/ENDPOINTGROUPID
Order status call parameters¶
Note
Request must have content-type=application/x-www-form-urlencoded.
| Status Call Parameter | Description | Necessity |
|---|---|---|
| login | Merchant login name | Mandatory |
| client_orderid | Merchant order identifier of the transaction for which the status is requested | Mandatory |
| orderid | Order id assigned to the order by Apropay | Conditional |
| 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 | Mandatory |
| 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. Include this parameter to get the status response with the particular transaction stage (can be used in specific cases). To get the latest transaction status, don’t include this parameter in status request | Optional |
In most common cases, the best option is to include both client_orderid and orderid parameters to status request. Order status can be requested with only client_orderid if it’s unique to merchant and orderid is not received. If orderid is not received in response, but this response contains an error, see the received error message to get the information why transaction was not created in the system.
Order Status Response¶
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.
* - these parameters are not defined by default. Please contact tech support to include these fields in callback.
| 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 of the initial transaction |
| 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 Receiver Registration Number |
| processor-tx-id | Acquirer transaction identifier |
| receipt-id | Electronic link to receipt https://gate.apropay.com/paynet/view-receipt/ENDPOINTID/receipt-id/ |
| 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 source card issuer. See Country Codes for details |
| 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 |
| 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 for details |
| 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 |
| original-gate-descriptor | Descriptor, which is set on gate level in the system |
| 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 3-D Secure Status List for details |
| eci | Electronic Commerce Indicator (Visa) |
| 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 |
| seller-commission | Total commission for processed transaction. This is optional parameter. Please contact your manager in Apropay, if you would like to receive it |
| acquirer-commission | Acquirer commission for processed transaction. This is optional parameter. Please contact your manager in Apropay, if you would like to receive it |
| 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-0000005b5eec
&merchant-order-id=6132tc
&processor-tx-id=9568-47ed-912d-3a1067ae1d22
&paynet-order-id=161944
&status=approved
&amount=7.56
&descriptor=no
&original-gate-descriptor=test 12345678 3Ds Bank
&gate-partial-reversal=enabled
&gate-partial-capture=enabled
&transaction-type=cancel
&receipt-id=2050-3c93-a061-8a19b6c0068f
&name=FirstName
&cardholder-name=FirstName
&card-exp-month=3
&card-exp-year=2028
&email=no
&last-name=Smith
&first-name=John
&processor-rrn=510458047886
&approval-code=380424
&order-stage=cancel_approved
&last-four-digits=1111
&bin=444455
&card-type=VISA
&phone=%2B79685787194
&bank-name=UNKNOWN
&paynet-processing-date=2015-04-14+10%3A23%3A34+MSK
&by-request-sn=00000000-0000-0000-0000-0000005b5ece
&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=7.56
&motivational-message=Sorry, your payment has been declined.
&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 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
Order status Debug¶
Possible transaction flow scenarios can be tested with E-Commerce test cards
| String to sign |
|---|
| Signature |
|---|
|