Aller au contenu principal
English (US) Italiano Português

HiPay Enterprise - Hosted Fields with JavaScript SDK and /order API

 

 

1.1. Implement the JavaScript SDK

First of all, please implement the SDK thanks to our technical documentation on our Developer Portal: 
https://developer.hipay.com/online-payments/sdk-reference/sdk-js

 

1.2. Testing

 

 1.3. Request tokenization

Parameter Description
cardHolder
string required 		Cardholder’s name as it appears on the card
cardNumber
string required 		Card number, with a 12- to 19-digit length
expiryMonth
string required 		Card expiry month, expressed with two digits (e.g.: 01)
expiryYear
string required 		Card expiry year, expressed with two digits (e.g.: 22)
cvc
string 		3- or 4-digit security code (called CVC2, CVV2 or CID depending on the card brand) as it appears on the credit card
multiUse
boolean optional

Indicates if the token should be generated either for a single use or for multiple uses.

While a single-use token is typically generated for a short time and for processing a single transaction, multi-use tokens are generally generated for recurring payments.

 

 1.4. Retrieve the content of the response

JavaScript response example:


{
  "payment_product": "cb",
  "token": "239495508d3713cb8a0d922b4c9f74599ce69e2334a2b03e33f484d546f71e8b",
  "request_id": "0",
  "card_id": "33e3ffbb-f69c-4f51-ba40-e87e8acc961b",
  "brand": "VISA",
  "pan": "448412xxxxxx0029",
  "card_holder": "JANE DOE",
  "card_expiry_month": "05",
  "card_expiry_year": "2024",
  "issuer": "BNP PARIBAS",
  "country": "FR",
  "domestic_network": "cb",
  "card_type": "CREDIT",
  "card_category": "PURCHASING",
  "forbidden_issuer_country": false,
  "device_fingerprint": "0400bpNfiPCR/AUNf94lis1ztjVPc4aVJjdvxbs2jtGe81iMFUQHuwibxBN/jJc8xXFuX6PmKF7D9w6UwTLJQ/raBded+trm4ecPHI1bKbfTyUEwirLZnDqLzknbtw2dg9JBTIBnmyVMxomEZzeUM33gBlH2zrOhrBPTQ3Xefa+YB7KRCB2VV4OJ3Eoc3pqKHd8qCjlU0y9oNd+sjcxpJiuDOyEioquMr6B3IAVTA3TmFfNzJxGFLwTACkxFXRiZcQcAnPGnG3CqgLln+4KLswTyWhDAstLN4US5V97h50/5jKu271aBAnRe9SUpqJ1nuRYRQc9qwfu0FPqg5dRbGWPI8GGv4RQQVRK6lU99UoH2xknMHQLoVgzcCC3wQhtdPa4apWlKzojc5zzoEwNAyYtfQUMWBwzAaBCBLs6FRDB5QLBfq3bGwE2owIzhld+C6fnxp63BxpuwNda7FIsvgR+bp9VKL1B8ftMSDVthyZXoKH4HYfwgjXnlJEJI4/wX97IAaVmZqTD7tyd0W8+tYgTFPk5uMbchLUfL6jB+ZmMavO7St0oGtrebhtvBVNTWfmYGbDHJmCY8bPeYLN93dzwz6ce8mnFiPj0ivny/m5L5d6EP5DMODtLof9iaSmLJS+gnosTzKoxVC6fSPFFgCaMpvU/h6EFXXmXEqe0ETisw5gTS90qWJpQRLA7T6v45cktLTuOKDQED3XyyPr0t8ztVFjo8eOcfWZcDCXZjVj+Jpy+I6nUOK19VzsgH1DGeSyhahZfNQgu+lmSl2pKAmu1wluCISazs9PD83/seKcOlvXrGxhKauwqEWLxUN0sYF8r08f8uCcC0xODcb+CqMKE6vVMIqD1irCDW15G2n7DMLi1MyPpjzYuuV+VhT2JQxvTdC24eZzo97tw16kQoiglK7BJDLfM/X8TvaSyxlUFCiGEdsE8OdwolivehTqT3rw1rR9l0dEJHzndNg+95/NceoRDAstLN4US59PE4fRZTRwzCQai4/k8/K5AL71+fhoVxuwLLNTE9qpzH9fOr0RSiHQAJw7JeW5ocvQUh+vx7iYJnob0nbfL59P6qjxCi4E3wOC618E1a25/ARxKjLVBzw1B7ZjXh6TBHymeHFEDQSqQFCE1XRfN+HZ21ET4rhaHYN4YbjEiJxk3o0NRac5lg3twTidneZ5Wedvp3EOKiSx6OC0ceqoTbyG/m3Zqxt3w1Bn6LxoWOnZu64rr07LwRGXZpyc7oQIV63xadNE2jqb6o3IAEdbB+xOnrC/zwRc9dcD6T1dGUjL+y2jdoT25hA43P0gknpMEieknctyemDeq66A09D3jaOoTcinCoqwdbKJytgaezfILjK9GFecOQi7xhfBnt4cNzAZ8s2cvd9SHnlPE5OMv7tk9ZNLe2qRcTG0WMOKxirZfMhUSzCWolYMrKB+CSvojDxfKmUpAl3azikZB+7cn6jrptpHWVlVRFW6/tzBN92Wy8+OwLweaBRn3D8g1ODMj2tk1bUFk1qRA=",
  "browser_info": {
    "java_enabled": false,
    "javascript_enabled": true,
    "language": "fr-FR",
    "color_depth": "24",
    "screen_height": 1080,
    "screen_width": 1920,
    "timezone": "-120",
    "http_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.142 Safari/537.36",
    "ipaddr": "",
    "http_accept": ""
  }
}

 

