1.1.7. Transfer V4

Transfer V4 Integration Data

Transfer V4 URL

The End point ID is an entry point for incoming Merchant’s transactions and is the only XPATE object which is exposed via API.

Deposit to card transactions are initiated through HTTPS POST request by using URL in the following format:
https://gate.sg.xpate.com/paynet/api/v4/transfer/ENDPOINTID – to use v4 transfer.
https://gate.sg.xpate.com/paynet/api/v4/transfer-form/ENDPOINTID – to use v4 transfer-form.
for integration purposes use staging environment sandbox.sg.xpate.com instead of production gate.sg.xpate.com

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 -> "XPATE": transfer-by-ref activate "XPATE" "XPATE" --> Merchant: async-response Merchant -> "XPATE": status "XPATE" --> Merchant: html deactivate "XPATE" Merchant --> Customer: urldecode(html) deactivate Merchant

Sender card data

Parameters below can be mandatory for specific integrations. For more information, please contact your manager in XPATE.

Money transfer request parameter Length/Type Comment
credit_card_number 19/Numeric Sender`s credit card number.
cvv2 3-4/String Sender`s CVV2 code. CVV2 (Card Verification Value) is the three of four digit number farthest to the right on the flip side of a credit card.
expire_month 2/String Sender credit card’s month of expiration.
expire_year 2-4/String Sender credit card’s year of expiration
card_printed_name 128/String Sender`s card printed name.
card_recurring_payment_id Long Sender`s recurring payment ID.

Receiver card data

Parameters below can be mandatory for specific integrations. For more information, please contact your manager in XPATE.

Money transfer request parameter Length/Type Comment
destination-card-no 19/Numeric Receiver`s card PAN.
destination_card_recurring_payment_id Long Receiver`s recurring payment ID.
destination_expire_month 2/String Receiver credit card’s month of expiration.
destination_expire_year 2-4/String Receiver credit card’s year of expiration.
destination_card_printed_name 128/String Receiver`s card printed name.

Sender customer data

Parameters below can be mandatory for specific integrations. For more information, please contact your manager in XPATE.

Money transfer request parameter Length/Type Comment
sender_first_name 128/String Sender’s first name.
sender_last_name 128/String Sender’s last name.
sender_middle_name 128/String Sender’s middle name/patronym.
sender_ssn 11/String Last four digits of the Sender’s social security number.
sender_birth_place 128/String Sender`s birth place.
sender_birthday 30/String Sender’s birthday.
sender_address1 256/String Sender’s address.
sender_city 128/String Sender’s city.
sender_state 4/String Sender’s US states (two letter abbreviation). Not applicable outside the US.
sender_zip_code 32/String Sender`s zip code
sender_citizenship 128/String Sender`s citizenship.
sender_country_code 3/String Sender’s country (two letter abbreviation).
sender_phone 128/String Sender’s full international phone number, including country suffix.
sender_cell_phone 128/String Sender’s full international cell phone number, including country suffix.
sender_email 128/String Sender’s email address.
sender_resident Boolean Is sender a resident?
sender_identity_document_id 128/String Sender`s identity document name.
sender_identity_document_series 12/String Sender`s identity document series.
sender_identity_document_number 16/String Sender`s identity document number.
sender_identity_document_issuer_name 128/String Sender`s identity document issuer.
sender_identity_document_issuer_department_code 32/String Sender`s identity document issuer department code.
sender_identity_document_issue_date Date Sender`s identity document issue date.

Receiver customer data

Parameters below can be mandatory for specific integrations. For more information, please contact your manager in XPATE.

