1.1.3. Recurrent Transactions¶
Recurrent Payment General Flow¶
Recurrent payments are made in three steps:
1. Initial payment – any transaction type with present cardholder data will work as initial payment - sale, preauth, transfer, etc.. It is important to make the initial payment the most secure way in order to guarantee that a real card holder is registering the card. To insure this, Merchant might use one of the following identification approaches or their combination: Verified by Visa, MasterCard SecureCode, random amount withdrawal verification, anti-fraud systems(e.g. MaxMind) check.
2. Card registration – get card token and register customer’s card in customer’s profile. Merchant should get Card Token ID that will be used in future recurrent payments in order to avoid storing the credit card sensitive data which is required by PCI DSS. Card Token ID is totally secure and cannot be used by fraudsters to carry ou fraudulent transaction even if they know it. This allows to securely save Card Token ID in Customer’s profile on the Merchant’s side. These are all of the tokens that Merchant can get:
card-ref-id - Card Reference ID which allows to initiate transaction without re-entering card information.
recurring-payment-id - Card Recurring Payment ID is also a token for cardholder data, which is used in different set of APIs and also can be used in initiating automate transactions.
dst-card-ref-id - Destination Card Reference ID can only be used in transfer transactions as a destination card.
dst-recurring-payment-id- Destination Recurring Payment ID can only be used in transfer transactions as a destination card.
All mentioned Card Token IDs can be used unlimited number of times and also can be created only for a transaction in final status. See Status List.
3. Recurrent payment – run recurrent payment when a business event is triggered on the Merchant. The necessity of customer’s 3DS check and submit of card security code (CVC, CVV, etc) for recurrent payment is determined by bank account settings and related to Merchant’s business type.
(1) Customer picks up a service from Merchant’s portfolio to register the credit card, after which customer initiates payment (any transaction type with present cardholder data will work as initial payment - sale, preauth, transfer, etc.).
(2) Merchant shows the result of the initial transaction.
(3) Merchant requests Card Token ID from Apropay.
(4) Apropay returns card-ref-id if token was request via v2/create-card-ref/.
(5) Apropay returns recurring-payment-id if token was request via v4/create-card-ref/.
(6) Apropay returns dst-card-ref-id if token was request via v4/create-card-ref/. This parameter can only be used in transfer transactions as a destination card.
(7) Apropay returns dst-recurring-payment-id if token was request via v4/create-card-ref/ and destination card was specified in initial request. This parameter can only be used in transfer transactions as a destination card.
(8) Merchant assigns Card Token ID Customer’s profile, after which Merchant shows the page saying that the card registration is successful and initial payment approved.
(9) Merchant might request card info by card-ref-id.
(11) Recurring payment can be initiated by Merchant based on internal business model or Customer’s request.
(12) Merchant initiates recurrent payment using given Card Token ID.
(13) Merchant gets Card Token ID in Customer’s profile.
(15) Apropay returns new Order ID for the recurrent payment.
(16) To implement Callback see Merchant Callbacks.
(18) To implement order status request see Statuses. Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
(20) Final Status can be sent by Merchant based on internal business model or Customer’s request.
Process Card Registration via v2/create-card-ref¶
Card Registration Diagram¶
(1) Customer picks up a service from Merchant’s portfolio to register the credit card, after which customer initiates payment (any transaction type with present cardholder data will work as initial payment - sale, preauth, transfer, etc.).
(2) Merchant shows the result of the initial transaction.
(3) Merchant requests Card Reference ID card-ref-id from Apropay.
(4) Apropay returns card-ref-id.
(5) Merchant assigns Card Reference ID to Customer’s profile.
Card Registration request URL¶
For integration purposes use staging environment sandbox.apropay.com instead of production gate.apropay.com. Card registration transactions 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/create-card-ref/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/create-card-ref/group/ENDPOINTGROUPID
Card registration request parameters¶
Note
Request must have content-type=application/x-www-form-urlencoded.
| Registration request 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. |
| control | Checksum used to ensure that it is the Merchant (and not a fraudster) who sends the request. This is SHA-1 checksum of the concatenation login + client-order-id + paynet-order-id + merchant-control. |
As you may see from the parameters list Merchant has to supply orderid and client_orderid associated with the first payment transaction. It emphasizes that the first payment is a mandatory step to process recurrent payments.
Card Registration 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.
| Registration Response Parameter | Description |
|---|---|
| type | The type of response. May be create-card-ref-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. |
| card-ref-id | Customer’s tokenized cardholder’s data ID used in subsequent recurrent payments. |
| unq-card-ref-id | Unique customer’s tokenized cardholder’s data ID to each PAN. It can be used by Merchant for loyalty programs or fraud control. |
| 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. |
| error-code | The error code is case of declined or error status. |
| end-point-id | Endpoint id used for the transaction. |
Request Example¶
POST /paynet/api/v2/create-card-ref/39915 HTTP/1.1
Host: sandbox.apropay.com
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 107
Content-Type: application/x-www-form-urlencoded
Connection: close
login=ZetMerchant
&client_orderid=34T43R77N
&orderid=6868525
&control=a0c10643aef72cf6612b29fdaea01d74d1071e38
Success Response Example¶
HTTP/1.1 200
Server: server
Date: Thu, 29 Dec 2022 13:35:34 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 144
type=create-card-ref-response
&serial-number=00000000-0000-0000-0000-000002ddfdfe
&card-ref-id=1461618
&unq-card-ref-id=2463777
&status=approved
Fail Response Example¶
HTTP/1.1 200
Server: server
Date: Thu, 29 Dec 2022 13:32:32 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 123
type=validation-error
&serial-number=00000000-0000-0000-0000-000002ddfd9c
&error-message=INVALID_CONTROL_CODE
&error-code=2
Process Card Registration via v4/create-card-ref¶
Card Registration Diagram¶
(1) Customer picks up a service from Merchant’s portfolio to register the credit card, after which customer initiates payment (any transaction type with present cardholder data will work as initial payment - sale, preauth, transfer, etc.).
(2) Merchant shows the result of the initial transaction.
(3) Merchant requests Card Token ID from from Apropay.
(4) Apropay returns card-ref-id.
(5) Apropay returns recurring-payment-id.
(6) Apropay returns dst-card-ref-id. This parameter can only be used in transfer transactions as a destination card.
(7) Apropay returns dst-recurring-payment-id. if destination card was specified in initial request. This parameter can only be used in transfer transactions as a destination card.
(8) Merchant assigns Card Token ID to Customer’s profile.
Card Registration request URL¶
For integration purposes use staging environment sandbox.apropay.com instead of production gate.apropay.com. Card registration transactions 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/v4/create-card-ref/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/v4/create-card-ref/group/ENDPOINTIDGROUPID
Card registration request parameters¶
Note
Request must have content-type=application/x-www-form-urlencoded.
| Registration request Parameter | Description |
|---|---|
| client_orderid | Merchant order identifier of the transaction for which the status is requested. |
| orderid | Order id assigned to the order by Apropay. |
As you may see from the parameters list Merchant has to supply orderid and client_orderid associated with the first payment transaction. It emphasizes that the first payment is a mandatory step to process recurrent payments.
Card Registration 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.
| Registration Response Parameter | Description |
|---|---|
| type | The type of response. May be create-card-ref-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. |
| card-ref-id | Customer’s tokenized cardholder’s data ID used in subsequent recurring payments. |
| recurring-payment-id | Customer’s tokenized cardholder’s data ID which is used in different set of APIs and also can be used in initiating automate transactions. |
| dst-card-ref-id | Customer’s tokenized cardholder’s data ID. Can be used only in transfer APIs as a destination card. |
| dst-recurring-payment-id | Customer’s tokenized cardholder’s data ID. Can be used only in transfer APIs as a destination card. |
| 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. |
| error-code | The error code is case of declined or error status. |
| end-point-id | Endpoint id used for the transaction. |
* card-ref-id and recurring-payment-id contains full information about cardholder data (PAN, exp date, cardholder name).
* dst-card-ref-id and dst-recurring-payment-id contains information only about PAN.
Card Registration Request Debug¶
Enter your private key in PKCS#1 container to use debug. See OAuth RSA-SHA256 for details.
Debug form
| Normalized parameters string to sign, according to OAuth 1.0a rules |
|---|
| POST body parameters to submit |
|---|
| OAuth 1.0a headers to submit. |
|---|
| HEX Encoded Signature |
|---|
| Base64 Encoded Signature |
|---|
|
Request Example¶
POST /paynet/api/v4/create-card-ref/39915 HTTP/1.1
Host: sandbox.apropay.com
User-Agent: curl/7.83.0
Accept: */*
Authorization: OAuth oauth_consumer_key="ZetMerchant", oauth_nonce="KT6cZmuVGqg0V6Jm2RE3q4o79KXC1v2q", oauth_signature="KucF0eYk3WZCV7oKwOi1z6PR%2BkHxiZwPucD6Sx%2BX2mV%2BbaidPy9K9USh8ciMKM60NNl1LYYjywdaErB1uTIdFFbQ8ZKs8M1smaMPOaHDaApceTOlDh6E7u3BzBTKYhBc%2BWnksZz9Wyz8%2B39lHCIODo0KZmNmXCTjjZmlx%2FrFNkK%2FhwJV9Kwq1nPbA5QZTkF686O0O0lHFy3Prx649AIRgsrqDLb5%2FgHL9M8fSScVUPnGdLGJ2hSgKJFpIOFibT0nC89Xg8odn1hR9WIa1650glaqZntSkocBzXAkOKa7kIbSOZW1sFCiBjksy6o1sny9hmc%2F9cC9t86RoEY1QhVYuvOLztQm1dLhpRy%2FPOL9LCmIzO3B%2FUB2wJUXPkEyFsSLZVeqQl%2B0IukljV6Cr1ZfuyUktbvvXJsnod5AK%2FsV2GaxEf%2BttqqWv%2FFNjPLoUZYrPB6rKsIpw%2FOftinIwIxYzLY3FMmbKQd6zxnMJLJm7M2s6cQFGiAnfgvZFAMZhugBuuigy4T9Ckq1t5N9vQkl2htDv0TTnswx50wpF%2F7OKiXTVFNqOE%2FCj%2F07ZwZbxbD%2FMxKhOhfNMME1jGxzgI0wEj1166eKpxnCOk%2BTlYTJvNW5%2BbKuGnU43Q2Nmga0aQ007NKRfIV%2FWk6e%2BUuGO48wGdi0CiKxS9hpnpvjyPLc%2BsA%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1673335450", oauth_version="1.0"
Content-Length: 40
Content-Type: application/x-www-form-urlencoded
Connection: close
client_orderid=34T43R77N
&orderid=6868305
Success Response Example¶
HTTP/1.1 200
Server: server
Date: Tue, 10 Jan 2023 07:24:36 GMT
Content-Type: text/html;charset=utf-8
Connection: close
Vary: Accept-Encoding
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
Content-Language: en-US
Strict-Transport-Security: max-age=31536000
Content-Length: 174
type=create-card-ref-response
&serial-number=00000000-0000-0000-0000-000002de3113
&card-ref-id=1461608
&recurring-payment-id=1491863
&dst-card-ref-id=1461608
&status=approved
Fail Response Example¶
HTTP/1.1 403
Server: server
Date: Tue, 10 Jan 2023 07:34:08 GMT
Content-Type: text/html
Content-Length: 735
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>403</title>
<style type="text/css">
body {
font-family: Arial, sans-serif;
font-size: 130%;
background-color: #eee;
}
p {
margin: 10em auto 0;
width: 500px;
border: 1px solid gray;
text-align: center;
vertical-align: middle;
padding: 40px 20px;
background-color: #fff;
-webkit-border-radius: 20px;
-moz-border-radius: 20px;
border-radius: 20px;
}
</style>
</head>
<body>
<p>Access is denied</p>
</body>
</html>
Get Cardholder details with Card Reference Identifier¶
Cardholder details request URL¶
For integration purposes use staging environment sandbox.apropay.com instead of production gate.apropay.com. Merchant requests Card details by sending HTTPS request to the server. In order to make this request Merchant is required to pass card-ref-id with the request. Use the following URL to make the request:
The End point ID is an entry point for incoming Merchant’s transactions for single currency integration.
https://gate.apropay.com/paynet/api/v2/get-card-info/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/get-card-info/group/ENDPOINTGROUPID
Card Information request parameters¶
Note
Request must have content-type=application/x-www-form-urlencoded.
| Information request Parameter | Length/Type | Comment | Necessity* |
|---|---|---|---|
| login | 20/String | Merchant login name. | Mandatory |
| cardrefid | 20/String | Equals to card-ref-id obtained in card information reference id call during Card Registration stage. | Mandatory |
| 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 + cardrefid + merchant_control. | Mandatory |
Get Card Information 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.
| Information Response Parameter | Description |
|---|---|
| type | The type of response. May be get-card-info-response, validation-error, error. If type equals error, error-message and error-code parameters contain error details. |
| card-printed-name | Card holder name. |
| expire-year | Card expiration year. |
| expire-month | Card expiration month. |
| bin | Bank Identification Number. |
| last-four-digits | The last four digits of PAN. |
| serial-number | Unique number assigned by Apropay server to particular request from the Merchant. |
| error-message | If status is validation-error or error this parameter contains the reason for decline or error details. |
| error-code | The error code is case of validation-error or error status. |
Process Recurrent Payment¶
Successful Recurrent Payment Diagram¶
(1) Merchant’s application triggers an event that requires to withdraw some amount from the Customer’s card.
(2) Merchant gets card reference id card-ref-id in Customer’s profile.
(3) Merchant initiates recurrent payment using given card-ref-id.
(4) Apropay returns new Order ID for the recurrent payment.
(5) To implement Callback see Merchant Callbacks.
(7) To implement order status request see Statuses. Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.
Recurrent Payment request URL¶
For integration purposes use staging environment sandbox.apropay.com instead of production gate.apropay.com. Recurrent payments transactions 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/make-rebill/ENDPOINTID – to make recurrent payment SALE.
https://gate.apropay.com/paynet/api/v2/make-rebill-preauth/ENDPOINTID – to make recurrent payment AUTH.
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/make-rebill/group/ENDPOINTGROUPID – to make recurrent payment SALE.
https://gate.apropay.com/paynet/api/v2/make-rebill-preauth/group/ENDPOINTGROUPID – to make recurrent payment AUTH.
Recurrent Payment request parameters¶
Note
Request must have content-type=application/x-www-form-urlencoded.
Leading and trailing whitespace in input parameters will be omitted.
| Payment request parameter | Length/Type | Comment | Necessity* |
|---|---|---|---|
| client_orderid | 128/String | Merchant order identifier. | Mandatory |
| login | 20/String | Merchant’s login. | Mandatory |
| cardrefid | 20/String | Card reference id obtained at Card Registration step. | Mandatory |
| order_desc | 64k/String | 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 |
| enumerate_amounts | 128/String | This parameter may comprise multiple amounts, separated with ,. Apropay will cycle through the amounts of the list, try to make a payment on that amount, until there are no more amounts from the list, or not get approved. | Optional |
| currency | 3/String | Currency the transaction is charged in (three-letter currency code). Example ofВ valid parameter values are: USD for US Dollar EUR for European Euro. | 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. May be empty or absent if bank gateway supports processing without CVV2. | Optional |
| ipaddress | 45/String | Customer’s IP address, included for fraud screening purposes. | Mandatory |
| control | 40/String | Checksum generated by SHA-1. This is SHA-1 checksum of the concatenation login + client_orderid + cardrefid + amount_in_cents + currency + merchant_control. | Mandatory |
| comment | 50/String | A short comment. | 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 |
| 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. Parameter is mandatory for 3DS flow and optional for non-3DS. Pass http://google.com if you are not sure. | Optional |
| 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. | Optional |
| 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. | 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 |
| 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 |
| recurrent_scenario | 50/String | Type of the rebill transaction. Possible values: REGULAR or IRREGULAR. If this parameter is sent in the request, it will have priority over the same parameter specified on gate level. Only used for specific acquirers. | Optional |
| recurrent_initiator | 50/String | Initiator of the rebill transaction. Possible values: CARDHOLDER or MERCHANT. If this parameter is sent in the request, it will have priority over the same parameter specified on gate level. Only used for specific acquirers. | Optional |
Recurrent 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.
| Recurrent 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. |
Recurrent 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
- login
- client_orderid
- cardrefid
- 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:
logic902B4FF550703500EURB17F59B4-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:
9d7370ef6d3c632f2a3b50c4a07041d87e27bbf8
Recurrent 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:
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 Request 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
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.
* - 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/. |
| 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 source card issuer. See Country Codes for details. |
| destination-card-country-alpha-three-code | Three letter country code of destination 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) |
| 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-00000aa68276
&merchant-order-id=pg1sbw
&processor-tx-id=15222817
&paynet-order-id=15222817
&status=approved
&amount=20000.00
&descriptor=no
&original-gate-descriptor=test 12345678 3Ds Bank
&transaction-type=sale
&receipt-id=18042926-d652-331c-b5a0-3e1dbacf69b2
&name=HOLDER
&cardholder-name=HOLDER
&card-exp-month=3
&card-exp-year=2016
&email=gmail.com
&last-name=Smith
&first-name=John
&processor-rrn=187722741
&approval-code=610669
&order-stage=sale_approved
&last-four-digits=7682
&bin=427655
&card-type=VISA
&phone=%2B79633014273
&bank-name=SBERBANK
&paynet-processing-date=2015-04-06+22%3A00%3A27+MSK
&by-request-sn=00000000-0000-0000-0000-00000a8d3992
&card-hash-id=1664889
&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
&merchantdata=promo
&initial-amount=20000.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 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