🧾Create Charges via API

Create single-use checkouts programatically

"Charge pages" or "charges" are an extended feature of Helio Pay Links that allow you to generate unique, single-use checkout pages from the same paylinkID. You can set the price dynamically via requestAmount

Charges are optimal for mobile payment flows, deep-linking, QR codes, embedded pay buttons on simple websites like Wix, plugins to E-commerce baskets, or other custom payment flows.

Create a Charge Page via Widget

You can embed a Helio widget in any website to generate charges. When using the widget, a new tab will open, redirecting the user to the unique checkout page.

The user will only be able to pay once, and refreshing the page will not allow the user to transact again.

When creating your checkout widget, simply include "display": "new-tab" in your configuration code to enable charges. Below is an example configuration.

{
  "paylinkId": "657729a959531071881ed7c5", // Use your own paylink ID!
  "display": "new-tab",
  "theme": {
    "themeMode": "light"
  }
}

When a user selects Pay with Card, scans the QR code or connects from a mobile device, a charge page is automatically generated to offer the optimal user experience.

Refer to our Checkout Widget documentation for more information or use our Checkout Widget Builder to get started quickly.

Create a Charge via API

Pre-requisites

In order to create a Charge using the Helio API, you need to complete the following steps.

1. Create Helio Account & get API keys

• Navigate to https://app.hel.io and login by using any of the login methods.

• Navigate to the settings page and select the API tab.

• Click on Enable checkbox, this will generate Public API Key and Secret API Key for you.

• Save both securely since you won't be able to retrieve the Secret API Key again, however, you can always regenerate both (which will override the old one).

2. Create a Pay Link

• Select the Create payment button to create a Pay Link. Choose "Dynamic pricing" if you want to set the price dynamically via requestAmount

• Fill in the required details, set the price and generate the pay link.

• Note: You can also create a Pay Link via API.

• Once you have set up your Pay Link, simply grab the paymentRequestIdfrom the Pay Link URL or Widget code

paymentRequestId

• API Endpoint: https://api.hel.io/v1/charge/api-key

• HTTP Method: POST

• Required Query Parameters: ?apiKey={{Your public key here}}

• Required Headers: Authorization: Bearer {{Your API Token here}}

Example request body:

{
    "paymentRequestId": "667974dbb38d45b726751902",
    "requestAmount": "0.2"
}

• requestAmountis ONLY required if you've selected Dynamic pricing when setting up your Pay Link

Example response body:

{
    "id": "667c375be240df9843f7f4f9",
    "pageUrl": "https://app.hel.io//charge/87e3482c-669b-4c62-ab01-23239889acb4"
}

• "id" represents the id of the charge.

• "pageUrl" is the url of the charge page.

Example query:

curl --location 'https://api.hel.io/v1/charge/api-key?apiKey=<YOUR_PUBLIC_API_KEY>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_API_KEY' \
--data '{
    "paymentRequestId": "667974dbb38d45b726751902",
    "requestAmount": "0.2"
}'

From the following example replace: YOUR_PUBLIC_API_KEY, YOUR_SECRET_API_KEY, with the values you collected in the previous step.

Using additionalJSON in Your Request:

You can use the additionalJSON field within the customerDetails object to include any extra information you'd like to pass along with your payment request

Example request body:

{
  "paymentRequestId": "66c49e24701f6930ee9c77dd",
  "requestAmount": "0.01",
  "prepareRequestBody": {
    "customerDetails": {
      "additionalJSON": "[]"
    }
  }
}

Example query:

curl --location 'https://api.hel.io/v1/charge/api-key?apiKey=<YOUR_PUBLIC_API_KEY>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_API_KEY' \
--data '{
    "paymentRequestId": "667974dbb38d45b726751902",
    "requestAmount": "0.2"
    "prepareRequestBody": {
    "customerDetails": {
      "additionalJSON": "[]" # or whatever json you want here.
    }
  }
}'

Embed a chare in a Helio Checkout Widget

You can embed a charge in our Checkout Widget. A typical flow could be like this:

• A user adds items to your checkout cart.

• Your backend calculates the amount, and creates a charge for that amount

• Your frontend then embeds our Checkout Widget, with the chargeToken

See our Checkout Widget page for more details.