HPP – PayTheX

1. Introduction

This document describes integration procedures and WebPayments protocol usage for ecommerce merchants.
WebPayments protocol implements acquiring payments (purchases) using specific Hosted
Payment Pages.

2. Integration process

2.1 Client registration

After registration in the system is completed, Client receives the necessary data to create the signature for payment request, as follows:

Parameter	Description
KEY	Key for Client identification
PASSWORD	Password
PAYMENT_URL	URL to which the POST request must be sent for transferring to payment form

The Client must provide an URL callback (Callback) to which the notifications will be sent in case of successfully completed payments as well as the refunds and chargeback notices. In any case when the system send a request to Callback URL, it should return HTTP 200 code, otherwise the system will try to send a request again up to 5 times.

2.2 Brief description of the interaction with Payment Platform

To initiate transaction Client must prepare HTML form data according to this document and submit these fields as POST in Payer’s browser to Payment Platform URL (PAYMENT_URL).

If transaction requires 3D-Secure or any other kind of verification procedures, Client don’t need to change anything in request, as all verification processes would be managed using Hosted Payment Page on the Payment Platform’s side.

After the successful payment the Payer’s browser will be redirected to the URL, which was specified during payment request and the parameter “order” will be sent to this URL by the GET method.

3. Payment operations description

3.1 Regular payments

Following request creates SALE transaction in payment platform. It is used for authorization and capture at a time. This operation is used for immediate payments.
Payment method code CCT and parameter card_token is used for payments when sensitive card data is replaced with value called token.

Description of Input Parameters

Parameter	Description	Valid Value	Required Field
key	Key for Client identification		+
payment	Payment method code	CC – for payment cards, CCT – for card token	+
order	Order ID	String up to 30 characters	–
data	Properties of the product (price, title).	Base64-encoded data. For more information refer the Product’s properties encoding section	+
ext1	Client Parameter 1		–
ext2	Client Parameter 2		–
ext3	Client Parameter 3		–
…	…		–
ext10	Client Parameter 10. It’s possible to use up to 10 extended fields		–
lang	Localization language to be selected on the payment page by default.	en, fr, de (ISO 639-1)	–
formid	Specific payment page identifier. (In case the Client’s account has multiple payment pages configured).		–
first_name	Buyer’s first name.	John	–
last_name	Buyer’s last name.	Doe	–
address	Buyer’s street address.	123 Sample Street	–
zip	Buyer’s zip code.	12345	–
city	Buyer’s city.	New York	–
country	Buyer’s country code.	US (ISO 3166-1 alpha-2)	–
state	Buyer’s country region code (state, provice , etc.). Applied only for US, CA and AU.	TX (ISO 3166-2)	–
phone	Buyer’s phone number		–
email	Buyer’s email address		–
url	URL to which the Buyer will be redirected after the successful payment		+
error_url	Optional URL to which the Buyer will be returned after three unsuccessful purchase attempts.		–
req_token	Special attribute pointing for further tokenization	boolean, default 0 – no tokenization, 1 – enable tokenization	–
card_token	Credit card token value. Only required when payment method code = CCT.	String 64 characters	-/+
sign	Special signature to validate your request to Payment Platform	* (Appendix A)	+

3.2 Recurring Payments

Recurring payments used to create new transactions based on already stored cardholder information from previous operations.
If the Client’s account supports recurring operations, the Client will be granted with special RECURRING_URL to which the POST request with special parameters must be sent to make the direct recurring payments.

Description of Input Parameters

rc_idRecurring ID (will be received with the first payment)
+

Parameter	Description	Valid Value	Required Field
key	Key for the Client identification		+
order	Order ID	String up to 30 characters	–
amount	Product price (currency will be defined by the first payment)	Digit in form XX.XX (without leading zeroes)	+
description	Product name	String up to 5000 characters	+
rc_token	Additional parameter for further recurring (will be received with the first payment)	String 32 characters	+
ext1	Client Parameter 1		–
ext2	Client Parameter 2		–
ext3	Client Parameter 3		–
…	…		–
ext10	Client Parameter 10. It’s possible to use up to 10 extended fields		–
sign	Special signature to validate your request to Payment Platform	*** (Appendix A)	+

Response in case of successful payment:
SUCCESS
If payment was rejected:
DECLINED: <description of the reasons for refusal>
In case of an error:
ERROR: <error description>

3.3 Recurring Payments According to Schedule

Schedule-based recurring payments allow you to make payments with stored cardholder data on regular basis.
If the Client’s account supports recurring operations, the Client will be granted with special SCHEDULE_URL and DESCHEDULE_URL to which the POST request with special parameters must be sent to manage the schedule-based recurring payments.

Request Parameters:

Parameter	Description	Valid Value	Required Field
key	Key for the Client identification		+
amount	Product price (currency will be defined by the initial payment)	Number in format XX.XX (without leading zeroes)	+
description	Product name	String up to 5000 characters	+
rc_id	Recurring ID (received with the initial payment)		+
rc_token	Additional parameter for further recurring (received with the initial payment)	String 32 characters	+
initial_delay	Initial period in days before the first recurring payment to be created	Number	+
period	Period in days between further recurring payments.	Number	+
times	Total number of recurring payments. The zero value means unlimited number of recurring payments.	Number	+
sign	Special signature to validate your request to Payment Platform	**** (Appendix A)	+

