Charges API

Charges API allows for a full customization of your payment experience and requires you to build your own interface for checkout.

This section will walk you through the charges API to complete your payment flow, including

Create Charge to initiate a payment
Get Charge to inquire the status of the payment
List Charges to list historical charges
Webhooks to get notified of charge status changes

You can see the API reference for charges at Charges API Specification, and a full detailed example of a charge integration guide at Charges API Integration Guide.

Sample Diagram of a Charge Flow

Here is an example diagram of a usage of the Charges API to create a charge with a client-server architecture:

charges

You can read more details about handling Charge Creation response below.

There are two ways for your server to get an update on Charge.

Polling - Your server can keep polling on GET /api/v1/charges/{chargeId} until you get a Charge with status SUCCEEDED or FAILED.
Webhook - If you have charge.succeeded webhook set up, which we recommend you do so, you will receive a webhook once Charge is succeeded.

Available payment methods

The following payment methods are supported on the Beam Charge API:

Card (CARD)
Card Installments (CARD_INSTALLMENTS)
Card Token (CARD_TOKEN)
Card Token Installments (CARD_TOKEN_INSTALLMENTS)
Card Network Token (CARD_NETWORK_TOKEN)
QR PromptPay (QR_PROMPT_PAY)
Alipay (ALIPAY)
Line Pay (LINE_PAY)
Shopee Pay (SHOPEE_PAY)
TrueMoney (TRUE_MONEY)
WeChat Pay (WECHAT_PAY)
Bangkok Bank app (BANGKOK_BANK_APP)
KPlus (KPLUS)
Make (MAKE)
Krungsri app (KRUNGSRI_APP)
SCB Easy (SCB_EASY)
SPayLater (SPAY_LATER)

Note

Available online payment methods are not the same as those supported in Bolt Intent API. This is indicated in OnlinePaymentMethodType and BoltPaymentMethodType enum respectively in the API Reference.

Note

For more details on the card token/card token installments payment method, please refer to the Card Tokenization guide.

Create a Charge via API

Here are some examples of Charge Creation Requests.

Card Charge


POST https://api.beamcheckout.com/api/v1/charges
Content-Type: application/json
Authorization: Basic {{credentials}}
 
{
  "amount": 10000,
  "currency": "THB",
  "paymentMethod": {
    "card": {
      "cardHolderName": "CARDHOLDER NAME",
      "expiryMonth": 12,
      "expiryYear": 30,
      "pan": "4111111111111111",
      "securityCode": "123"
    },
    "paymentMethodType": "CARD"
  },
  "referenceId": "order_190821",
  "returnUrl": "https://www.beamcheckout.com",
  "skip3dsFlow": false
}

If your merchant account has been set up to allow bypass 3DS authentication flow, you can set skip3dsFlow to true to skip 3DS on card payment methods (CARD, CARD_INSTALLMENTS, CARD_TOKEN, CARD_TOKEN_INSTALLMENTS).

QR PromptPay Charge


POST https://api.beamcheckout.com/api/v1/charges
Content-Type: application/json
Authorization: Basic {{credentials}}
 
{
  "amount": 10000,
  "currency": "THB",
  "paymentMethod": {
    "qrPromptPay": {
      "expiryTime": "2023-12-31T23:59:59Z"
    },
    "paymentMethodType": "QR_PROMPT_PAY"
  },
  "referenceId": "order_190822",
  "returnUrl": "https://www.beamcheckout.com",
  "skip3dsFlow": false
}

Note

The amount field is in the smallest currency unit. For example, for Thai Baht (THB), the amount is in Satang.

For more information on authentication, please refer to the Authentication guide.

Handling Charge Creation Response

Once an API call is made successfully, a charge is created. However, some charges may require additional steps to complete the payment. This is indicated in the actionRequired field of the charge creation response. There are 3 possible values for this field:

NONE: No additional action is required to complete the payment.
REDIRECT: The shopper needs to be redirected to a URL to complete. This is shown in the redirect object of the response.
ENCODED_IMAGE: The shopper needs to scan a QR code to complete the payment. This is shown in the encodedImage object of the response. The image sent is a base64 encoded string that needs to be decoded and displayed to the shopper.

Here are examples of all the possible responses for a charge creation:

No Action Required


{
  "actionRequired": "NONE",
  "chargeId": "ch_2xTsz7Qit55pahSvKfJG3UMkpFQ",
  "paymentMethodType": "CARD"
}

Redirect Required


{
  "actionRequired": "REDIRECT",
  "chargeId": "ch_2xTsz7Qit55pahSvKfJG3UMkpFQ",
  "redirect": {
    "redirectUrl": "https://www.beamcheckout.com/redirect"
  },
  "paymentMethodType": "CARD"
}

Encoded Image Required


{
  "actionRequired": "ENCODED_IMAGE",
  "chargeId": "ch_2xTsz7Qit55pahSvKfJG3UMkpFQ",
  "encodedImage": {
    "expiry": "2025-08-24T14:15:22Z",
    "imageBase64Encoded": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEAAQMAAABmvDolAAAABlBMVEX///8AAABVwtN+AAABXUlEQVR42uyYsbHzIBCEjyEgpASVQmsujVJUAiGBhv1nD5iR/VvvxY9jAwfyF91wuwuytbW19ZOgunwNNZRY4nn0L6+1gMYff/kqoUYQOPklmQMcx3SJBNRYYpGDo8pWAQ8QEDEOcE4iETgXBfpeEAgo8rg4qwNG3P5XYMijhqoH5iEdVweaQ/MAjbJK7HmRcsJrLQBA0zSoA9CtyG8tyALQXHPqk1VENBXf/7cCCAGuBWsSfVKOMwHZGuDQel0MNQAoBy0i3XJzDUCcpgETgDZY2A6y3PzBCOBaR1iTtA2qP9zPgw1A66L4a9ZFfBqlEUBmXeTeFEWQ74NaCGALojn0WDyQkzngrRWL3g4IPNTmdYH5SMJc5HkZg7IHzFvzqIu6ON8ei5YA+ptYib0eyP9zMAN0myxHN8qPvDAAjLyYgTHqolgDpk/SHxTQ4/LlFeVvA1tbWxb1LwAA//8XPln5fRCHxAAAAABJRU5ErkJggg==",
    "rawData": "Sample QR Code for payment"
  },
  "paymentMethodType": "QR_PROMPT_PAY"
}

Get Charge via API

You can use the chargeId in the charge creation response above in the Get Charge API ( GET /api/v1/charges/{chargeId}) to retrieve the details of a specific charge by its ID.

List Charges via API

You can use the List Charges API (GET /api/v1/charges) to list all charges created under your merchant account. You can also use query parameters to filter the results based on criteria such as referenceId specified upon charge creation.

Listening to Charge Webhooks

You can configure your webhook endpoint to listen to charge-related events, such as charge.succeeded by following instructions in the Webhook guide.