Step 2: Create a payment

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 HeidiPay/Pagolight 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. For more details please refer to the Contract Create API Documentation in the next section, where you can also use our code builder tool.

📘
Mandatory vs. Optional Parameters
Depending on the product and your agreement with HeidiPay or Pagolight, 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:

“amount” (object)_
- “amount” (string): order value
- “currency” (string): currency code must be “EUR” for Italy and "CHF" for Switzerland
“amount_format”:
- 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): must be a valid email address
- “first_name” (string): customer’s first name
- “last_name”(string): customer’s last name
- “contact_number”(string): OPTIONAL. Customer’s mobile phone.
“redirect_urls” (object): customer will be redirected to these URL depending on the outcome of the application. If you do not use the webhooks functionality, please ensure that your redirect URL triggers a change in status of the order in your order tracking system / CMS.
- “success_url” (url): The URL to redirect to if the transaction is successful
- “failure_url” (url): The URL to redirect to if the transaction fails (e.g. cancelled or declined)
Product information (object): information about the products that are in the basket.
- “sku” (string): product sku number (optional)
- “name” (string): product name, that customer will also be able to see in the HeidiPay portal.
- “quantity” (integer): must be at least 1
- “price” (string): product price
- Multiple products can be added (see example request below).
shipping_address (object): OPTIONAL but if requested by your contract, you must also provide the shipping address.
- “address_line_1” (string): enter # and street
- “zip_code” (string): 5 digits for Italy, 4 for Switzerland
- “city” (string): city name (e.g. Milano, Bern)
- “country_code”: enter “IT” or "CH"
  If you do not collect address detailed separately, you can also include everything into one line with the object “shipping_address_raw” as described in the online documentation.
Order_reference (string): OPTIONAL 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): _OPTIONAL. You can use this feature to limit the number of installment you want to offer your customer for this order. If you do not send any “allowed_terms”, the instalment options setup by default in your account will be offered to your customer when they are redirected to our page.
"allowed_terms": [3, 6, 12, 24]
pricing_structure_code (string): ONLY FOR PAGOLIGHT PRO. For Pagolight Pro orders, you also need to provide the “codice tabella” that has been enabled in your contract. For example, if you want to use a “0% interest” offer you should make sure to use the related table.
- This field should be use by adding it as “additional_data” as per below.
  "additional_data": {"pricing_structure_code": "PC6"}
- Please note that your call will be rejected if you don't provide this field in the right format for a Pagolight Pro call.
webhooks (object): 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.
- “status_url” (url): the url to which you want to receive the webhook call
- “mapping” (string): use “DEFAULT” (in capital letter), which provides you with the following order status
  - “pending”: customer is in the checkout process
  - “cancelled”: status gets to cancelled if (i) a customer has abandoned the checkout, (ii) he was inactive on the checkout for 4 hours or (iii) he was declined.
  - “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.
- “token” (string): this is your internal token to be able to identify the order or any other use (not to be confused with our authentication token which is unrelated). Here is an example of webhook payload that your system would receive if an order status has changed.
  {"token": "yourtinternaltoken", "status": "success"}

Payload & Response Example

url = "https://sbx-origination.heidipay.io/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": "21 via Corsica",
    "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.

📘Mandatory vs. Optional Parameters

Payload & Response Example

Response example:

📘
Mandatory vs. Optional Parameters