Response in case of successful payment:
SUCCESS
In case of an error:
ERROR: <error description>

To remove existing recurring schedule, the POST request with the parameters listed below
should be sent to the DESCHEDULE_URL.

Request Parameters:

Parameter	Description	Valid Value	Required Field
key	Key for the Client identification		+
rc_id	Recurring ID (received with the first payment)		+
rc_token	Additional parameter for further recurring (received with the first payment)	String 32 characters	+
sign	Special signature to validate your request to Payment Platform	***** (Appendix A)	+

Response in case of successful payment:
SUCCESS
In case of an error:
ERROR: <error description>

3.4 Notification to the Callback URL (Callback)

After the successful payment but before the redirection, the system will notify the Client and will give the Client the appropriate list of parameters.
Note: Callback is not sent on unsuccessful (declined) payment.

Parameter	Description
id	System unique transaction ID
order	Order ID
status	SALE, REFUND, CHARGEBACK
rrn	Retrieval Reference Number value from the acquirer system
approval_code	Approval code value from the acquirer system
card	Card number mask (format: ХХХХХХ****ХХХХ)
description	Product description
amount	Product price
currency	Currency
name	Customers first and last name
email	Customers e-mail
country	Customers country (2-character code)
state	Customers state (2-character or 3-character code)
city	Customers city
address	Customers address
date	Transaction date
ip	Customers IP
ext1	Client Parameter 1 (if present in the request)
ext2	Client Parameter 2 (if present in the request)
ext3	Client Parameter 3 (if present in the request)
…	…
ext10	Client Parameter 10 (if present in the request)
rc_id	Recurring ID (if the system supports recurring and property ‘recurring’ was set for the product)
rc_token	Additional parameter for further recurring (if the system supports recurring and property ‘recurring’ was set for the product). Sent only on primary transactions
card_token	If the parameter req_token was enabled or card_token present, Payment Platform returns the token value
sign	Special signature, used to validate callback **(Appendix A)

4. Product’s properties encoding

The product’s information should be presented as the json encoded or serialized associated array in base64-encoding.

For each product the array should contain following properties:

Property name	Description	Valid value	Required Field
amount	Price	Number with two characters after the decimal point (N.NN)	+
currency	Currency	3-characters string (USD,EUR, etc.)	–
description	Description of the product	String up to 5000 characters Note: For non-Latincharacters support the stringshould be in UTF8 charset.	+
selected	Product, selected by default in products list	‘selected’	–
recurring	Flag to initialize the possibility of the further recurring payments	‘recurring’	–

For the simple payment form there can be only one product at one time, so the encoding should looks like in following PHP example:

base64_encode(
json_encode(
array(
    'amount' => '1.99',
    'currency' => 'USD',
    'description' => 'Description of Product',
    'recurring')
));

For the complex payment form there should be the list of products instead.
Below is the PHP example of the products list encoding:

base64_encode(
json_encode(
array(
'p1' => array('amount' => '1.99',
              'currency' => 'USD',
              'description' => 'Description of Product 1',
              'recurring'),
'p2' => array('amount' => '20.05',
              'description' => 'Description of Product 2',
              'selected') ,
'p3' => array('amount' => '35.45',
              'currency' => 'EUR',
              'description' => 'Description of Product 3')
)));

p1, p2, p3 are the identifiers of products

Example illustrates the use of the properties of ‘recurring’ on a single product, namely the identifier p1. The remaining products p2, p3 do not have this property.
The Client defines the Product ID by himself. The main requirement is only a unique identifier in the list of products.

The property ‘currency’ is not necessarily. By default the ‘USD’ is being used. The Client can specify the transaction currency by himself according to the currencies allowed and supported for his account.
The property ‘recurring’ is not necessarily and only used if the Client’s account supports the recurring operations and the Client will continue to use the recurring payments for the certain products.

The property ‘selected’ is defined to make the product already selected in the payment form when the Buyer is redirected to it.

5. Testing

For the accounts with testing mode enabled, it is possible to perform different test operations with the following payment card details:

SUCCESS payment
Card number: 4111 1111 1111 1111
Exp. Date: 01/2024
CVV2: any 3 digits.

FAILED payment
Card number: 4111 1111 1111 1111
Exp. Date: 02/2024
CVV2: any 3 digits.

SUCCESS 3DS payment:
Card number: 4111 1111 1111 1111
Exp. Date: 05/2024
CVV2: any 3 digits.

FAILED 3DS payment
Card number: 4111 1111 1111 1111
Exp. Date: 06/2024
CVV2: any 3 digits.

Appendix A

Sign is signature rule used either to validate your requests to payment platform or to validate callback from payment platform to your system. It must be md5 encoded string calculated by rules below:

* - md5(strtoupper(strrev(key) . strrev(payment) . strrev(data) . strrev(url) . strrev(PASSWORD)));

