Charges API

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.

Create Charges via API

Currently, Beam supports the following payment methods for direct charges API (POST /api/v1/charges): This flow allows for a full customization of your payment experience and requires you to build your own interface for checkout.

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)
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)
Krungsri app (KRUNGSRI_APP)
SCB Easy (SCB_EASY)

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

Example Charge Creation Requests

Card Charge

POST https://api.beamcheckout.com/api/v1/charges
Content-Type: application/json
Authorization: Basic {{yourMerchantId}} {{yourApiKey}}

{
  "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"
}

QR PromptPay Charge

POST https://api.beamcheckout.com/api/v1/charges
Content-Type: application/json
Authorization: Basic {{yourMerchantId}} {{yourApiKey}}

{
  "amount": 10000,
  "currency": "THB",
  "paymentMethod": {
    "qrPromptPay": {
      "expiryTime": "2023-12-31T23:59:59Z"
    },
    "paymentMethodType": "QR_PROMPT_PAY"
  },
  "referenceId": "order_190822",
  "returnUrl": "https://www.beamcheckout.com"
}

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"
}

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

charges

Shopper wants to pay merchant for a product/service on the merchant's platform.
Merchant's client makes a request for payment to merchant's server.
Merchant's server sends a request to create a direct charge via the create charge API (POST /api/v1/charges).
Beam creates a charge with PENDING status.
Beam sends a response with the id of the created charge, indicating that a REDIRECT is required.
Merchant's server processes the request, storing the id and redirects the client to the redirectUrl provided in the redirect object.
Merchant's client display the redirected page for the shopper to continue payment process.
Shopper continues the payment process on their device.
Beam updates the charge from PENDING to SUCCEEDED. Indicating that the charge has been successfully processed.
If configured, Beam sends a charge.succeeded webhook to the merchant's server indicating that the charge has been processed successfully.
Merchant's server processes the webhook and returns an acknowledgment to Beam.

TIP
You can read more details about the webhook in the Webhook guide.

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.