Create a payment. Authentication Key Type: SalesChannelApiKey
PAYMENT API IS SCA-READY
As of September 2019, a regulation called Strong Customer Authentication (SCA) requires businesses in Europe to request additional customer authentication for online payments. Using the Preflight, Checkout fully supports SCA—including exemption logic—and ensures that you only ask customers to provide additional authentication when strictly necessary. Read more about SCA
Avoid PCI certification - use client side tokenization!
If you don’t use tokenization and instead send the card object directly, then you are required to be PCI compliant! Read more about PCI and how to become PCI compliant here. In order not to require PCI certification, please use the Tokenization API I before payment or HIPS Checkout API. Read more about Client Side Tokenization (hips.js)
What is preflight?
A preflight is a request that are beeing performed on HIPS side before the payment is executed to see if the card beeing charged is enrolled in 3D Secure.
Should the card used for the transaction be enrolled in 3D Secure, the cardholder must be redirected to the card issuer for authentication. You will see this by looking in the preflight object of the JSON response from the Payment API. Look if preflight ➔ requires_redirect is true, in that case redirect the user to preflight ➔ redirect_user_to_url for authentication.
Once the authentication process is completed, the cardholder will return to your specified hooks ➔ user_return_url_on_success or hooks ➔ user_return_url_on_fail depending of the result from the authentication.
When the user gets back to you, you should call View a payment API to get the result of the payment request.
Should the card not be enrolled in 3D secure, the JSON result will include the result of the payment request. The parameter status will be successful if the card was charged or failed if the card charge failed.
Preflight / SCA exemption
3D Secure / SCA is a mandatory authentication mechanism in Europe. However, should your environment be unable to redirect a user you can apply for an exemption from HIPS support. If approved you shall pass the parameter
preflight=falsein the payment request. Read more about SCA
Payment Statuses
| Name | Description |
|---|---|
| pending | The payment request is waiting for a preflight to be successful before it can continue with an authorization. |
| authorized | The payment is authorized (approved by bank or financial institution). The funds are reserved with the customers bank, but is not captured. You must call the Capture API when you want to capture the funds and finalize the payment request. This is normally done when the products ordered are shipped to the customer. |
| pending_capture | The payment is marked as fulfilled or a capture request has been sent, but it has not yet been captured by the system. |
| failed | Payment is declined |
| successful | Payment is authorized, and captured. And will be paid to you. |
Preflight Statuses
| Name | Description |
|---|---|
| successful | No preflight is required. |
| require_3ds | The card used is enrolled in 3D Secure and the cardholder needs to be redirected to his/her bank to finalize the authentication process. If you get this preflight status, you should redirect the customer to the URL in preflight ➔ redirect_user_to_url. The customer will return back to your platform via the URL you specilied in user_return_url_on_success or user_return_url_on_fail |
Example request with Hips card_token
curl --request POST \
--url https://api.hips.com/v2/payments \
--header 'Accept: application/json' \
--header 'Authorization: private_BQokikJOvBiI2HlWgH4olfQ2' \
--header 'Content-Type: application/json' \
--data '{
"source": "card_token",
"card_token": "73jWmRr6iGmiDN14UH6cut6g",
"purchase_currency": "USD",
"amount": 995,
"merchant_order_id": "1234",
"customer": {
"name": "John Doe",
"email": "[email protected]",
"ip_address": "37.123.187.251"
}
}'
Example with network card token
curl --request POST \
--url https://api.hips.com/v2/payments \
--header 'Accept: application/json' \
--header 'Authorization: private_BQokikJOvBiI2HlWgH4olfQ2' \
--header 'Content-Type: application/json' \
--data '{
"source": "network_token",
"network_token": {
"number": "4111111111111111",
"exp_month": "01",
"exp_year": "21",
"cryptogram": "aKsj8TgffSwWW4f1vD="
},
"merchant_order_id": "1234",
"purchase_currency": "USD",
"amount": 995,
"customer": {
"name": "John Doe",
"email": "[email protected]",
"ip_address": "37.123.187.251"
}
}'
Example request with plain text card
curl --request POST \
--url https://api.hips.com/v2/payments \
--header 'Accept: application/json' \
--header 'Authorization: private_BQokikJOvBiI2HlWgH4olfQ2' \
--header 'Content-Type: application/json' \
--data '{
"source": "card",
"card": {
"number": "4111111111111111",
"exp_month": "01",
"exp_year": "21",
"cvc": "123"
},
"merchant_order_id": "1234",
"purchase_currency": "USD",
"amount": 995,
"customer": {
"name": "John Doe",
"email": "[email protected]",
"ip_address": "37.123.187.251"
}
}'
Example of a payment request where preflight redirect is NOT required:
{
"id": "z68uoH7QZ1fizWZ3iPR6vbYE",
"object": "payment",
"source": "card",
"status": "successful",
"preflight": {
"requires_redirect": false,
"redirect_user_to_url": null,
"status": "successful"
},
"order": {
"id": "VqqG2QAiNHA7VwuVGw5GZXtj",
"merchant_reference": {
"order_id": null
}
},
"amount": 3000,
"amount_currency": "USD",
"settlement_amount": 3000,
"settlement_amount_currency": "USD",
"settlement_exchange_rate": 1,
"authorization_code": "624412",
"decline_reason": "not_declined"
}
Example of a payment request where preflight redirect IS required (in the example below the preflight indicates that 3D Secure is required and that the cardholder should be redirected to his/her bank for authentication):
{
"id": "ViCbUHPnMJyTM4YrXbDuDkHc",
"object": "payment",
"source": "card",
"status": "pending",
"preflight": {
"requires_redirect": true,
"redirect_user_to_url": "https://landings.hips.com/redirector/?preflight_id=9vrLvaEms4UCjd1R7nKpKpd9",
"status": "require_3ds"
},
"order": {
"id": "ifdkHpKK6YW3BovXFn3WVsoP",
"merchant_reference": {
"order_id": null
}
},
"amount": 3000,
"amount_currency": "USD",
"settlement_amount": 3000,
"settlement_amount_currency": "USD",
"settlement_exchange_rate": 1,
"authorization_code": null,
"decline_reason": "not_declined"
}