1.5. Save specific values in your database to make the payment

Please note: Maestro and Bancontact are not compatible with recurring and one-click payments.

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

Field name Description Format Values / Example
payment_product

Payment product used to complete the transaction

(e.g.: cb, bcmc, paypal)

Alpha (16)

cb | american-express | bcmc | paypal
token Card token. If you tokenize several times a same card you will have each time different token Alphanumeric (64) 2fdba6f38bff7bde0418752759d4ea0533aeca42babf1b2d1d9f7f6f9394e959
card_id Unique ID of the token Alphanumeric (36) 33e3ffbb-f69c-4f51-ba40-e87e8acc961b
brand Card brand  Alpha (16) VISA | MASTERCARD | MAESTRO | AMERICAN EXPRESS | CB | BCMC
pan Card number.
Please note that, due to PCI DSS security standards, our system has to mask credit card numbers in any output. 		Alphanumeric (19) 448412xxxxxx0029
card_holder Cardholder's name Alpha (-) JOHN DOE
card_expiry_month Card expiry month (2 digits) Numeric (2) 11
card_expiry_year Card expiry year (4 digits) Numeric (4) 2024
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. 		Alpha (-) BNP PARIBAS
country Bank country code where the card was issued
This two-letter country code complies with ISO 3166-1 		Alpha (2) FR
domestic_network Domestic network of the card. E.g.: "cb" for France, "bcmc" for Belgium Alpha (4) cb | bcmc
card_type Card type Alpha (6) CREDIT | DEBIT
card_category Card  category Alpha (10) PURCHASING | VIRTUAL | PREPAID

 

Then, after integrating the SDK, in order to use the token you received, you have to call the /order API within one minute. 

2.1. Requirements

Environment Endpoint

Stage

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

Production

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

Create API credentials with private visibility from the HiPay Enterprise back office > Integration > Security settings.

 

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

 

 Field name  Format  Description
 orderid AN (32) ID of the order
 operation A Set one of the following values:
Sale = debits the customer immediately
Authorization = only requests authorization. Then, you will have to ask for the capture (debit) of the transaction.
 eci N (1) [string]

