Skip to main content
Français Italiano Português

HiPay Enterprise – Recurring payments through the Hosted Page/iFrame

1. Generating the Hosted Page/iFrame

First, display a checkbox asking customers if they want to save their card to later trigger the installment(s) for a recurring payment.

Please refer to this article to generate the hosted payment page.

Please specify the following values:

 Field name Value
 orderid Order ID example for the 1st installment:
MYTESTORDER001-installment-1-of-3
 eci For an e-commerce transaction, set the value:
7
 multi_use In order to enable the “one-click” or recurring payment mode, set the value:
1


2. Saving the card token in your database

In the API response and server-to-server notification, you will receive the card information, including the card token. You should save the following data in your database:

Field name (in HTTP POST) Description
 payment_product

Payment product used to complete the transaction

(e.g.: cb, bcmc, paypal)
 payment_method[token] Card token
 payment_method[brand] Card brand (e.g.: VISA, MASTERCARD, AMERICAN EXPRESS, MAESTRO)
 payment_method[pan] Card number (up to 19 characters)
Please note that, due to PCI DSS security standards, our system has to mask credit card numbers in any output (e.g.: 549619**4769).
 payment_method[card_holder] Cardholder’s name
 payment_method[card_expiry_month] Card expiry month (2 digits)
 payment_method[card_expiry_year] Card expiry year (4 digits)
 payment_method[issuer] Card issuing bank name
Do not rely on this value to remain static over time. Bank names may change due to acquisitions and mergers.
 payment_method[country] Bank country code where the card was issued
This two-letter country code complies with ISO 3166-1 (alpha 2).

 

3. Triggering payment for the installment(s)

For the next installment(s), you will have to use the WS “order” method, with the parameters below.

You should check the expiration date before triggering additional orders to avoid declined transactions. Please also inform your client each time you submit a new order.

Service endpoints

Environment Endpoint

Stage

 https://stage-secure-gateway.hipay-tpp.com/rest/v1/order

Production

 https://secure-gateway.hipay-tpp.com/rest/v1/order

 

Request parameters

Format abbreviation Description
AN Alphanumeric characters (a-z, A-Z, 0-9)
A Alphabetic characters only (a-z, A-Z)
N Numeric characters only
R Decimal number with explicit decimal point, signed
JSON JavaScript Object Notation


Payment settings

 Field name  Format  Length  Description
 orderid AN 32 Order ID example for the 2nd installment:
MYTESTORDER001-installment-2-of-3

Then, for the 3rd and last installment, send a new request with a different order ID:
MYTESTORDER001-installment-3-of-3
 operation A - Set the value:
Sale = debits the customer immediately
 eci N [string] 1 Set the value:
9 
 description AN 128 Short description of the order
 long_description AN -  Additional description of the order
 payment_product AN 255 Please check the list of alternative payment methods
 cardtoken AN - This parameter is specific to credit or debit card payments.
 currency A 3 Base currency for the order (default to EUR)
This three-character currency code complies with ISO 4217.
 amount R - Order total amount
 shipping R - Shipping fees for the order (default to zero)
Can be omitted if the shipping fees value is zero.
 tax R - Tax amount for the order (default to zero)
Can be omitted if the tax amount value is zero.
 tax_rate R - Tax rate for the order
 custom_data JSON - You can use this parameter to submit custom values you wish to show in HiPay’s back office transaction details, to receive back in the API response messages and in the notifications or to activate specific anti-fraud rules.

E.g.:
custom_data => {
"shipping_method":"click and collect",
"first_order":"0",
"products_list":"First product, Second
product, Third product"}

 

Customer information

Field name Format Length Description
email AN - Customer’s email address
phone AN
 - Customer’s phone number
birthdate N 8 Customer’s birthdate (YYYYMMDD)
For fraud detection purposes
gender A 1

Gender of the customer:

M = male
F = female
firstname AN
 - Customer’s first name
lastname AN - Customer’s last name
streetaddress AN - Customer’s street address
streetaddress2 AN -

Additional address information of the customer

(e.g.: building, floor, flat, etc.)
city AN - Customer’s city
state AN - State of the country
zipcode AN - Zip or postal code of the customer
country A 2 Country code of the customer
This two-letter country code complies with ISO 3166-1 (alpha 2).
shipto_firstname AN - First name of the order’s recipient
shipto_lastname AN - Last name of the order’s recipient
shipto_streetaddress AN - Street address where the order is to be shipped
shipto_streetaddress2 AN - Additional information about the street address where the order is to be shipped (e.g.: building, floor, flat, etc.)
shipto_city AN - City where the order is to be shipped
shipto_state AN - State where the order is to be shipped
shipto_zipcode AN - Zip or postal code where the order is to be shipped
shipto_country A 2

Country code where the order is to be shipped

This two-letter country code complies with ISO 3166-1 (alpha 2).
ipaddr AN - Customer’s IP address
cid AN - Unique customer ID
accept_url AN - URL to redirect your customers to once the payment process is completed successfully
decline_url AN - URL to redirect your customers to after the acquirer has declined the payment
pending_url AN - URL to redirect your customers to when the payment request has been submitted to the acquirer, but the response is not available yet
exception_url AN - URL to redirect your customers to after a system failure
cancel_url AN - URL to redirect your customers to when they decide to abort the payment

 

Related articles