HiPay Enterprise – Intégration page de paiement hébergée et iframe V1
Live testing
Service endpoints
Environment
Endpoint
Stage
https://stage-secure-gateway.hipay-tpp.com/rest/v1/hpayment
Production
https://secure-gateway.hipay-tpp.com/rest/v1/hpayment
Authentication
All requests to the HiPay Enterprise API require identification through HTTP Basic Authentication. Your API credentials can be found in the Integration section of your HiPay Enterprise back office. Most HTTP clients (including web browsers) have built-in support for HTTP basic authentication. If not, the following header must be included in all HTTP requests.
Authorization: Basic base64("privateAPIusername:privateAPIpassword")
To find your private API username, private API password, you need to go on the HiPay back-office > Integration > Security settings.
Request parameters in POST method
(For further details, please refer to our developer portal.)
Parameter
Format
Length
Description
template
Alphabetic
32
To display the hosted payment page, set the value: basic-js To display the iframe, set the value:iframe-js
time_limit_to_pay
Numeric
-
The time limit to pay allows you to specify the validity period of a payment page in seconds, starting from the moment the payment link (forwardUrl) is generated. If empty, default value is set to 7 days. Maximum value: 24 days
css
AlphaNumeric
255
URL to the merchant's style sheet Important: HTTPS protocol is required.
language
AN
5
Set the language of the payment page. Locale code, default to en_GB – English –Great BritainE.g.: fr_FR, es_ES, etc.
merchant_display_name
AN
32
Merchant's name displayed on the payment page
display_selector
N
1
Enable/disable the payment product selector. Possible values:0 = The selector is not displayed1 = The selector is displayed
Field name
Format
Length
Description
payment_product_list
AN
255
List of payment products, separated by a “,” (e.g.: visa,mastercard,american-express)for the exhaustive list please click here
operation
A
-
Set the value:Sale = debits the customer immediatelyAuthorization = only requests authorization. You will then have to ask for the capture (debit) of the transaction.
eci
N [string]
1
Set the value:7 = e-commerce 1 = MO/TO (for call center and payment link by email)
multi_use
N
1
Set the value:0 = for one-shot payment1 = in order to re-use the token for a recurring payment
authentication_indicator
N [string]
1
Indicate if 3-D Secure authentication should be performed:0 = Bypass 3-D Secure authentication1 = 3-D Secure authentication is triggered if the card is enrolled2 = 3-D Secure authentication is mandatory
orderid
AN
32
ID of the order
description
AN
128
Short description of the order
long_description
AN
-
Additional description of the order
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", "_reporting_data_1":"my custom data 1", "_reporting_data_2":"my custom data 2", "_reporting_data_3":"my custom data 3", "_reporting_data_4":"my custom data 4", "_reporting_data_5":"my custom data 5"}
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
Field name
Format
Length
Description
email
AN
-
Customer's e-mail 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 thecustomer (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 complieswith 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
Full PHP example:
$data = array(
// Design and configuration of the payment page
"template" =>"basic-js",
"time_to_limit_to_pay" =>"",
"css" =>"",
"language" =>"fr_FR",
"merchant_display_name" =>"My company name",
"display_selector"=>"1",
// Order information
"orderid"=> "hipay-test-12345678910",
"description"=> "test product 01",
"long_description"=> "full description of test product 01",
"payment_product_list"=> "visa,mastercard,maestro,american-express",
"cardtoken"=> "daaf85868bcaee8klniazereiuop7b0ce133e88d",
"eci"=> "7",
"authentication_indicator"=> "1",
"operation"=> "authorization",
"currency"=> "EUR",
"amount"=> 100,
"shipping"=> 1,
"tax"=> 1,
"tax_rate"=> 1,
"custom_data"=>
'{
"shipping_method":"click and collect",
"first_order":"0",
"products_list": "First product, Second product",
"_reporting_data_1":"my custom data 1",
"_reporting_data_2":"my custom data 2",
"_reporting_data_3":"my custom data 3",
"_reporting_data_4":"my custom data 4",
"_reporting_data_5":"my custom data 5"
}',
"accept_url"=> "",
"decline_url"=> "",
"pending_url"=> "",
"exception_url"=> "",
"cancel_url"=> "",
// Customer information
"email"=> "jane.doe@test.com",
"phone"=> "01234567890",
"birthdate"=> "19890525",
"gender"=> "f",
"firstname"=> "Jane",
"lastname"=> "Doe",
"country"=> "FR",
"streetaddress"=> "10 rue de la facturation",
"streetaddress2"=> "",
"city"=> "Paris",
"zipcode"=> "75012",
"shipto_firstname"=> "Jane",
"shipto_lastname"=> "Doe",
"shipto_streetaddress"=> "20 rue de la livraison",
"shipto_streetaddress2"=> "",
"shipto_city"=> "Paris",
"shipto_zipcode"=> "75012",
"shipto_country"=> "FR",
"cid"=> "123456",
"ipaddr"=> "xxx.xx.xxx.xx",
// PSD2 information
"account_info"=>
"{
'customer':
{
'account_change': 20180507,
'opening_account_date': 20180507,
'password_change': 20180507,
},
'purchase':
{
'count': 2,
'card_stored_24h': 0,
'payment_attempts_24h': 0,
'payment_attempts_1y': 0
},
'payment':
{
'enrollment_date': 20180507
},
'shipping':
{
'shipping_used_date': 20180507,
'name_indicator': 1,
'suspicious_activity': 1
}
}",
"device_channel"=> 2,
"previous_auth_info"=>
"{
'transaction_reference': '987654321CBA'
}",
"merchant_risk_statement"=>
"{
'email_delivery_address': 'jane.doe@test.com',
'delivery_time_frame': 1,
'purchase_indicator': 1,
'pre_order_date': 20190925,
'reorder_indicator': 1,
'shipping_indicator': 1,
'gift_card':
{
'amount': 15,
'count': 1,
'currency': 'EUR'
}
}",
"recurring_info"=>
"{
'expiration_date': 20200318,
'frequency': 31
}"
);
