---
title: "Creates a HelcimPay.js Checkout Session"
method: POST
path: "/helcim-pay/initialize"
tags: ["Helcim Pay"]
---

# Creates a HelcimPay.js Checkout Session

`POST /helcim-pay/initialize`

## Headers

- `api-token` string, required

## Request body

- HelcimPayInitializeRequest
  - `paymentType` string, required — Payment Type. Valid payment types are purchase | preauth | verify
  - `amount` number, required — The amount of the transaction to be processed.
  - `currency` string, required — Currency abbreviation. CAD | USD
  - `customerCode` string — This is the code of an existing customer in Helcim associated with this checkout.
  - `invoiceNumber` string — This is the number of an existing invoice in Helcim associated with this checkout.
  - `paymentMethod` string — This is the payment method (credit card, ACH) that customer can use to pay the amount. cc | ach | cc-ach
  - `allowPartial` number — This is used to determine whether the partial payment UI will be displayed to the customer.
  - `hasConvenienceFee` number — This is used to apply the convenience fee rate to credit card transaction should customer chooses this payment method.
  - `taxAmount` number — This is used to enable level 2 processing lower rates. The value should be the dollar amount of the tax to 2 decimal places.
  - `hideExistingPaymentDetails` number — This is used to hide the existing payment information of the customer.
  - `setAsDefaultPaymentMethod` number — This is used to set the payment method of the transaction to default for that customer.
  - `terminalId` number — This is used to process the card transaction on the specified terminal.
  - `confirmationScreen` boolean — This is used to display transaction information such as the amount paid and invoice number to the user after a successful transaction. If `true`, a confirmation screen will be displayed after a successful transaction. If `false`, no confirmation screen will be displayed.
  - `digitalWallet` string — This is used to enable digital wallets as payment methods, currently Google Pay is available. If a given digital wallet is set to `1` it will be enabled, if it is set to `0` it will not be enabled. By default, no digital wallets are enabled.
  - `displayContactFields` number — This is used to add phone and email input fields to the modal, allowing customers to provide additional billing information. Set the value to `1` to enable these fields, or `0` to keep them disabled. Note that the contact fields cannot be used in combination with a customer code. By default, display contact fields are disabled.
  - `customStyling` CustomStyling — Applies custom styling to the Helcim Pay instance.
    - `appearance` string — Specifies the appearance of Helcim Pay. * `dark` - Renders Helcim Pay in dark mode * `light` - Renders Helcim Pay in light mode * `system` - Renders Helcim Pay based on the client's system theme The default appearance is `light`.
    - `brandColor` string — A hex code which defines the brand color that Helcim Pay is rendered with. The default color is `815AF0`.
    - `cornerRadius` string — Controls how corners are rendered on Helcim Pay. * `pill` * `rectangular` * `rounded` The default corner radius is `rounded`.
    - `ctaButtonText` string — Overrides the text of the payment button. * `book` * `buy` * `checkout` * `donate` * `order` * `pay` * `subscribe` The button text will always display "Save" for verify transactions. The default button text is `pay`.
  - `customerRequest` CustomerRequest — This is used to create a new customer based on the given information.
    - `customerCode` string — The unique customer code. If blank, it will be automatically generated.
    - `contactName` string, required — The primary contact name (full name) of the customer.
    - `businessName` string — The business name of the customer. There must be either a contact name or business name present.
    - `cellPhone` string — The cell phone number of the customer.
    - `billingAddress` Address
      - `name` string, required — Contact Name or Business Name
      - `street1` string, required
      - `street2` string
      - `city` string
      - `province` string — 2 letter abbreviation of the province (AB, BC, CA). Required field if country is CAN or USA.
      - `country` string — 3-letter abbreviation of the country (CAN, USA)
      - `postalCode` string, required
      - `phone` string — 10 to 15 digits phone number.
      - `email` string
    - `shippingAddress` Address
      - `name` string, required — Contact Name or Business Name
      - `street1` string, required
      - `street2` string
      - `city` string
      - `province` string — 2 letter abbreviation of the province (AB, BC, CA). Required field if country is CAN or USA.
      - `country` string — 3-letter abbreviation of the country (CAN, USA)
      - `postalCode` string, required
      - `phone` string — 10 to 15 digits phone number.
      - `email` string
  - `invoiceRequest` InvoiceRequest — This is used to create a new invoice based on the given information.
    - `invoiceNumber` string — The unique invoice number. If blank, it will be automatically generated.
    - `tipAmount` number
    - `depositAmount` number
    - `notes` string — The content that would be displayed under comment section of the invoice.
    - `shipping` InvoiceRequestShipping
      - `amount` number, required
      - `details` string, required
      - `address` Address, required
        - `name` string, required — Contact Name or Business Name
        - `street1` string, required
        - `street2` string
        - `city` string
        - `province` string — 2 letter abbreviation of the province (AB, BC, CA). Required field if country is CAN or USA.
        - `country` string — 3-letter abbreviation of the country (CAN, USA)
        - `postalCode` string, required
        - `phone` string — 10 to 15 digits phone number.
        - `email` string
    - `pickup` InvoiceRequestPickup
      - `date` string, required — The date for the pickup.
      - `name` string — The name of the person who would pickup the item.
    - `tax` InvoiceRequestTax
      - `amount` number, required
      - `details` string, required
    - `discount` InvoiceRequestDiscount
      - `amount` number, required
      - `details` string, required
    - `lineItems` LineItem[], required — Array of invoice items.
      - `sku` string
      - `description` string, required — The description of the item or product.
      - `quantity` number, required — Quantity of the item.
      - `price` number, required — Unit price of the item.
      - `total` number, required — Total amount based on quantity and price of the item.
      - `taxAmount` number — Tax amount on the item.
      - `discountAmount` number — Discount amount on the item.

## Response `200`

Successful

- CheckoutInit200Response
  - `checkoutToken` string — The checkout token is used to initialize Helcim Pay
  - `secretToken` string — The secret token is used to validate the transaction response

## Other responses

- `default` — Failed

---

[API](https://skmtc.net/helcim/apis/the-helcim-api.md) · [All operations](https://skmtc.net/helcim/apis/the-helcim-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/helcim/the-helcim-api/versions/345052ca6578/schema)