Beam logo

Charges API Integration Guide

This page details how to integrate with the Beam Charges API, which allows you to fully customize the payment experience by creating charges that can be paid through various methods, including cards, QR code payments etc.

This page will take you through the steps to create a charge, handle the different responses of charge creation, and tracking the charge lifecycle. For this scenario, we will use a Postman collection provided in the Sample Postman Collection page to demonstrate the API calls.

Steps to integrate with Charges API

Pre-requisites:

  • Set up the environment variables in Postman for the Beam API, which includes Beam Playground's merchant ID and your API key.

environment-setup

  1. Create a Charge
  • When your integration needs to accept payments from customers, you can send a request to create a charge. To create a charge, send a POST request to the /api/v1/charges endpoint with the required parameters. Here is the sample provided request object to create a charge for a CARD payment method, do note that the amount is in the smallest unit of the currency (e.g., satang for THB):
{
  "amount": 300099,
  "currency": "THB",
  "paymentMethod": {
    "paymentMethodType": "CARD",
    "card": {
      "cardHolderName": "Cardholder Name",
      "expiryMonth": 12,
      "expiryYear": 30,
      "pan": "4111111111111111",
      "securityCode": "123"
    }
  },
  "referenceId": "TestReferenceId",
  "returnUrl": "https://www.beamcheckout.com"
}
  1. Handle 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.

2.1 Handling REDIRECT Action

  • If the actionRequired field is REDIRECT, you need to redirect the shopper to the URL provided in the redirect object of the response.

2.2 Handling ENCODED_IMAGE Action

  • If the actionRequired field is ENCODED_IMAGE, you need to display the QR code image to the shopper for them to scan and complete the payment. Here is an example of a charge creation response with an encoded image action:

encoded-image-action-required

2.3 Handling NONE Action

  • If the actionRequired field is NONE, the charge is successfully created and no further action is required. Do note that this does not mean that the charge has succeeded, only that it is created successfully Here is an example of a charge creation response with no action required: none-action-required
  1. Track Charge Lifecycle

  • After the charge is created, you can track the charge lifecycle by subscribing to the relevant webhooks. This can be done manually through an API call to the /api/v1/charges/{chargeId} endpoint to see the current status of the charge. get-charge

  • However, it is recommended to subscribe to the webhooks to get updates on the charge status. This can be done via the charge.succeeded webhook, which will notify you when the charge is successfully processed.

    You can find an example of setting up the webhook in the Playground section of the documentation.