Money transfer request parameter Length/Type Comment
receiver_first_name 128/String Receiver’s first name.
receiver_last_name 128/String Receiver’s last name.
receiver_middle_name 128/String Receiver’s middle name/patronym.
receiver_birth_place 11/String Receiver`s birth place.
receiver_birthday 128/String Receiver’s birthday.
receiver_address1 256/String Receiver’s address.
receiver_city 128/String Receiver’s city.
receiver_zip_code 32/String Receiver`s zip code
receiver_region 30/String Receiver`s region
receiver_area 50/String Receiver`s area.
receiver_citizenship 128/String Receiver`s citizenship.
receiver_country_code 3/String Receiver`s country (two letter abbreviation)
receiver_phone 128/String Receiver’s full international phone number, including country suffix.
receiver_resident Boolean Is receiver a resident?
receiver_identity_document_id 128/String Receiver`s identity document name.
receiver_identity_document_series 12/String Receiver`s identity document series.
receiver_identity_document_number 16/String Receiver`s identity document number.
receiver_identity_document_issuer_name 128/String Receiver`s identity document issuer.
receiver_identity_document_issuer_department_code 32/String Receiver`s identity document issuer department code.
receiver_identity_document_issue_date Date Receiver`s identity document issue date.

Sender anti-fraud data

Money transfer request parameter Length/Type Comment
customer_user_agent 512/String Customer User Agent Info
customer_localtime 128/String Customer Localtime
customer_screen_size 32/String Customer Screen Size.
customer_accept_language 128/String Customer browser accept language
customer_accept 128/String Customer Browser Accept Header
ipaddress 7-45/String The customer’s IP address, include for fraud screening purposes. NB: 45 is for IPv4 tunneling like 0000:0000:0000:0000:0000:0000:192.168.100.10

Mandatory fields

Parameter name Description
ipaddress The customer’s IP address, include for fraud screening purposes. NB: 45 is for IPv4 tunneling like 0000:0000:0000:0000:0000:0000:192.168.100.101
client_orderid Customer order ID.
currency Currency the transaction is charged in (three-letter currency code). Example ofВ  valid parameter values are: USD for US Dollar EUR for European Euro.
amount Amount to be transferred. 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
redirect_url 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. Optional for direct integration(non-form) deposit2card.
order_desc Order description
Parameters, which will define the type of transaction are listed below.

Additional fields for transfer V4 transactions

Note

Browser data for 3DS 2.X is gathered by XPATE system on 3DS authentication stage. For some processing channels, however, the browser data 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
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

Transfer v4 fill rules

Transaction type Parameters to send
PAN —> PAN cvv2,expire_month,expire_year,card_printed_name,credit_card_number,destination-card-no + mandatory fields
PAN —> RPI cvv2,expire_month,expire_year,card_printed_name,credit_card_number,destination_card_recurring_payment_id + mandatory fields
RPI —> PAN card_recurring_payment_id, expire_month,expire_year,card_printed_name, destination-card-no + mandatory fields
RPI —> RPI card_recurring_payment_id, expire_month,expire_year,card_printed_name, destination_card_recurring_payment_id + mandatory fields
0 —> PAN (deposit2card) destination-card-no, deposit2card = true + mandatory fields
0 —> RPI (deposit2card) destination_card_recurring_payment_id, deposit2card = true + mandatory fields

Transfer Response

Transfer 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 XPATE
merchant-order-id Merchant order id
serial-number Unique number assigned by XPATE 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

Transfer Request V4 debug

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

Debug form
URL input URL(use /v4/transfer-form/ENDPOINTID for transfer-form)
endpointid or endpointgroupid input your ENDPOINTID or ENDPOINTGROUPID
login your login should be used as Consumer Public for OAuth
destination-card-no enter the beginning of the sequence, and then "i".
destination_expire_month
destination_expire_year
destination_card_printed_name
destination_card_recurring_payment_id use either RPI or card number, not both
credit_card_number enter the beginning of the sequence, and then "i".
card_recurring_payment_id use either RPI or card number, not both
amount
currency
cvv2
card_printed_name
expire_month
expire_year
ipaddress
order_desc
redirect_url
redirect_success_url
redirect_fail_url
client_orderid
merchant_form_data
deposit2card boolean used only to determine if transaction type is deposit2card

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.

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 XPATE server and order id is returned, Merchant should poll for transaction status. When transaction is processed on XPATE 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.sg.xpate.com instead of production gate.sg.xpate.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.sg.xpate.com/paynet/api/v2/status/ENDPOINTID - for v2 status integration.
https://gate.sg.xpate.com/paynet/api/v4/status/ENDPOINTID - for v4 status integration.
The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.
https://gate.sg.xpate.com/paynet/api/v2/status/group/ENDPOINTGROUPID - for v2 status integration.
https://gate.sg.xpate.com/paynet/api/v4/status/group/ENDPOINTGROUPID - for v4 status integration.

