1.1.1. Sale Transactions

Direct integration

General Sale Process Flow

  1. Merchant initiates a transaction by sending HTTPS POST request to the specified URL
  2. Apropay server immediately returns the response back to Merchant. The response contains paynet-order-id. For detailed request and response format see Sale Request Parameters Table.
  3. Merchant shows the Customer message like Your order is being processed. Please, wait…. 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.
  4. Apropay Server determines if 3DS is required or not and drives the transaction authorization process as appropriate.
  5. Merchant is using single entry point for both 3DS and non-3DS Sale 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.

@startuml |Customer| start :checkout order; |#AntiqueWhite|Merchant| :process sale; |"Apropay"| :start transaction; |Merchant| :get order status; |"Apropay"| if (3DS status required?) then (yes) :3DS sale process; |Merchant| :follow 3DS sale processing; |Customer| :3-D Secure validation; stop else (no) |"Apropay"| :non-3DS sale process; |Merchant| :final order status; stop endif @enduml

checkout order Customer checks out the order on Merchant’s website
process sale Merchant sends Sale request to Apropay server with specified parameters described in Sale 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 Sale 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.
3DS status required? Apropay Gateway determines if 3DS authorization required for the incoming sale transaction.
Non-3DS sale 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 Sale transaction diagram for details.
3DS sale 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 Sale transaction diagram.

Non-3DS Sale transaction diagram

Merchant is using single entry point for both 3DS and non-3DS Sale 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 in General Sale Process Flow.

@startuml Merchant -> "Apropay": Sale request activate "Apropay" "Apropay" --> Merchant: Order ID "Apropay" -> Acquirer: Process sale activate Acquirer Merchant -> "Apropay": Get status by Order ID Acquirer --> "Apropay": Processing result deactivate Acquirer "Apropay" --> Merchant: Final status deactivate "Apropay" @enduml

Sale request Customer checks out the order and Merchant sends non-3DS Sale request to Apropay server with specified parameters described in Sale 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 Sale Apropay server forwards Sale request to bank acquirer asynchronously. The bank starts processing the transaction.
Get status by Order Id Merchant is polling for status with given orderid as described in Order status asynchronous call.
Processing result The bank responds to Apropay server with approve or decline for requested Sale.
Final status Apropay server returns status to Merchant through Order status asynchronous call.

3DS Sale transaction diagram

Merchant is using single entry point for both 3DS and non-3DS Sale 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 in General Sale Process Flow.

Customer -> Merchant: Checkout order activate Merchant Merchant -> "Apropay": Process 3DS sale activate "Apropay" "Apropay" -> Issuer: Get Auth Form activate Issuer Issuer --> "Apropay": Return 3DS form HTML deactivate Issuer "Apropay" --> Merchant: 3DS response with auth form deactivate "Apropay" Merchant -> Customer: Show 3DS form deactivate Merchant Customer -> Issuer: Customer submits additional auth data activate Issuer Issuer --> "Apropay": Authorized deactivate Issuer activate "Apropay" "Apropay" -> Acquirer: Process sale activate Acquirer Acquirer --> "Apropay": Sale result deactivate Acquirer "Apropay" --> Customer: Show auto submit order form deactivate "Apropay" Customer -> Merchant: Auto submit form with order id activate Merchant Merchant --> Customer: Show final page deactivate Merchant

Checkout order Customer checks out the order on Merchant’s website
Process 3DS Sale Merchant sends 3DS Sale request to Apropay server with specified parameters described in Sale 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 Sale 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 Sale Apropay server forwards Sale request to bank acquirer. The bank starts processing the transaction.
Sale result The bank responds to Apropay server with approve or decline for requested Sale
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 Sale transaction

Sale transaction request URL

For integration purposes use staging environment sandbox.apropay.com instead of production gate.apropay.com. Sale 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/sale/ENDPOINTID – for sale and recurrent sale transactions

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/sale/group/ENDPOINTGROUPID – for sale and recurrent sale transactions

Sale Request Parameters

In order to initiate a Sale transaction Merchant sends an HTTPS POST request with the parameters specified in Sale Request Parameters Table below

Note

