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

3D redirect

If your gate supports 3D Secure you need to send status request and process html return parameter to send customer to 3D 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: customer credit card number.
cvv2 3-4/String Sender: the customer’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: the credit card’s month of expiration.
expire_year 2-4/String Sender: the credit card’s year of expiration
card_printed_name 128/String Sender: card printed name.
card_recurring_payment_id Long Sender: 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/Numberic Receiver: card PAN.
destination_card_recurring_payment_id Long Receiver: recurring payment id.

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: customer’s first name.
sender_last_name 128/String Sender: customer’s last name.
sender_middle_name 128/String Sender: customer’s middle name/patronym.
sender_ssn 11/String Sender: the Social Security number is a nine-digit number in the format AAA-GG-SSSS. The last four digits of the customer’s social security number.
sender_birth_place 128/String Sender: birth place.
sender_birthday 30/String Sender: customer’s birthday.
sender_address1 256/String Sender: customer’s address.
sender_city 128/String Sender: customer’s city.
sender_state 4/String Sender: the customer’s US states (two letter abbreviation). Not applicable outside the US.
sender_zip_code 32/String Sender: zip code
sender_citizenship 128/String Sender: citizenship, гражданство.
sender_country_code 3/String Sender: the customer’s country(two letter abbreviation)
sender_phone 128/String Sender: the customer’s full international phone number, including country suffix.
sender_cell_phone 128/String Sender: the customer’s full international cell phone number, including country suffix.
sender_email 128/String Sender: the customer’s email address.
sender_resident Boolean Sender: resident, является ли резидентом.
sender_identity_document_id 128/String Sender: identity document name, идентификатор ДУДЛ.
sender_identity_document_series 12/String Sender: identity document series, серия ДУДЛ.
sender_identity_document_number 16/String Sender: identity document number, номер ДУДЛ.
sender_identity_document_issuer_name 128/String Sender: identity document issuer, кем выдан ДУДЛ.
sender_identity_document_issuer_department_code 32/String Sender: identity document issuer department code, код подразделения.
sender_identity_document_issue_date Date Sender: 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: customer’s first name.
receiver_last_name 128/String Receiver: customer’s last name.
receiver_middle_name 128/String Receiver: customer’s middle name/patronym.
receiver_birth_place 11/String Receiver: birth place, место рождения.
receiver_birthday 128/String Receiver: customer’s birthday.
receiver_address1 256/String Receiver: customer’s address.
receiver_city 128/String Receiver: customer’s city.
receiver_zip_code 32/String Receiver: zip code
receiver_region 30/String Receiver: region
receiver_area 50/String Receiver: area.
receiver_citizenship 128/String Receiver: citizenship, гражданство.
receiver_country_code 3/String Receiver: the customer’s country(two letter abbreviation)
receiver_phone 128/String Receiver: the customer’s full international phone number, including country suffix.
receiver_resident Boolean Receiver: resident, является ли резидентом.
receiver_identity_document_id 128/String Receiver: identity document name, идентификатор ДУДЛ.
receiver_identity_document_series 12/String Receiver: identity document series, серия ДУДЛ.
receiver_identity_document_number 16/String Receiver: identity document number, номер ДУДЛ.
receiver_identity_document_issuer_name 128/String Receiver: identity document issuer, кем выдан ДУДЛ.
receiver_identity_document_issuer_department_code 32/String Receiver: identity document issuer department code, код подразделения.
receiver_identity_document_issue_date Date Receiver: 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.101

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

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

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 Request V4 debug

See OAuth 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
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 V4 debug

See OAuth 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.

Payment Form Template Sample

<html>
<head>
    <script type="text/javascript">
    function isCCValid(r){var n=r.length;if(n>19||13>n)return!1;
        for(i=0,s=0,m=1,l=n;i<l;i++)d=parseInt(r.substring(l-i-1,l-i),10)*m,s+=d>=10?d%10+1:d,1==m?m++:m--;
        return s%10==0?!0:!1}
    </script>
</head>
<body>
<h3>Order #$!MERCHANT_ORDER_ID - $!ORDERDESCRIPTION</h3>
<h3>Total amount: $!AMOUNT $!CURRENCY to $!MERCHANT</h3>

<form action="${ACTION}" method="post">
    <div>Destination card number: <input id="cardnumber" name="${CARDNO}" 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>

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

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

Request authorization through control parameter

The checksum is used to ensure that it is a particular Merchant (and not a fraudster) that initiates the transaction. This SHA-1 checksum, the parameter control, is created by concatenation of the parameters values in the following order:

  • ENDPOINTID/ENDPOINTGROUPID
  • client_orderid
  • minimal monetary units amount (i.e. cent, penny etc.)
  • email
  • merchant_control

A complete string example may look as follows:

59I6email@client.com3E8E45B5-2-42D8-6ECC-FBF6B11B1

Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter (see Transfer Form Request Parameters) which is required for request authorization. For the above-mentioned example the control will take the following value:

d02e67236575a8e02dea5e094f3c8f12f0db43d7

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 Request Debug

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

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 it is XPATE (and not a fraudster) that initiates the callback for a particular Merchant. This is SHA-1 checksum of the concatenation login + client-order-id + paynet-order-id + merchant-control. See Order status API call authorization through control parameter for more details about generating control checksum. Mandatory
by-request-sn Serial number assigned to the specific request by 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.
last-four-digits Last four digits of customer credit card number.
bin Bank BIN of customer credit card number.
card-type Type of customer credit card (VISA, MASTERCARD, etc).
gate-partial-reversal Processing gate support partial reversal (enabled or disabled).
gate-partial-capture Processing gate support partial capture (enabled or disabled).
transaction-type Transaction type (sale, reversal, capture, preauth).
processor-rrn Bank Receiver Registration Number.
processor-tx-id Acquirer transaction identifier.
receipt-id Electronical 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.
card-hash-id Unique card identifier to use for loyalty programs or fraud checks.
card-country-alpha-three-code Three letter country code of source card issuer. See Card country codes for details
email Customer e-mail.
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.
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 3d Secure Status List for details
verified-rsc-status See Random Sum Check Status List for details

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
&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
&last-four-digits=1111
&bin=444455
&card-type=VISA
&phone=%2B79685787194
&bank-name=UNKNOWN
&paynet-processing-date=2015-04-14+10%3A23%3A34+MSK
&by-request-sn=00000000-0000-0000-0000-0000005b5ece
&card-hash-id=1569311
&verified-3d-status=AUTHENTICATED
&verified-rsc-status=AUTHENTICATED

Order status Debug

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.