--- title: "Hpp Checkout Session Create" method: POST path: "/hpp-checkout-sessions" tags: ["Front-end Order Creation"] --- # Hpp Checkout Session Create `POST /hpp-checkout-sessions` ## Request - Base URL: `https://paella-sandbox.billie.io/api/v2` - URL: `https://paella-sandbox.billie.io/api/v2/hpp-checkout-sessions` - Auth: OAuth 2 - Password - Token URL: `/oauth/token` - TypeScript: (a function with typed inputs; its response is checked against the schema) **Purpose** Creates a session ID and redirect URL that are used to initiate a Hosted Payment Page. **Preconditions:** - All the authorization related data is present. - Accept and decline URL are present to redirect the buyer from the hosted payment page after the authorization attempt. **Success** - Response Code: `HTTP 201` - Response body: `session_id` -> Session ID for the checkout session which will be used to get the authorization detail and also confirm the checkout session. - Response body: `hpp_url` -> URL to redirect or send to buyer to access the hosted payment page. - Response body: `expires_at` -> Expiration time of the checkout session. **Attention:** - The session has an expiry time of 48 hours. ## Request body - union - HppCheckoutSessionECommerce - `channel` 'ecommerce', required - `amount` AuthorizationAmount, required: The amount object with split values for net, gross and tax - `gross` number, float, required: Value greater than 0, with max. 2 decimals. It should equal to net + tax. - `net` number, float, required: Value greater than 0, with max. 2 decimals. - `tax` number, float, required: Value greater than or equal to 0, with max. 2 decimals. - `comment` string - `duration` integer, required - `order_id` string - `delivery_address` CreateOrderAddressRequest - `addition` string - `house_number` string - `street` string, required - `city` string, required - `postal_code` string, required - `country` string, required: ISO 3166-1 alpha-2 country code (two letters: DE, AT, etc.). See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 - `organization_name` string - `billing_address` CreateOrderAddressRequest - `addition` string - `house_number` string - `street` string, required - `city` string, required - `postal_code` string, required - `country` string, required: ISO 3166-1 alpha-2 country code (two letters: DE, AT, etc.). See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 - `organization_name` string - `debtor_company` LegacyCreateOrderDebtorCompanyRequest, required - `merchant_customer_id` string, required - `name` string, required - `tax_id` string - `tax_number` string - `registration_court` string - `registration_number` string - `industry_sector` string - `subindustry_sector` string - `employees_number` string - `legal_form` string, required: One of the legal form codes available in the `GET /legal-forms` API endpoint. - `established_customer` boolean - `address_addition` string - `address_house_number` string - `address_street` string, required - `address_city` string, required - `address_postal_code` string, required - `address_country` string, required: ISO 3166-1 alpha-2 country code (two letters: DE, AT, etc.). See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 - `organisation_type` string - `debtor_person` object, required: Debtor Person desc - `email` string, required: Email address with strict formatting rules - `salutation` 'm' | 'f' - `first_name` string - `last_name` string - `phone_number` string - `line_items` CreateOrderLineItemRequest[], required - `external_id` string, required - `title` string, required - `description` string - `quantity` number, required - `category` string - `brand` string - `gtin` string - `mpn` string - `product_url` string - `image_url` string - `type` string - `quantity_unit` string - `tax_rate` number, float: Tax rate of the order line. Non-negative value. The percentage value is represented with two implicit decimals and two i.e. 1900 = 19% - `total_discount_amount` number, float: Value greater than or equal to 0, with max. 2 decimals. - `unit_price` number, float: Value greater than or equal to 0, with max. 2 decimals. - `amount` AmountDTO, required: The amount object with split values for net, gross and tax - `gross` number, float, required: Value greater than 0, with max. 2 decimals. It should equal to net + tax. - `net` number, float, required: Value greater than 0, with max. 2 decimals. - `tax` number, float, required: Value greater than or equal to 0, with max. 2 decimals. - `merchant_urls` object, required - `accept_url` string, required: Merchant URL the buyer will be redirected to after the purchase was successfully authorized. - `decline_url` string, required: Merchant URL the buyer will be redirected to after the purchase was declined. - HppCheckoutSessionTelesales - `channel` 'telesales', required - `amount` AuthorizationAmount, required: The amount object with split values for net, gross and tax - `gross` number, float, required: Value greater than 0, with max. 2 decimals. It should equal to net + tax. - `net` number, float, required: Value greater than 0, with max. 2 decimals. - `tax` number, float, required: Value greater than or equal to 0, with max. 2 decimals. - `comment` string - `duration` integer, required - `order_id` string - `delivery_address` CreateOrderAddressRequest - `addition` string - `house_number` string - `street` string, required - `city` string, required - `postal_code` string, required - `country` string, required: ISO 3166-1 alpha-2 country code (two letters: DE, AT, etc.). See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 - `organization_name` string - `billing_address` CreateOrderAddressRequest - `addition` string - `house_number` string - `street` string, required - `city` string, required - `postal_code` string, required - `country` string, required: ISO 3166-1 alpha-2 country code (two letters: DE, AT, etc.). See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 - `organization_name` string - `debtor_company` LegacyCreateOrderDebtorCompanyRequest, required - `merchant_customer_id` string, required - `name` string, required - `tax_id` string - `tax_number` string - `registration_court` string - `registration_number` string - `industry_sector` string - `subindustry_sector` string - `employees_number` string - `legal_form` string, required: One of the legal form codes available in the `GET /legal-forms` API endpoint. - `established_customer` boolean - `address_addition` string - `address_house_number` string - `address_street` string, required - `address_city` string, required - `address_postal_code` string, required - `address_country` string, required: ISO 3166-1 alpha-2 country code (two letters: DE, AT, etc.). See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 - `organisation_type` string - `debtor_person` object, required: Debtor Person desc - `email` string, required: Email address with strict formatting rules - `salutation` 'm' | 'f' - `first_name` string - `last_name` string - `phone_number` string - `line_items` CreateOrderLineItemRequest[], required - `external_id` string, required - `title` string, required - `description` string - `quantity` number, required - `category` string - `brand` string - `gtin` string - `mpn` string - `product_url` string - `image_url` string - `type` string - `quantity_unit` string - `tax_rate` number, float: Tax rate of the order line. Non-negative value. The percentage value is represented with two implicit decimals and two i.e. 1900 = 19% - `total_discount_amount` number, float: Value greater than or equal to 0, with max. 2 decimals. - `unit_price` number, float: Value greater than or equal to 0, with max. 2 decimals. - `amount` AmountDTO, required: The amount object with split values for net, gross and tax - `gross` number, float, required: Value greater than 0, with max. 2 decimals. It should equal to net + tax. - `net` number, float, required: Value greater than 0, with max. 2 decimals. - `tax` number, float, required: Value greater than or equal to 0, with max. 2 decimals. - `merchant_urls` object - `accept_url` string: Merchant URL the buyer will be redirected to after the purchase was successfully authorized. - `decline_url` string: Merchant URL the buyer will be redirected to after the purchase was declined. - HppCheckoutSessionInstore - `channel` 'instore', required - `amount` AuthorizationAmount, required: The amount object with split values for net, gross and tax - `gross` number, float, required: Value greater than 0, with max. 2 decimals. It should equal to net + tax. - `net` number, float, required: Value greater than 0, with max. 2 decimals. - `tax` number, float, required: Value greater than or equal to 0, with max. 2 decimals. - `comment` string - `duration` integer, required - `order_id` string - `delivery_address` CreateOrderAddressRequest - `addition` string - `house_number` string - `street` string, required - `city` string, required - `postal_code` string, required - `country` string, required: ISO 3166-1 alpha-2 country code (two letters: DE, AT, etc.). See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 - `organization_name` string - `billing_address` CreateOrderAddressRequest - `addition` string - `house_number` string - `street` string, required - `city` string, required - `postal_code` string, required - `country` string, required: ISO 3166-1 alpha-2 country code (two letters: DE, AT, etc.). See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 - `organization_name` string - `debtor_company` LegacyCreateOrderDebtorCompanyRequest, required - `merchant_customer_id` string, required - `name` string, required - `tax_id` string - `tax_number` string - `registration_court` string - `registration_number` string - `industry_sector` string - `subindustry_sector` string - `employees_number` string - `legal_form` string, required: One of the legal form codes available in the `GET /legal-forms` API endpoint. - `established_customer` boolean - `address_addition` string - `address_house_number` string - `address_street` string, required - `address_city` string, required - `address_postal_code` string, required - `address_country` string, required: ISO 3166-1 alpha-2 country code (two letters: DE, AT, etc.). See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 - `organisation_type` string - `debtor_person` object, required: Debtor Person desc - `email` string, required: Email address with strict formatting rules - `salutation` 'm' | 'f' - `first_name` string - `last_name` string - `phone_number` string - `line_items` CreateOrderLineItemRequest[], required - `external_id` string, required - `title` string, required - `description` string - `quantity` number, required - `category` string - `brand` string - `gtin` string - `mpn` string - `product_url` string - `image_url` string - `type` string - `quantity_unit` string - `tax_rate` number, float: Tax rate of the order line. Non-negative value. The percentage value is represented with two implicit decimals and two i.e. 1900 = 19% - `total_discount_amount` number, float: Value greater than or equal to 0, with max. 2 decimals. - `unit_price` number, float: Value greater than or equal to 0, with max. 2 decimals. - `amount` AmountDTO, required: The amount object with split values for net, gross and tax - `gross` number, float, required: Value greater than 0, with max. 2 decimals. It should equal to net + tax. - `net` number, float, required: Value greater than 0, with max. 2 decimals. - `tax` number, float, required: Value greater than or equal to 0, with max. 2 decimals. - `merchant_urls` object - `accept_url` string: Merchant URL the buyer will be redirected to after the purchase was successfully authorized. - `decline_url` string: Merchant URL the buyer will be redirected to after the purchase was declined. ## Response `201` HPP session created - object - `session_id` string, uuid, required - `expires_at` string, Y-m-d\TH:i:sP, required: Expires at datetime - `hpp_url` string, required: Hosted payment page URL ## Other responses - `400`: Invalid Request Data - `401`: Unauthorized request or invalid credentials - `500`: Unexpected Server Error ## Changes - **2026-11-03** `29d6a8a63ff9`: 1 info - endpoint added [Operation history](https://skmtc.dev/billie/apis/billie-direct-api/changes/hpp-checkout-sessions/post.md) --- [API](https://skmtc.dev/billie/apis/billie-direct-api.md) - [All operations](https://skmtc.dev/billie/apis/billie-direct-api/llms.txt) - [OpenAPI document](https://skmtc.dev/billie/apis/billie-direct-api/revisions/29d6a8a63ff9?raw)