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 nameDo 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 issuedThis 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-3Then, 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, Secondproduct, 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 = maleF = 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 customerThis 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