Request must have content-type=application/x-www-form-urlencoded.
Leading and trailing whitespace in input parameters will be omitted.
Please note the following characters must be escaped in the parameter values: & + “.
Sale Request Parameters 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. 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 Country Codes for a list of valid country codes Mandatory
phone 15/String Customer’s full international phone number, including country code Mandatory
email 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 128/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 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. 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 Sale 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 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
dapi_imei 32/String Unique device identifier Optional

Additional fields for sale transactions

For merchants - customer browser information and 3DS results notification URL

Note

Browser data for 3DS 2.X is gathered by Apropay system on 3DS authentication stage. For some processing channels, however, the browser data and/or merchant URL for 3DS challenge results must be provided in initial transaction request. Please contact Support manager to clarify if these parameters should be included in request parameters.

The merchant’s site needs to accurately populate the browser information for each transaction. This data can be obtained by merchant’s servers. Ensure that the data is not altered or hard-coded, and that it is unique to each transaction.

Field Name Length/Type Description Conditional Inclusion
tds_areq_notification_url, alias tds_cres_notification_url 256/String Fully qualified URL of merchant system that will receive the CRes message or Error Message. This CRes message must be sent to Apropay. See details here Upload CRes Result Optional
customer_browser_info Boolean If true, then the fields below must be present Optional
ipaddress 45/String IP address of the browser as returned by the HTTP headers to the 3DS Requestor Required
customer_browser_accept_header 2048/String Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser Required
customer_browser_color_depth 2/String Value representing the bit depth of the colour palette for displaying images, in bits per pixel Required when browser_javaScript_enabled = true; otherwise Optional
customer_browser_java_enabled Boolean Boolean that represents the ability of the cardholder browser to execute Java Required when browser_javaScript_enabled = true; otherwise Optional
customer_browser_javascript_enabled Boolean Boolean that represents the ability of the cardholder browser to execute JavaScript Required
customer_browser_accept_language 8/String Value representing the browser language as defined in IETF BCP47 Required
customer_browser_screen_height 6/Numeric Total height of the Cardholder’s screen in pixels Required when browser_javaScript_enabled = true; otherwise Optional
customer_browser_screen_width 6/Numeric Total width of the cardholder’s screen in pixels Required when browser_javaScript_enabled = true; otherwise Optional
customer_browser_time_zone 5/String Time-zone offset in minutes between UTC and the Cardholder browser local time. Note that the offset is positive if the local time zone is behind UTC and negative if it is ahead Required when browser_javaScript_enabled = true; otherwise Optional
customer_browser_user_agent 2048/String Exact content of the HTTP user-agent header Required
For PSPs and Acquirers - 3DS authentication results

The PSP or Acquirer can fill the 3DS results for each transaction, if 3DS authentication is performed on their side.

Field Name Length/Type Description
tds_authentication_result_type 6/String
Type of result. Possible values are:
- SIMPLE
tds_authentication_result_authentication_type 2/String
Authentication Type. Indicates the type of authentication method the Issuer will use to challenge the Cardholder, whether in the ARes message or what was used by the ACS when in the RReq message. Possible values are:
- 01 = Static
- 02 = Dynamic
- 03 = OOB
- 04 = Decoupled
- 05-79 = Reserved for EMVCo future use (values invalid until defined by EMVCo)
- 80-99 = Reserved for DS use
tds_authentication_result_authentication_value 19-28/String Authentication Value. Payment System-specific value provided by the ACS or the DS using an algorithm defined by Payment System. Authentication Value may be used to provide proof of authentication. A 20-byte value that has been Base64 encoded, giving a 28-byte result
tds_authentication_result_transaction_id 19-36/String xid for 1.0.2 or dsTransID for 2.1.0/2.2.0
tds_authentication_result_transaction_status 1/String
Transaction Status. Indicates whether a transaction qualifies as an authenticated transaction or account verification. Possible values are:
- Y = Authentication Verification Successful
- N = Not Authenticated/Account Not Verified, Transaction denied
- U = Authentication/Account Verification Could Not Be Performed, Technical or other problem, as indicated in ARes or RReq
- A = Attempts Processing Performed, Not Authenticated/Verified, but a proof of attempted authentication/verification is provided
- C = Challenge Required, Additional authentication is required using the CReq/CRes
- D = Challenge Required, Decoupled Authentication confirmed
- R = Authentication/ Account Verification Rejected, Issuer is rejecting
tds_authentication_result_message_version 5/String
Message Version Number. Protocol version identifier This shall be the Protocol Version Number of the specification utilised by the system creating this message. The Message Version Number is set by the 3DS Server which originates the protocol with the AReq message. The Message Version Number does not change during a 3DS transaction. Possible values are:
- 1.0.2
- 2.1.0
- 2.2.0