Set one of the following values:

1 (for call center and payment link by email)

7 (for the first payment)
9 (for the next payments made with the same token, for one-click or recurring payment)
 authentication_indicator N (1)

If the payment product is a credit or debit card, this parameter indicates if the 3-D Secure authentication should be performed for this transaction.

0: Bypass 3-D Secure authentication.

1: 3-D Secure authentication if available.

2: 3-D Secure authentication mandatory.

For more information about the 3-D Secure workflow, check the HiPay Enterprise Overview.
 description AN (128) Short description of the order
 long_description AN Additional description of the order
 soft_descriptor AN Description of the banking operation as it will appear in the client's banking application
 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",
  "_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"
}
Field name Format 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

 

Full PHP example:


$data = array(
	// 1. Order information
	"orderid"=> "HP".rand(microtime(0),100000),
	"description"=> "produit test 01",
	"long_description"=> "produit test 01 description complète",
	"payment_product"=> "visa",
	"cardtoken"=> "09a7c8e86a77e45630a09051146d133319ba90a01f37fbd41261dd05008fcd5a",
	"eci"=> "7",
	"authentication_indicator"=> "1", // 3DS
	"operation"=> "sale",
	"currency"=> "EUR",
	"amount"=> 100,
	"shipping"=> 10,
	"tax"=> 15,
	"tax_rate"=> 15,
	"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"
	}',
	// 2. Customer information
	"email"=> "jane.doe@test.com",
	"phone"=> "01234567890",
	"birthdate"=> "19890525",
	"gender"=> "f",
	"firstname"=> "Jane",
	"lastname"=> "Doe",
	"streetaddress"=> "10 rue de la facturation",
	"streetaddress2"=> "Bâtiment A",
	"city"=> "Paris",
	"country"=> "FR",
	"zipcode"=> "75012",
	"shipto_firstname"=> "Jane",
	"shipto_lastname"=> "Doe",
	"shipto_streetaddress"=> "20 rue de la livraison",
	"shipto_streetaddress2"=> "Bâtiment B",
	"shipto_city"=> "Paris",
	"shipto_zipcode"=> "75012",
	"shipto_country"=> "FR",
	"ipaddr"=> "127.0.0.1",
	"cid"=> "123456",
	"accept_url"=> "https://example.com/accept",
	"decline_url"=> "https://example.com/decline",
	"pending_url"=> "https://example.com/pending",
	"exception_url"=> "https://example.com/exception",
	"cancel_url"=> "https://example.com/cancel",

	//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,
	"browser_info"=> "{
		'java_enabled': true,
    'javascript_enabled': true,
    'ipaddr': '127.0.0.1',
    'http_accept': '*/*',
    'http_user_agent': 'Mozilla/4.0',
    'language': 'fr',
    'color_depth': '1',
    'screen_height': 0,
    'screen_width': 0,
    'timezone': '300'
		}",
	"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
		}"
);

 

The response API is useful to redirect the customer after he paid on the right page (accept, decline, pending, exception) of your website.

JSON API response example:


{
  "state":"completed",
  "reason":"",
  "forwardUrl":"",
  "test":"true",
  "mid":"00001333332",
  "attemptId":"1",
  "authorizationCode":"test123",
  "transactionReference":"800001237474",
  "dateCreated":"2019-08-20T17:32:05+0000",
  "dateUpdated":"2019-08-20T19:32:12+0200",
  "dateAuthorized":"2019-08-20T17:32:10+0000",
  "status":"118",
  "message":"Captured",
  "authorizedAmount":"10.00",
  "capturedAmount":"10.00",
  "refundedAmount":"0.00",
  "creditedAmount":"0.00",
  "decimals":"2",
  "currency":"EUR",
  "ipAddress":"127.0.0.1",
  "ipCountry":"",
  "deviceId":"",
  "avsResult":"",
  "cvcResult":"",
  "eci":"7",
  "paymentProduct":"visa",
  "paymentMethod":
  {
    "token":"09a7c8e86a77e45630a09051146d133319ba90a01f37fbd41261dd05008fcd5a",
    "brand":"VISA",
    "pan":"411111******1111",
    "cardHolder":"TEST HIPAY",
    "cardExpiryMonth":"12",
    "cardExpiryYear":"2025",
    "issuer":"JPMORGAN CHASE BANK, N.A.",
    "country":"US"
  },
  "threeDSecure":"",
  "fraudScreening":
  {
    "scoring":"0",
    "result":"ACCEPTED",
    "review":""
  },
  "order":
  {
    "id":"HP40765",
    "dateCreated":"2019-08-20T17:32:05+0000",
    "attempts":"1",
    "amount":"10.00",
    "shipping":"1.00",
    "tax":"1.00",
    "decimals":"2",
    "currency":"EUR",
    "customerId":"123456",
    "language":"en_US",
    "email":"test@client.com"
  }
}

 

Field name Description
forwardUrl URL to redirect the customer (for Bancontact or 3DS authentication)
state Transaction state. The value must be from the following list:
- completed
- pending
- declined
- error
For further details, please refer to the Transaction workflow section.
reason 
- code 
- message

Optional element. Reason why the transaction was declined.
- code: Decline reason code
- message: Decline reason description

Possible decline reasons can be found in the Decline reasons and error codes section.

test True if the transaction is a test transaction; otherwise false
mid Your merchant account number (issued to you by HiPay Enterprise)
attempt_id Attempt ID of the payment
authorization_code Authorization code (up to 35 characters) generated for each approved or pending transaction by the acquiring provider
transaction_reference Unique identifier of the transaction
date_created Date when the transaction was created
date_updated Date when the transaction was last updated
date_authorized Date when the transaction was authorized
status Transaction status. A list of possible statuses can be found in the Transaction statuses section.
message Transaction message
authorized_amount Transaction amount
captured_amount Captured amount
refunded_amount Refunded amount
decimals Decimal precision of the transaction amount
currency Base currency for the transaction.
This three-character currency code complies with ISO 4217.
ip_address IP address of the customer making the purchase
ip_country Country code associated to the customer’s IP address
device_id Unique identifier assigned to the device (the customer’s browser) by HiPay
avs_result

Result of the Address Verification Service (AVS)

Possible AVS result codes can be found in the Address Verification Service section.

cvc_result

Result of the CVC (Card Verification Code) check

Possible CVC result codes can be found in the Card Verification Code section.

eci

Electronic Commerce Indicator (ECI)

Possible ECIs can be found in the Electronic Commerce Indicator section.

payment_product Payment product used to complete the transaction. Informs about the payment_method section type. Possible payment products can be found in the Payment products section.
payment_method For further details, please refer to the Response fields specific to the payment product section.
three_d_secure
- eci
- enrollment_status 
- enrollment_message 
- authentication_status
- authentication_message
- authentication_token
- xid 		Optional element. Result of the 3-D Secure authentication.
- 3-D Secure (3DS) Electronic Commerce Indicator
- Enrollment status
- Enrollment message
- Authentication status
- This field is only included if payment authentication was attempted and a value was received.
- Authentication message. This field is only included if payment authentication was attempted and a value was received.
- Value generated by the card issuer as a token to prove that the cardholder was successfully authenticated.
- Unique transaction identifier generated by the payment server on behalf of the merchant to identify the 3-D Secure transaction.
fraud_screening
- scoring
- result
- review 		Fraud screening result
Total score assigned to the transaction (main risk indicator)

Overall result of risk assessment returned by the payment gateway
The value must be from the following list:
- pending: rules have not been checked
- accepted: the transaction has been accepted
- blocked: the transaction has been rejected due to reviewing system rules
- challenged: the transaction has been flagged for review.