Order status call parameters

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 XPATE Conditional
control Checksum used to ensure that status request is initiated from Merchant in Status API v2. This is SHA-1 checksum of the concatenation login + client-order-id + paynet-order-id + merchant-control. For Status API v4 this parameter is not used, request is signed used OAuth. See the Order status V4 Debug and OAuth for details. Mandatory
by-request-sn Serial number assigned to the specific request by XPATE. 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

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 XPATE
merchant-order-id Merchant order id
phone Customer phone.
serial-number Unique number assigned by XPATE server to particular request from the Merchant.
dest-last-four-digits Last four digits of customer credit card number.
dest-bin Bank BIN of customer credit card number.
dest-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.sg.xpate.com/paynet/view-receipt/ENDPOINTID/receipt-id/
cardholder-name Cardholder name.
card-exp-month Card expiration month.
card-exp-year Card expiration year.
destination-card-hash-id Unique card identifier to use for loyalty programs or fraud checks.
destination-card-country-alpha-three-code Three letter country code of destination card issuer. See Card country codes for details
email Customer e-mail.
dest-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-dst-payment-product-code Code for card set by multinational financial service. (Visa/Mastercard).
ips-dst-payment-product-name Decrypted code for card set by multinational financial service. (Visa/Mastercard).
ips-dst-payment-type-code Type of card code set by multinational financial service. (Visa/Mastercard).
ips-dst-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.

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
&processor-rrn=510458047886
&approval-code=380424
&order-stage=cancel_approved
&dest-last-four-digits=1111
&dest-bin=444455
&dest-card-type=VISA
&phone=%2B79685787194
&dest-bank-name=UNKNOWN
&paynet-processing-date=2015-04-14+10%3A23%3A34+MSK
&by-request-sn=00000000-0000-0000-0000-0000005b5ece
&destination-card-hash-id=1569311
&destination-card-country-alpha-three-code=RUS
&verified-3d-status=AUTHENTICATED
&eci=02
&ips-dst-payment-product-code=SAP
&ips-dst-payment-product-name=SAP—Platinum Mastercard® Salary– Immediate Debit
&ips-dst-payment-type-code=Debit
&ips-dst-payment-type-name=MASTERCARD Debit
&initial-amount=7.56

Order status V2 Debug

endpointid
login
client_orderid
orderid
merchant_control
by-request-sn

String to sign
Signature

Order status V4 Debug

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

Order status form
URL input URL
endpointid or groupid input your ENDPOINTID or ENDPOINTGROUPID
login
client_orderid input your Invoice Number
order_id
by-request-sn

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.

Transfer Form Integration

Transfer 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 Transfer Form integration merchant is released of accepting payment details and all this stuff is completely implemented on the XPATE gateway side. In addition merchant may customize the look and feel of the Transfer Form. Merchant must send the template to his/her Manager for approval before it could be used.

Transfer Form API URL

For integration purposes use staging environment sandbox.sg.xpate.com instead of production gate.sg.xpate.com. Transfer 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.sg.xpate.com/paynet/api/v4/transfer-form/ENDPOINTID - for transfer 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.sg.xpate.com/paynet/api/v4/transfer-form/group/ENDPOINTGROUPID - for transfer transactions

General Transfer Form Process Flow

Customer -> Merchant: Checkout activate Merchant Merchant -> "XPATE": transfer-form/ENDPOINTID activate "XPATE" "XPATE" --> Merchant: status=processing deactivate "XPATE" deactivate Merchant Customer -> Customer: Input cardholder data Customer -> "XPATE": Submit form activate "XPATE" "XPATE" -> "XPATE": Processing "XPATE" --> Customer: Redirect to **redirect_url** deactivate "XPATE" Customer -> Merchant: Return to the Shop alt status loop Merchant -> "XPATE": status/ENDPOINTID activate "XPATE" "XPATE" --> Merchant: status=processing deactivate "XPATE" end else callback ... transaction processing ... "XPATE" --> Merchant: Callback notification end