* - md5(strtoupper(strrev(key) . strrev(payment) . strrev(data) . strrev(url) . strrev(card_token) . strrev(PASSWORD))); – only if payment method code = CCT

** - md5(strtoupper(strrev(email) . PASSWORD . order . strrev(substr(card,0,6) . substr(card,-4))));

*** - md5(strtoupper(strrev(key) . strrev(amount) . strrev(description) . strrev(rc_id).strrev(rc_token) . strrev(PASSWORD)));

**** - md5(strtoupper(strrev(key) . strrev(amount) . strrev(description) . strrev(rc_id) . strrev(rc_token) . strrev(initial_delay) . strrev(period) . strrev(times) . strrev(PASSWORD)));

***** - md5(strtoupper(strrev(key) . strrev(rc_id) . strrev(rc_token) . strrev(PASSWORD)));

Appendix B

Example of sending request to Payment Platform

The POST method is used to transmit the parameters. Below are the examples of forms shown to a Buyer at the Client’s site for the Buyer’s transition to a payment form.
To demonstrate the structure and the creation of a simple form, in the following example we will sell some clothing items, such as a jacket.

<form action="https://someprocessing.com?a=auth" method="POST">
    <input type="hidden" name="key" value="client key">
    <input type="hidden" name="payment" value="CC">
    <input type="hidden" name="order" value="client order ID">
    <input type="hidden" name="data" value="eyJhbW91bnQiOiI0OS45NSIsImRlc2NyaXB0aW9uIjoiQmxhY2sgSmFja2V0In0=">
    <input type="hidden" name="ext1" value="client value 1">
    <input type="hidden" name="ext2" value="client value 2">
    <input type="hidden" name="ext3" value="client value 3">
    <input type="hidden" name="ext4" value="client value 4">
    <input type="hidden" name="url" value="https://site.com/success.html">
    <input type="hidden" name="sign" value="signature">
    <input type="submit" value="Pay!">
</form>

In case of submitting this form, the Customer will be redirected to a payment form, which will be already filled in with the product name, price, etc. In our case it will be Black Jacket for $49.95.

To demonstrate the complex form which allows the Client to handle the multiple products,
we will sell, for example:
– Jacket
– Shirt
– Pants

Before the creation of the form the Client has to make the list of products which will be displayed in the dropdown list. To do this the Client needs:
– to define products IDs;
– set prices;
– specify the name of each product (in this example the description includes the price) which will be displayed to the Buyer;
– perform encoding.

Below is the method of encoding the list of products:

base64_encode(
json_encode(
array(
    'owJCT' => array('amount' => '49.95','description' => 'Jacket - $49.95'),
    'owSHT' => array('amount' => '20.05','description' => 'Shirt - $20.05','selected'),
    'owPNS' => array('amount' => '70.50','description' => 'Pants - $70.50')
)
)
);

As a result we get the encoded list of products:

eyJvd0pDVCI6eyJhbW91bnQiOiI0OS45NSIsImRlc2NyaXB0aW9uIjoiSmFja2V0IC0gJDQ5 Ljk1In0sIm93U0hUIjp7ImFtb3VudCI6IjIwLjA1IiwiZGVzY3JpcHRpb24iOiJTaGlydCAtICQyM C4wNSIsIjAiOiJzZWxlY3RlZCJ9LCJvd1BOUyI6eyJhbW91bnQiOiI3MC41MCIsImRlc2Nya XB0aW9uIjoiUGFudHMgLSAkNzAuNTAifX0=

Below is precisely this encoded list that is necessary to determine the data parameter when forming the request form

<form action="https://someprocessing.com?a=auth" method="POST">
    <input type="hidden" name="key" value="client key">
    <input type="hidden" name="payment" value="CC">
    <input type="hidden" name="order" value="client order ID">
    <input type="hidden" name="data" value="eyJvd0pDVCI6eyJhbW91bnQiOiI0OS45NSIsImRlc2NyaXB0aW9uIjoiSmFja2V0IC0gJDQ5Ljk1In0sIm93U0hUIjp7ImFtb3VudCI6IjIwLjA1IiwiZGVzY3JpcHRpb24iOiJTaGlydCAtICQyMC4wNSIsIjAiOiJzZWxlY3RlZCJ9LCJvd1BOUyI6eyJhbW91bnQiOiI3MC41MCIsImRlc2NyaXB0aW9uIjoiUGFudHMgLSAkNzAuNTAifX0=">
    <input type="hidden" name="ext1" value="client value 1">
    <input type="hidden" name="ext2" value="client value 2">
    <input type="hidden" name="ext3" value="client value 3">
    <input type="hidden" name="ext4" value="client value 4">
    <input type="hidden" name="url" value="https://site.com/success.html">
    <input type="hidden" name="sign" value="signature">
    <input type="submit" value="Pay!">
</form>

After successful payment the Callback URL will receive “description” which contains the name of the selected product. In our example when selecting ‘Shirt’ the form will show the following description: ‘Shirt – $20.05’ and the corresponding pid will be ‘owSHT’.