Decision made when the overall risk result returns challenged.
An empty value means that no review is required.
The value must be from the following list:
- pending: a decision to release or cancel the transaction is pending
- allowed: the transaction has been released for processing
- denied: the transaction has been cancelled
order
- Id
- dateCreated 
- attempts
- amount
- shipping
- tax
- decimals
- currency
- customer_id
- language
- email 		Information about the customer and their order:
- Unique identifier of the order as provided by the merchant
- Time when the order was created
- Indicates how many payment attempts have been made for this order
- Total order amount (e.g.: 150.00). It should be calculated as the sum of purchased items, plus shipping fees (if present) and tax (if present).
- Order shipping fees
- Order tax amount
- Decimal precision of the order amount
- Base currency for this order. This three-character currency code complies with ISO 4217.
- Unique identifier of the customer as provided by the merchant
- Language code of the customer
- Email address of the customer
operation
- type
- id
- reference
- amount
- currency
- date 		If a maintenance operation was requested and an operation_id value was sent.
- Type of last operation
- Operation ID sent in maintenance operation
- HiPay’s Operation reference
- Operation amount
- Operation currency
- Operation date

 

To consider an accepted payment, it is appropriate to rely on the server-to-server notification containing the following values:
status=118
message=Captured
and
status=119
message=Partially captured

You can receive the server-to-server notification in:
- POST "application/x-www-form-urlencoded" format
- POST XML

Server-to-server POST notification example:


state=completed
&test=true
&mid=00001333332
&attempt_id=1
&authorization_code=test123
&transaction_reference=800001237474
&date_created=2019-08-20T17%3A32%3A05%2B0000
&date_updated=2019-08-20T17%3A32%3A12%2B0000
&date_authorized=2019-08-20T17%3A32%3A10%2B0000
&status=118
&message=Captured
&authorized_amount=10.00
&captured_amount=10.00
&refunded_amount=0.00
&decimals=2
&currency=EUR
&ip_address=127.0.0.1
&ip_country=
&device_id=
&custom_data%5Bfirst_order%5D=0
&custom_data%5Bproducts_list%5D=First+product%2C+Second+product
&custom_data%5B_reporting_data_1%5D=my+custom+data+1
&custom_data%5B_reporting_data_2%5D=my+custom+data+2
&custom_data%5B_reporting_data_3%5D=my+custom+data+3
&custom_data%5B_reporting_data_4%5D=my+custom+data+4
&custom_data%5B_reporting_data_5%5D=my+custom+data+5
&custom_data%5Bshipping_method%5D=click+and+collect
&avs_result=
&cvc_result=
&eci=7
&payment_product=visa
&payment_method%5Btoken%5D=09a7c8e86a77e45630a09051146d133319ba90a01f37fbd41261dd05008fcd5a
&payment_method%5Bbrand%5D=VISA
&payment_method%5Bpan%5D=411111%2A%2A%2A%2A%2A%2A1111
&payment_method%5Bcard_holder%5D=TEST+HIPAY
&payment_method%5Bcard_expiry_month%5D=12
&payment_method%5Bcard_expiry_year%5D=2025
&payment_method%5Bissuer%5D=JPMORGAN+CHASE+BANK%2C+N.A.
&payment_method%5Bcountry%5D=U
S&fraud_screening%5Bscoring%5D=0
&fraud_screening%5Bresult%5D=accepted
&fraud_screening%5Breview%5D=
&order%5Bid%5D=HP40765
&order%5Bdate_created%5D=2019-08-20T17%3A32%3A05%2B0000
&order%5Battempts%5D=1
&order%5Bamount%5D=10.00
&order%5Bshipping%5D=1.00
&order%5Btax%5D=1.00
&order%5Bdecimals%5D=2
&order%5Bcurrency%5D=EUR
&order%5Bcustomer_id%5D=123456
&order%5Blanguage%5D=en_US
&order%5Bemail%5D=hipay%40client.com

Articles associés