---
title: "Contract Create"
method: POST
path: "/api/checkout/v1/init/"
tags: ["api"]
---

# Contract Create

`POST /api/checkout/v1/init/`

An endpoint that accepts an application payload for a customer wishing to enter a buy-now-pay-later journey. The endpoint returns a redirect URL that takes the customer through a series of screens to complete the process.

## Request body

- InitiateCheckout
  - `amount` Money, required
    - `currency` 'CHF' | 'EUR' | 'GBP', required — * `CHF` - CHF * `EUR` - EUR * `GBP` - GBP
    - `amount` string, decimal, required
  - `amount_format` 'MINOR_UNIT' | 'DECIMAL', required — The format of the amount provided. `MINOR_UNIT` = amount is an integer of the minor unit of the currency. eg 1000 is 10CHF. `DECIMAL` = Decimal representation as string. e.g. "10.00" is 10CHF * `MINOR_UNIT` - MINOR_UNIT * `DECIMAL` - DECIMAL
  - `redirect_urls` RedirectURL, required
    - `success_url` string, uri, required — The URL to redirect to if the transaction is successful.
    - `failure_url` string, uri, required — The URL to redirect to if the transaction fails or has an error.
    - `cancel_url` union — Optionally, specify a URL to redirect to if the user cancels the transaction.
      - string, uri
      - string
  - `customer_details` ConsumerDetails
    - `email_address` union
      - string, email
      - string
    - `title` string, nullable
    - `first_name` string, nullable
    - `last_name` string, nullable
    - `date_of_birth` string, date, nullable
    - `contact_number` string, nullable
    - `company_name` string, nullable
    - `external_consumer_id` string, nullable — External consumer ID provided by the merchant
    - `nationality` 'CHE' | 'GBR' | 'ITA', nullable — Any ISO 3166-1 3-letter (alpha 3) country code. For example: * `CHE` - CHE * `GBR` - GBR * `ITA` - ITA
    - `residence_status` 'PERMIT_C' | 'PERMIT_B' | 'OTHER_RESIDENT_PERMIT' | 'null', nullable — Residence status. Must be one of PERMIT_C, PERMIT_B, OTHER_RESIDENT_PERMIT * `PERMIT_C` - PERMIT_C * `PERMIT_B` - PERMIT_B * `OTHER_RESIDENT_PERMIT` - OTHER_RESIDENT_PERMIT
    - `date_of_entry` string, date, nullable — Date of entry to residence country in format YYYY-MM-DD
    - `national_identification_number` string — National identification number for the customer if applicable.
    - `additional_data` unknown
  - `existing_contract_info` ExistingContractInfo
    - `prefill_from_existing_contract` boolean, required — Whether to prefill data from an existing contract
    - `existing_external_contract_uuid` string, uuid, required — UUID of the existing external contract to prefill from
  - `products` Product[]
    - `external_id` string, nullable
    - `sku` string, nullable
    - `name` string, nullable
    - `quantity` integer, required
    - `price` string, decimal, required — Price in decimal format (2dp)
    - `list_price` string, decimal, nullable — List Price in decimal format (2dp)
    - `image_thumbnail` string, uri
    - `image_original` string, uri
    - `additional_data` unknown
    - `allowed_terms` integer[], nullable
    - `description` string
    - `residual_value` string, decimal, nullable — Residual value of the product in decimal format (2dp), used for trade-in options. Takes precedence over any internally calculated residual value.
    - `trade_in_option_date` string, date, nullable — The date the trade-in option can be exercised, format: YYYY-MM-DD.
  - `order_reference` string — A reference number/code that is unique to this order
  - `order_description` string — High-level description of the order for the user.
  - `webhooks` Webhooks
    - `status_url` string, uri, required — The URL to call when the status changes
    - `mapping_scheme` string, required
    - `token` string, required — The webhook token to use when carrying out calls to the webhook url.
  - `billing_address` Address
    - `street_number` string — The street number on its own - strongly recommended for Swiss (CH) addresses. If address_line_1 is omitted and both street and street_number are provided, address_line_1 will be constructed as 'street_number street'.
    - `street` string — The street without the street number - strongly recommended for Swiss (CH) addresses. If address_line_1 is omitted and both street and street_number are provided, address_line_1 will be constructed as 'street_number street'.
    - `address_line_1` string — First line of address, usually including street number and name. If omitted and both street and street_number are provided, it will be constructed as 'street_number street'.
    - `apartment` string — The apartment/suite number. Often the same as address_line_2
    - `address_line_2` string, nullable — Second line of address. Apartment number / suite / building etc.
    - `zip_code` string, required — The zip/postal code for the address.
    - `city` string, required — The city/locality of the address.
    - `country_code` 'CH' | 'IT' | 'GB', required — The ISO-3166-1 2-digit country code for the user's country. For example: * `CH` - Switzerland * `IT` - Italy * `GB` - United Kingdom
    - `region_code` string — The ISO-3166-2 subdivision code for the region.
    - `region_iso3166_2` string — The ISO-3166-2 subdivision code for the region.
    - `sub_region_code` string — The ISO-3166-2 subdivision code for the subdivision within the region. Example: Provinces in Italy (IT). Not all countries have this level of subdivision.
    - `is_client_validated` boolean
    - `formatted_address` string, nullable
  - `billing_address_raw` unknown
  - `shipping_address` Address
    - `street_number` string — The street number on its own - strongly recommended for Swiss (CH) addresses. If address_line_1 is omitted and both street and street_number are provided, address_line_1 will be constructed as 'street_number street'.
    - `street` string — The street without the street number - strongly recommended for Swiss (CH) addresses. If address_line_1 is omitted and both street and street_number are provided, address_line_1 will be constructed as 'street_number street'.
    - `address_line_1` string — First line of address, usually including street number and name. If omitted and both street and street_number are provided, it will be constructed as 'street_number street'.
    - `apartment` string — The apartment/suite number. Often the same as address_line_2
    - `address_line_2` string, nullable — Second line of address. Apartment number / suite / building etc.
    - `zip_code` string, required — The zip/postal code for the address.
    - `city` string, required — The city/locality of the address.
    - `country_code` 'CH' | 'IT' | 'GB', required — The ISO-3166-1 2-digit country code for the user's country. For example: * `CH` - Switzerland * `IT` - Italy * `GB` - United Kingdom
    - `region_code` string — The ISO-3166-2 subdivision code for the region.
    - `region_iso3166_2` string — The ISO-3166-2 subdivision code for the region.
    - `sub_region_code` string — The ISO-3166-2 subdivision code for the subdivision within the region. Example: Provinces in Italy (IT). Not all countries have this level of subdivision.
    - `is_client_validated` boolean
    - `formatted_address` string, nullable
  - `shipping_address_raw` unknown
  - `client_metadata` ClientMetadata
    - `ecommerce_platform` string
    - `locale` string
  - `locale` 'en' | 'fr' | 'de' | 'it' — Deprecated. Use language instead. * `en-gb` - British English * `fr` - French * `de` - German * `it` - Italian
  - `language` 'en' | 'fr' | 'de' | 'en-gb' | 'it' — If provided, it must be in ISO 639-1. For example: * `en` - English * `fr` - French * `de` - German * `en-gb` - British English * `it` - Italian
  - `store_id` string — A reference number/code that the merchant assigns to a store
  - `store_name` string — The merchant store name, stored on the merchant user object
  - `store_number` string — The merchant store number, stored on the merchant user object
  - `additional_data` unknown
  - `allowed_terms` integer[], nullable
  - `config` unknown
  - `merchant_user_uuid` string, uuid, nullable
  - `delay_finalisation` boolean — Pass True to override the delayed finalisation setting. With delayed finalisation of the contract the merchant later confirms availability of the goods with payment captured only upon confirmation
  - `financial_product_type` 'BNPL' | 'CREDIT' — If provided, it must be BNPL or CREDIT * `BNPL` - BNPL * `CREDIT` - CREDIT
  - `pricing_structure_code` string, nullable
  - `order_discount_amount` string, decimal, nullable — Order Discount Amount in decimal format (2dp)
  - `service_start_date` string, date, nullable — For service products, this is the date the service starts format: YYYY-MM-DD.
  - `service_end_date` string, date, nullable — For service products, this is the date the service ends format: YYYY-MM-DD.
  - `bank_account_number` string — Bank account number for the customer if applicable.

## Response `201`

- InitiateCheckoutResponse — This serializer is not used to validate output from the API. It is used purely for documentation generation and mirrors the pydantic model checkout_api.types.InitiateCheckoutResponse.
  - `action` 'REDIRECT', required — * `REDIRECT` - REDIRECT
  - `redirect_url` string, uri, required — URL to redirect the user to to complete their HeidiPay checkout.
  - `application_uuid` string, uuid, required
  - `external_contract_uuid` string, uuid, required
  - `risk_status` 'credit_check_decline' | 'id_check_decline' | 'address_not_found_decline' | 'success' | 'null', nullable — Risk status of any risk tests that run before the customers enter the checkout. * `credit_check_decline` - credit_check_decline * `id_check_decline` - id_check_decline * `address_not_found_decline` - address_not_found_decline * `success` - success

## Other responses

- `400`
- `500`

---

[API](https://skmtc.net/heylight/apis/heidipay-checkout-api.md) · [All operations](https://skmtc.net/heylight/apis/heidipay-checkout-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/heylight/heidipay-checkout-api/versions/c51570cfc888/schema)