1.1.7. Transfer V4¶
- Transfer V4 Integration Data
- Transfer V4 URL
- 3DS redirect
- Sender card data
- Receiver card data
- Sender customer data
- Receiver customer data
- Sender anti-fraud data
- Mandatory fields
- Additional fields for transfer V4 transactions
- Transfer v4 fill rules
- Transfer Response
- Transfer Request V4 Postman Collection
- Transfer Request V4 debug
- Order status
- Transfer Form Integration
- Transfer Form API URL
- General Transfer Form Process Flow
- Initiating a transaction with Transfer Form
- Transfer Form Request Parameters
- Additional fields for transfer-form V4 transactions
- Transfer-form v4 fill rules
- Transfer Form Response
- Transfer Form final redirect
- Transfer Form Template Sample
- Wait Page Template Sample
- Finish Page Macros
- Transfer Form Request Postman Collection
- Transfer Form Request Debug
- Order status
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.
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:
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_email | 128/String | Receiver’s email address |
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 |
Additional fields for transfer V4 transactions¶
For merchants - customer browser information¶
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 |
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
|
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
Normalized parameters string to sign, according to OAuth 1.0a rules |
---|
POST body parameters to submit |
---|
OAuth 1.0a headers to submit. |
---|
HEX Encoded Signature |
---|
Base64 Encoded Signature |
---|
|
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.
See more details at Statuses
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:
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 |
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 Country Codes for details |
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 |
seller-commission | Total commission for processed transaction. This is optional parameter. Please contact your manager in XPATE, if you would like to receive it |
acquirer-commission | Acquirer commission for processed transaction. This is optional parameter. Please contact your manager in XPATE, if you would like to receive it |
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 V4 Debug¶
Enter your private key in PKCS#1 container to use debug. See RSA-SHA256 for details.
Order status form
Normalized parameters string to sign, according to OAuth 1.0a rules |
---|
POST body parameters to submit |
---|
OAuth 1.0a headers to submit. |
---|
HEX Encoded Signature |
---|
Base64 Encoded Signature |
---|
|
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.
Form Transaction by ENDPOINTGROUPID
The End point group ID is an entry point for incoming Merchant’s transactions for multi currency integration.
General Transfer Form Process Flow¶
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 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 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 |
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 | 45/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. See more details at Statuses | 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 |
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 |
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>
<div><label for="dest-number">Destination card number:</label> <input id="dest-number" name="${DESTINATIONCARDNO}" type="text" maxlength="19" autocomplete="off"/></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>
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.
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"> </span> seconds.
<form name="checkform" method="post">
<input type="hidden" name="tmp" value="$!uuid"/>
$!{INTERNAL_SECTION}
<input type="submit" value="Check" />
</form>
</body>
</html>
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
Normalized parameters string to sign, according to OAuth 1.0a rules |
---|
POST body parameters to submit |
---|
OAuth 1.0a headers to submit. |
---|
HEX Encoded Signature |
---|
Base64 Encoded Signature |
---|
|
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.
See more details at Statuses
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:
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 |
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 Country Codes for details |
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 |
seller-commission | Total commission for processed transaction. This is optional parameter. Please contact your manager in XPATE, if you would like to receive it |
acquirer-commission | Acquirer commission for processed transaction. This is optional parameter. Please contact your manager in XPATE, if you would like to receive it |
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 V4 Debug¶
Enter your private key in PKCS#1 container to use debug. See RSA-SHA256 for details.
Order status form
Normalized parameters string to sign, according to OAuth 1.0a rules |
---|
POST body parameters to submit |
---|
OAuth 1.0a headers to submit. |
---|
HEX Encoded Signature |
---|
Base64 Encoded Signature |
---|
|