Checkout – Customer proceeds to order checkout.
Merchant initiates a transaction by sending HTTPS POST request to the specified URL. It should be v4/transfer-form/ENDPOINTID.
XPATE 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 Transfer 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 Transfer Form.
XPATE gateway processes the transaction according to 3D or Non 3D process.
When transfer authorization is completed XPATE 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 Transfer Form final redirect.

Initiating a transaction with Transfer Form

Merchant must supply the following parameters to initiate a transfer transaction using form template.

Transfer Form Request Parameters

Request parameter name Length/Type Comment Necessity*
client_orderid 128/String Merchant order identifier. Mandatory
order_desc 64k/String Brief order description Mandatory
first_name 50/String Customer’s first name Mandatory
last_name 50/String Customer’s last name Mandatory
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
address1 50/String Customer’s address line 1. Mandatory
city 50/String Customer’s city. Mandatory
state 2/String Customer’s state (two-letter state code). Please see Two-Letter Country Codes for a list of valid state codes. Mandatory for USA, Canada and Australia Conditional
zip_code 10/String Customer’s ZIP code Mandatory
country 2/String Customer’s country(two-letter country code). Please see Two-Letter Country Codes for a list of valid country codes. Mandatory
phone 15/String Customer’s full international phone number, including country code. Mandatory
cell_phone 15/String Customer’s full international cell phone number, including country code. Optional
email 50/String Customer’s email address. 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
ipaddress 20/String Customer’s IP address, included for fraud screening purposes. Mandatory
site_url 128/String URL the original transfer is made from. Optional
control 40/String Checksum generated by SHA-1. See Request authorization through control parameter for more details. Mandatory
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 XPATE 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. Mandatory if both redirect_success_url and redirect_fail_url are missing
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 XPATE 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. Mandatory if redirect_url parameter is missing
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 XPATE 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. Mandatory if redirect_url parameter is missing
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 transfer data in Merchant database. See more details at Merchant Callbacks Optional
preferred_language 2/String Customer’s two-letter language code for multi-language transfer 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 Optional
* acquirer can redefine the necessity of some fields so they become mandatory instead of optional
* leading and trailing whitespace in input parameters will be omitted

Additional fields for transfer-form V4 transactions

Note

Browser data for 3DS 2.X is gathered by XPATE system on 3DS authentication stage. For some processing channels, however, the browser data 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
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

Transfer-form v4 fill rules

Transaction type Parameters to send
form —> PAN destination-card-no + mandatory fields
form —> RPI destination_card_recurring_payment_id + mandatory fields
PAN —> form credit_card_number, cvv2,expire_month,expire_year,card_printed_name + mandatory fields
RPI —> form card_recurring_payment_id, cvv2,expire_month,expire_year,card_printed_name, + mandatory fields
form —> form mandatory fields
0 —> form(deposit2card) deposit2card = true + mandatory fields
In case of transfer-form transaction, you will receive a response with redirect_url, which contains URL of the form to fill in the remaining parameters.

Transfer Form Response

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 XPATE
merchant-order-id Merchant order id
serial-number Unique number assigned by XPATE 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 Transfer Form Process Flow

Transfer Form final redirect

