This REST Checkout API works with similar logic to most modern payment gateways, being based on a redirect process, combined with order status webhooks.
- Customer needs to select HeyLight at your checkout as payment method and be redirected to an URL that we provide you as a response to the endpoint Contract Create API.
- The redirect URL takes the customer through a series of screens to complete the process. Once the customer has been accepted, declined or they abandoned the process, they will be redirected to your website "success" URL or "failure" URL that you provide us when you call the Contract Create API.
- Should the redirect to the success or failure URL not happen, your store can nevertheless be updated of any change in application status via our webhooks. In order to trigger our webhook, you need to provide the relevant instructions (URL, internal reference (token)) when calling the Contract Create API.
You will find below some basic explanation regarding the Contract Create API call to get you started.
Mandatory vs. Optional Parameters
Depending on the product and your agreement with HeyLight, certain parameters may be optional or mandatory. The below list is indicative and your account manager can guide you on the mandatory parameters we need to receive for your account.
Request body parameters:
🔻 Mandatory parameter
| Field | Property | Information |
|---|---|---|
| amount (object) | amount (string) currency (string) | currency code must be “EUR” for Italy and "CHF" for Switzerland |
| amount_format (string) | - | MINOR_UNIT: amount is an integer of the minor unit of the currency. eg 1000 is 10EUR. DECIMAL: decimal representation as string. e.g. "10.00" is 10EUR |
| customer_details (object) | email_address (string) first_name (string) last_name (string) contact_number (string) | contact_number: customer’s mobile phone. |
| redirect_urls (object) | success_url (url) failure_url (url) | customer will be redirected to these URL depending on the outcome of the application. |
| products (object) | sku (string) name (string) quantity (integer) price (string) | Multiple products can be added. Product sku number is optional |
| shipping_address (object) | address_line_1 (string) zip_code (string) city (string) country_code (string) | “zip_code”: 5 digits for Italy, 4 for Switzerland “city”: city name (e.g. Milano, Bern) “country_code”: enter “IT” or "CH" |
| store_id (string) | - | insert "commerce" |
| language (string) | - | it must be in ISO 639-1. e.g. italian -> "it" - English -> "en" |
🔽 Optional parameter
| Field | Property | Information |
|---|---|---|
| order_reference (string) | - | Your internal order reference number, which is convenient for your internal reconciliations. It is however optional if you prefer not to provide it. |
| allowed_terms (array of integers) | - | e.g. "allowed_terms": [3, 6, 12, 24] |
| additional_data (object) | pricing_structure_code (string) | e.g. "additional_data": {"pricing_structure_code": "PC6"} |
Webhook
If you include a webhook object in your request, our system will automatically send a payload to your system with the updated status when the status changes. This feature ensures your order tracking system is always up to date, therefore we highly recommend you add this feature to your request.
| Field | Property | Information |
|---|---|---|
| webhooks | status_url (url) mappgin (string) token (string) | status_url: the url to which you want to receive the webhook call. mapping: use "DEFAULT" (in capital letter). token: This token can be generated directly by you, it is necessary to identify the order and to receive webhooks.. |
Webhook response states:
- “pending”: customer is in the checkout process
- “cancelled”: status gets to cancelled if:
- a customer has abandoned the checkout (received after 4 hours);
- he was inactive on the checkout for 4 hours;
- he was declined (received immediately)
- “awaiting_confirmation”: if you have opted for a non-synchronized warehouse setup (manual order confirmation), your order will be set to this status when the customer completes the checkout
- “success”: If you would like a personalised mapping of the status please let your relationship manager know.
Webhook response example:
{"token": "yourtinternaltoken", "status": "success"}
Payload & Response Example
- Sandbox:
https://sbx-origination.heidipay.io - Production:
https://origination.heidipay.com - Path:
/api/checkout/v1/init/
headers = {
"accept": "application/json",
"content-type": "application/json",
"authorization": "Bearer 570d2a78ce0cb4e43856badbd47f0c21345fcebb"
}
{
"amount": {
"currency": "EUR",
"amount": "1050"
},
"redirect_urls": {
"success_url": "<https://yourmerchantsuccessurl.com>",
"failure_url": "<https://yourmerchantfailureurl.com>"
},
"customer_details": {
"email_address": "[email protected]",
"first_name": "Jane",
"last_name": "Doe",
"contact_number": "3399951301"
},
"products": [
{
"sku": "xyz12345",
"name": "TV box 1",
"price": "1000",
"quantity": 1
},
{
"sku": "xyz12346",
"name": "InsuranceTV",
"quantity": 1,
"price": "50"
}
],
"webhooks": {
"mapping_scheme": "DEFAULT",
"status_url": "<https://yourmerchantstatusurl.com>",
"token": "yourtinternaltoken"
},
"shipping_address": {
"address_line_1": "via Corsica 24",
"zip_code": "16128",
"city": "Genova",
"country_code": "IT"
},
"store_id": "ecommerce",
"allowed_terms": [3,6,12],
"amount_format": "DECIMAL",
"order_reference": "xyz1234",
"language": "it"
}
Response example:
{
"action": "REDIRECT",
"redirect_url": "https://sandbox-checkout.heidipay.com?otc=a71e69ef-3982-4474-896b-f8a89f65313b&fallback=https%3A%2F%2Fyourmerchantfailureurl.com",
"external_contract_uuid": "70b7ba0a-a569-456d-ba5f-24200287c1ce"
}
The external contract UUID is the unique ID of the contract that is also use for other purpose including refunds or calling for application status.