Charges

A charge is an attempt to pay to a merchant via Beam which contains information about the payment, such as amount, currency, payment method, and status. It can come from charge sources, such as payment links or API calls.

A charge can be in one of the following states:

PENDING: The charge is being processed and the final outcome is not yet known.
SUCCEEDED: The charge has been successfully processed. A transaction will be created for this charge.
FAILED: The charge is unable to be processed. This can happen due to various reasons such as insufficient funds, card declined, etc.

You can see the API reference for charges at Charges API.

Charge Sources

Charge sources are the different sources that a charge could come from. Each charge source can support different payment scenarios based on your business needs. This value is fixed by Beam and cannot be changed by the merchant. Currently, the following charge sources are supported:

Payment Links (PAYMENT_LINK)
API (API) This is described in the next section.
Store Links (STORE_LINK)
QR PromptPay Link (QR_PROMPT_PAY_LINK)

Creating 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)

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": {
    "reditrectUrl": "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.