Sale 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
&currency=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

Sale Request with Card Recurring Payment ID Example

card_recurring_payment_id=1491927
&cvv2=123
&client_orderid=34T43R77N
&order_desc=Test Order Description
&amount=777
&currency=USD
&ipaddress=65.153.12.232
&redirect_url=http://doc.apropay.com/doc/dummy.htm
&server_callback_url=https://httpstat.us/200
&control=218d377897ce25c2ac69d99de42bc6902eb5bcd8

Sale 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.
Sale Response Parameters 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

Sale Response Example

type=async-response
&serial-number=00000000-0000-0000-0000-0000000624e8
&merchant-order-id=59e1e3ca-5d44-11e1-b3d6-002522b853b4
&paynet-order-id=94935
&end-point-id=223

Sale Request Postman Collection

Sale Request Debug

Possible transaction flow scenarios can be tested with E-Commerce test cards

endpointid or groupid input your ENDPOINTID or ENDPOINTGROUPID
client_orderid make it or use your internal invoice ID
order_desc
first_name
last_name
ssn
birthday
address1
city
state
zip_code
country
phone
cell_phone
amount ​
email
currency
card_recurring_payment_id use either RPI or card number, not both
ipaddress
site_url
credit_card_number enter the beginning of the sequence, and then "i"
card_printed_name
expire_month
expire_year
cvv2
purpose
merchant_control input your Control Key
redirect_url
redirect_success_url
redirect_fail_url
server_callback_url
merchant_data
dapi_imei

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:

Customer -> Merchant: Initiate transaction activate Merchant Merchant -> "Apropay": sale activate "Apropay" "Apropay" --> Merchant: async-response Merchant -> "Apropay": status "Apropay" --> Merchant: html deactivate "Apropay" Merchant --> Customer: urldecode(html) deactivate Merchant

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 Sale 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 parameters described in Merchant Callbacks

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.

For more information, see Merchant Callbacks

Server callback result example

status=declined
&error-message=Decline, refer to card issuer
&error-code=107
&paynet-order-id=S279G323P4T1209294
&merchant-order-id=c258d6536ababe65

Sale 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)
  • email
  • 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:

d02e67236575a8e02dea5e094f3c8f12f0db43d7

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 parameters 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
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 request 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
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
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 Actual transaction amount. This value can be changed during the transaction flow
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. 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/
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
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
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-0000005b5044
&merchant-order-id=902B4FF5
&processor-tx-id=PNTEST-159884
&paynet-order-id=159884
&status=approved
&amount=10.42
&descriptor=test-usd
&original-gate-descriptor=test 12345678 3Ds Bank
&gate-partial-reversal=enabled
&gate-partial-capture=enabled
&transaction-type=sale
&receipt-id=a5061379-6ff5-3565-a9ba-1b8a814d04f6
&name=TEST HOLDER
&cardholder-name=TEST HOLDER
&card-exp-month=1
&card-exp-year=2016
&email=john.smith@gmail.com
&last-name=Smith
&first-name=John
&processor-rrn=510321889824
&approval-code=242805
&order-stage=sale_approved
&last-four-digits=9001
&bin=520306
&card-type=MASTERCARD
&phone=12063582043
&bank-name=CITIBANK
&paynet-processing-date=2015-04-09 17:14:26 MSK
&by-request-sn=00000000-0000-0000-0000-0000005b2a8a
&card-hash-id=1493114
&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=10.42
&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

Possible transaction flow scenarios can be tested with E-Commerce test cards

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

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.

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/sale-form/ENDPOINTID - for sale 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/sale-form/group/ENDPOINTGROUPID - for sale transactions

General Payment Form Process Flow

