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.

autonumber
Customer -> Merchant: Pick up recurrent service
activate Merchant
hnote over Customer,"Apropay" : Process initial transaction
Merchant -> Customer: Show result
deactivate Merchant
== Initiate Card Registration ==
Alt
Merchant -> "Apropay": Initiate card registration via v2/create-card-ref
activate Merchant
activate "Apropay"
"Apropay" --> Merchant: Return card-ref-id
else
Merchant -> "Apropay": Initiate card registration via v4/create-card-ref
"Apropay" --> Merchant: Return card-ref-id
"Apropay" --> Merchant: Return recurring-payment-id
"Apropay" --> Merchant: Return dst-card-ref-id
deactivate "Apropay"
end
Merchant -> Merchant: Assign Card Token ID to Customers profile
== Get Card Info ==
group Optional
Merchant -> "Apropay": Get Card info By card-ref-id
activate "Apropay"
"Apropay" --> Merchant: Return Card info By card-ref-id
deactivate Merchant
deactivate "Apropay"
end
== Recurrent Payment ==
group Optional
Customer -> Merchant: Initiate Recurrent payment
activate Merchant
end
Merchant -> Merchant: Start recurrent payment
Merchant -> Merchant: Get card ref id from customers profile
Merchant -> "Apropay": Make recurrent payment
activate "Apropay"
"Apropay" --> Merchant: type=async-response, OrderID
group Get Final Status
== Receive Merchant Callback ==
Merchant <- "Apropay" : callback with final status
"Apropay" <-- Merchant: HTTP 200
deactivate "Apropay"
== Order Status request ==
Merchant -> "Apropay": Get status by Order ID\napi/v2/status
activate "Apropay"
"Apropay" --> Merchant : Response\nstatus,order-stage
deactivate "Apropay"
end
group Optional
Merchant -> Customer: Final Status
deactivate Merchant
end

(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

autonumber
Customer -> Merchant: Pick up recurrent service
hnote over Customer,"Apropay" : Process initial transaction
Merchant -> Customer: Show result
== Initiate Card Registration ==
Merchant -> "Apropay": Get card-ref-id
activate "Apropay"
activate Merchant
"Apropay" --> Merchant: Return card-ref-id
deactivate "Apropay"
Merchant -> Merchant: Assign card-ref-id to Customers profile

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

Card Registration Request Postman Collection

Card Registration Request Debug

endpointid or groupid input your ENDPOINTID or ENDPOINTGROUPID
login
client_orderid input your Invoice Number
orderid
merchant_control input your Control Key

String to sign
Signature
              
            
			
		
			
		
			
		

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

autonumber
Customer -> Merchant: Pick up recurrent service
hnote over Customer,"Apropay" : Process initial transaction
Merchant -> Customer: Show result
Merchant -> "Apropay": Initiate card registration
activate Merchant
activate "Apropay"
activate Merchant
"Apropay" --> Merchant: Return card-ref-id
"Apropay" --> Merchant: Return recurring-payment-id
"Apropay" --> Merchant: Return dst-card-ref-id
"Apropay" --> Merchant: Return dst-recurring-payment-id
deactivate "Apropay"
Merchant -> Merchant: Assign card ref ID to Customers profile

(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 Postman Collection

Card Registration Request Debug

Enter your private key in PKCS#1 container to use debug. See OAuth RSA-SHA256 for details.

Debug form
URL
login your login will be used as Consumer Public for OAuth header, not included as request body parameter
client_orderid
orderid

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
* HEX encoded string is for debug purposes only. You shouldn't send this string to the server neither in HEX nor in Encoded HEX representation.
Base64 Encoded Signature
* Binary RSA-SHA256 signature directly encoded in base64 should be sent to the server.

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.

Get Card Information Postman Collection

Get Card Information Debug

endpointid or groupid input your ENDPOINTID or ENDPOINTGROUPID
login
card-ref-id
merchant_control input your Control Key

String to sign
Signature
              
            
  

   









Process Recurrent Payment

Successful Recurrent Payment Diagram

autonumber
activate Merchant
Merchant -> Merchant: Start recurrent payment
Merchant -> Merchant: Get card ref id from customers profile
Merchant -> "Apropay": Make recurrent payment
activate "Apropay"
"Apropay" --> Merchant: type=async-response, OrderID
group Get Final Status
== Receive Merchant Callback ==
Merchant <- "Apropay" : callback with final status
"Apropay" <-- Merchant: HTTP 200
deactivate "Apropay"
== Order Status request ==
Merchant -> "Apropay": Get status by Order ID\napi/v2/status
activate "Apropay"
"Apropay" --> Merchant : Response\nstatus,order-stage
deactivate "Apropay"
end
deactivate Merchant

(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

Recurrent Payment request Postman Collection

Recurrent Payment request Debug

endpointid or groupid input your ENDPOINTID or ENDPOINTGROUPID
login
client_orderid make it or use your internal invoice ID
cardrefid
amount
currency
enumerate_amounts
recurrent_scenario
recurrent_initiator
cvv2
ipaddress
comment
order_desc
merchant_control input your Control Key

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.

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

Order status Postman Collection

Order status Debug

endpointid or groupid input your ENDPOINTID or ENDPOINTGROUPID
login
client_orderid input your Invoice Number
orderid
merchant_control input your Control Key
by-request-sn

String to sign
Signature