Upon completion of Transfer 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 XPATE
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 XPATE (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 Transfer Form request XPATE 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

Transfer 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>

Transfer form autofill

If you want to use autofill in your transfer form, certain element attributes <id> <autocomplete> <label for> should be hardcoded in the following manner:

#if ($INPUT_SOURCE_CARD_CARDHOLDER)
<!-- Card printed name field -->
<li class="form-li">
    <label class="form-label" for="cc-name">Card printed name:</label>
    <input class="form-name-field" id="cc-name" name="${CARDHOLDER}" type="text" maxlength="50" autocomplete="cc-name" value="${CARDHOLDER_VALUE}" />
</li>
#end
#if ($INPUT_SOURCE_CARD_CVV2)
<!-- CVV field -->
<li class="form-li">
    <label class="form-label" for="${CVV2}">Card security code (CVV2/CVC2):</label>
    <input class="form-cvv-field" name="${CVV2}" id="${CVV2}" type="password" maxlength="4" autocomplete="off" />
</li>
#end
#end
#if ($INPUT_DESTINATION_CARD)
<!-- Destination Card Number field -->
#if($!DESTINATIONCARDNO)
<li class="form-li">
    <label class="form-label" for="${DESTINATIONCARDNO}">Destination card number:</label>
    <input class="form-number-field" id="${DESTINATIONCARDNO}" name="${DESTINATIONCARDNO}" type="text" maxlength="19" autocomplete="off"  />
</li>
#end
#end

Our default transfer form template supports autocomplete. In case if you want to add additional fields for autocomplete, this specification should be used for naming references.

Transfer form macros

Field Name Macro Field Value Macro Description
${CARDNO} ${CARDNOVALUE} Customer’s credit card number.
${EXPMONTH} n/a Credit card expiration month
${EXPYEAR} n/a Credit card expiration year
${CVV2} ${CVV2VALUE} Card security code 432
${CARDHOLDER} ${CARDHOLDER_VALUE} Card printed name
${MERCHANT} n/a End point display name
${SKIN_VERSION} n/a CSS skin version
${ORDERDESCRIPTION} n/a Order description
${CUSTOMER_FIRST_NAME} n/a Customer first name sent by merchant via input parameters
${CUSTOMER_LAST_NAME} n/a Customer last name sent by merchant via input parameters
${CUSTOMER_EMAIL} n/a Customer E-mail address sent by merchant via input parameters
${AMOUNT} n/a Amount
${CURRENCY} n/a Currency
${PAYNET_ORDER_ID} n/a XPATE order id
${MERCHANT_ORDER_ID} n/a Merchant order id
${refresh_interval} n/a Refresh interval recommended by system
${uuid} n/a Internal
${INTERNAL_SECTION} n/a Internal for iFrame integration
${CUSTOMER_IP_COUNTRY_ISO_CODE} n/a Customer country defined by IP Address
${PREFERRED_LANGUAGE} n/a Customer language sent by merchant via input parameters
${BROWSER_LANGUAGE} n/a Customer language defined by browser settings
${CUSTOMER_LANGUAGE} n/a Customer language sent by merchant via input parameters or defined by browser settings if first is not set
${MERCHANT_FORM_DATA} n/a Parameters sent in merchant_form_data API parameter are parsed into macros with the same name, the parameter is url-encoded, example: testparam%3Dtest1%26mynewparam%3Dtest2 and is parsed into $MFD_testparam = test1 and $MFD_mynewparam = test2 macros in the form. Parameter name characters[a-zA-Z0-9], parameter value characters[a-zA-Z0-9], control characters [=&], 2MB max size
${DESTINATION_CARD_TYPE} n/a Destination card type
${DESTINATION_LAST_FOUR_DIGITS} n/a Destination card last four digits

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 XPATE 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 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

Transfer Form Request Debug

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

Debug form
URL input URL(use /v4/transfer-form/ENDPOINTID for transfer-form)
endpointid or endpointgroupid input your ENDPOINTID or ENDPOINTGROUPID
login your login should be used as Consumer Public for OAuth
destination-card-no enter the beginning of the sequence, and then "i".
credit_card_number enter the beginning of the sequence, and then "i".
destination_card_recurring_payment_id use either RPI or card number, not both
card_recurring_payment_id use either RPI or card number, not both
amount
currency
cvv2
card_printed_name
expire_month
expire_year
ipaddress
order_desc
redirect_url
redirect_success_url
redirect_fail_url
client_orderid
merchant_form_data
deposit2card boolean used only to determine if transaction type is deposit2card

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.

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 XPATE server and order id is returned, Merchant should poll for transaction status. When transaction is processed on XPATE 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.sg.xpate.com instead of production gate.sg.xpate.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.sg.xpate.com/paynet/api/v2/status/ENDPOINTID - for v2 status integration.
https://gate.sg.xpate.com/paynet/api/v4/status/ENDPOINTID - for v4 status integration.
The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.
https://gate.sg.xpate.com/paynet/api/v2/status/group/ENDPOINTGROUPID - for v2 status integration.
https://gate.sg.xpate.com/paynet/api/v4/status/group/ENDPOINTGROUPID - for v4 status integration.

Order status call parameters

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 XPATE Conditional
control Checksum used to ensure that status request is initiated from Merchant in Status API v2. This is SHA-1 checksum of the concatenation login + client-order-id + paynet-order-id + merchant-control. For Status API v4 this parameter is not used, request is signed used OAuth. See the debug Order status V4 Debug and OAuth for details. Mandatory
by-request-sn Serial number assigned to the specific request by XPATE. 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

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 XPATE
merchant-order-id Merchant order id
phone Customer phone.
serial-number Unique number assigned by XPATE server to particular request from the Merchant.
dest-last-four-digits Last four digits of customer credit card number.
dest-bin Bank BIN of customer credit card number.
dest-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.sg.xpate.com/paynet/view-receipt/ENDPOINTID/receipt-id/
cardholder-name Cardholder name.
card-exp-month Card expiration month.
card-exp-year Card expiration year.
destination-card-hash-id Unique card identifier to use for loyalty programs or fraud checks.
destination-card-country-alpha-three-code Three letter country code of source card issuer. See Card country codes for details
email Customer e-mail.
dest-bank-name Bank name by customer card BIN.
terminal-id Acquirer terminal identifier to show in receipt.
paynet-processing-date Acquirer transaction processing date.
approval-code Bank approval code.
order-stage The current stage of the transaction processing. See Order Stage for details.
loyalty-balance The current bonuses balance of the loyalty program for current operation. if available
loyalty-message The message from the loyalty program. if available
loyalty-bonus The bonus value of the loyalty program for current operation. if available
loyalty-program The name of the loyalty program for current operation. if available
descriptor Bank identifier of the payment recipient.
original-gate-descriptor Descriptor, which is set on gate level in the system.
error-message If status in declined, error, filtered this parameter contains the reason for decline
error-code The error code is case status in declined, error, filtered.
by-request-sn Serial number from status request, if exists in request. Warning parameter amount always shows initial transaction amount, even if status is requested by-request-sn.
verified-3d-status See 3-D Secure Status List for details
eci Electronic Commerce Indicator (Visa).
ips-src-payment-product-code Code for card set by multinational financial service. (Visa/Mastercard).
ips-src-payment-product-name Decrypted code for card set by multinational financial service. (Visa/Mastercard).
ips-src-payment-type-code Type of card code set by multinational financial service. (Visa/Mastercard).
ips-src-payment-type-name Decrypted code for type of card set by multinational financial service. (Visa/Mastercard)
initial-amount Amount, set in initiating transaction, without any fees or commissions. This value can’t change during the transaction flow.

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
&processor-rrn=510458047886
&approval-code=380424
&order-stage=cancel_approved
&dest-last-four-digits=1111
&dest-bin=444455
&dest-card-type=VISA
&phone=%2B79685787194
&dest-bank-name=UNKNOWN
&paynet-processing-date=2015-04-14+10%3A23%3A34+MSK
&by-request-sn=00000000-0000-0000-0000-0000005b5ece
&destination-card-hash-id=1569311
&destination-card-country-alpha-three-code=RUS
&verified-3d-status=AUTHENTICATED
&eci=02
&ips-dst-payment-product-code=SAP
&ips-dst-payment-product-name=SAP—Platinum Mastercard® Salary– Immediate Debit
&ips-dst-payment-type-code=Debit
&ips-dst-payment-type-name=MASTERCARD Debit
&initial-amount=7.56

Order status V2 Debug

endpointid
login
client_orderid
orderid
merchant_control
by-request-sn

String to sign
Signature

Order status V4 Debug

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

Order status form
URL input URL
endpointid or groupid input your ENDPOINTID or ENDPOINTGROUPID
login
client_orderid input your Invoice Number
order_id
by-request-sn

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.