Customer -> Merchant: Checkout activate Merchant alt sale Merchant -> "Apropay": sale-form/ENDPOINTID activate "Apropay" "Apropay" --> Merchant: status=processing note right: redirect-url deactivate "Apropay" Merchant --> Customer: Provide **redirect-url** to customer browser deactivate Merchant activate Customer loop Merchant -> "Apropay": status/ENDPOINTID activate Merchant activate "Apropay" "Apropay" --> Merchant: status=processing deactivate Merchant deactivate "Apropay" end Customer -> Customer: Input cardholder data Customer -> "Apropay": Submit form deactivate Customer activate "Apropay" "Apropay" -> "Apropay": Processing "Apropay" --> Customer: Redirect to **redirect_url** deactivate "Apropay" activate Customer Customer -> Merchant: Return to the Shop deactivate Customer activate Merchant alt status Merchant -> "Apropay": status/ENDPOINTID activate "Apropay" "Apropay" --> Merchant: Final status deactivate "Apropay" else callback "Apropay" --> Merchant: Callback with final status deactivate Merchant end

Checkout – Customer proceeds to order checkout.
Merchant initiates a transaction by sending HTTPS POST request to the specified URL. It should be /sale-form/ENDPOINTID if SMS 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 required 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
email 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
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
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 Example

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
&amount=10.42
&email=john.smith@gmail.com
&currency=USD
&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

Payment Form 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.
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
${APPLE_PAY} n/a Apple Pay buy button will be available if this macros is used
${GOOGLE_PAY} n/a Google Pay buy button will be available if this macros is used
${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
${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">&nbsp;</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
${AMOUNT} n/a Amount
${CURRENCY} n/a Currency
${DESCRIPTION} n/a Transaction description
${DATE} n/a Transaction date
${PAYNET_PROCESSING_DATE} n/a Paynet processing date
${RRN} n/a Reference Retrieval Number
${AUTH_CODE} n/a Authorization Code
${CARD_TYPE} n/a Card type
${LAST_FOUR_DIGITS} n/a Last four digits of a card

Working with predetermined data in form(cardrefid)

cardrefid additional parameter can be passed in request for v2/sale-form/ transactions. On passing this parameter, all card data input will be immutable and filled as in transaction where this cardrefid was generated. Using cardrefid requires form with macros, as described below.

Cardrefid Form Template Sample

<html>
<head>
</head>
<body>
<h3>Order #$!MERCHANT_ORDER_ID - $!ORDERDESCRIPTION</h3>
<h3>Total amount: $!AMOUNT $!CURRENCY to $!MERCHANT</h3>
<h4>Card Holder: ${CARDHOLDER} </h4>
<h4>Card Number: $!CARD_BIN ...... $!CARD_LAST4DIGITS </h4>
<h4>Exp year: $!EXPYEAR_VALUE </h4>
<h4>Exp month: $!EXPMONTH_VALUE </h4>
<form action="${ACTION}" method="post">
  <div>Cvv: <input name="${CVV2}" type="text" maxlength="4" autocomplete="off"/></div>
  $!{INTERNAL_SECTION}
  #if($!card_error)
  <div style="color: red;">$!card_error</div>
  #end
  <input name="submit" type="submit" value="Pay"/>
</form>
</body>
</html>

Cardrefid Macros

Field Name Macro Field Value Macro Description
${CARDHOLDER} n/a Cardholder name
${CARD_BIN} n/a Full card number
${CARD_LAST4DIGITS} n/a Last 4 digits of the card
${EXPMONTH_VALUE} n/a Card expiry month value
${EXPYEAR_VALUE} n/a Card expiry year value
${CVV2} n/a CVV2 card value

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)
  • email
  • 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 Postman Collection

Payment Form Request Debug

endpointid or groupid input your ENDPOINTID or ENDPOINTGROUPID
client_orderid make it or use your internal invoice ID
order_desc
first_name
last_name
ssn
birthday
address1
city
state
zip_code
country
phone
cell_phone
amount ​
email
currency
ipaddress
site_url
purpose
merchant_control input your Control Key
redirect_url
redirect_success_url
redirect_fail_url
server_callback_url
merchant_data
cardrefid
maximum-transaction-amount
minimum-transaction-amount
merchant_form_data

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.
Status Response Parameter 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
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
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
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)
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.
* - these parameters are not defined by default. Please contact tech support to include these fields in callback

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

Order status Debug

Possible transaction flow scenarios can be tested with E-Commerce test cards

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