Beam logo

Payment Links API Integration Guide

This page details how to integrate with the Beam Payment Links API, which allows you to create payment links that direct your shoppers to a Beam-hosted checkout page.

This page will take you through the steps to create a payment link, handle the payment process, and manage the payment link lifecycle. For this scenario, we will use a Postman collection provided in the Sample Postman Collection page to demonstrate the API calls.

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 Payment Link
  • When your store needs to accept payments from customers, you can send a request to create a payment link.To create a payment link, send a POST request to the /api/v1/payment-links endpoint with the required parameters. Here is the sample provided request object for a payment link that accepts card payments, card installments, eWallets, mobile banking, and QR PromptPay:
{
  "collectDeliveryAddress": false,
  "expiresAt": "2026-06-05T04:20:04.067Z",
  "linkSettings": {
    "buyNowPayLater": {
      "isEnabled": false
    },
    "card": {
      "isEnabled": true
    },
    "cardInstallments": {
      "installments3m": {
        "isEnabled": true
      },
      "installments4m": {
        "isEnabled": true
      },
      "installments6m": {
        "isEnabled": true
      },
      "installments10m": {
        "isEnabled": true
      },
      "isEnabled": true
    },
    "eWallets": {
      "isEnabled": true
    },
    "mobileBanking": {
      "isEnabled": true
    },
    "qrPromptPay": {
      "isEnabled": true
    }
  },
  "order": {
    "currency": "THB",
    "description": "Pets Shop",
    "internalNote": "string",
    "netAmount": 100,
    "orderItems": [
      {
        "description": "Cat",
        "imageUrl": "https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcQhgTNCuDgVXM3besQcyklPg1UG_yct9CbGEiAqAlFu3SjHmjdWcJtjqpM8on3RGifxrsApvWGqisu49inxSZDFpQ",
        "itemName": "American shorthair",
        "price": 1000000,
        "productId": "automated_01",
        "quantity": 2,
        "sku": "S"
      },
      {
        "description": "Dog",
        "imageUrl": "https://cdn05.zipify.com/TArsw3DvFfNX8o-_adR4MItDEM8=/fit-in/1940x0/6d8d9a148fd542fba5faa74e9aeb5f60/2.jpeg",
        "itemName": "Chihuahua",
        "price": 1000000,
        "productId": "automated_02",
        "quantity": 1,
        "sku": "XS"
      }
    ],
    "referenceId": "order#10001"
  },
  "redirectUrl": "https://www.beamcheckout.com"
}   

post-payment-links

TIP

Example request object for other payment methods can be found in the Postman collection.

  • If the request is successful, you will receive a response containing the payment link object, which includes the id and url of the payment link. The response should look like this:

payment-link-creation

  1. Redirect Shopper to Payment Link
  • After creating the payment link, you can redirect the shopper to the url provided in the response. This will take them to the Beam-hosted checkout page where they can complete the payment.
  1. Track Payment Link Status
  • You can track the status of the payment link by sending a GET request to the /api/v1/payment-links/{paymentLinkId} endpoint where paymentLinkId is the id field you received in the response when creating the payment link.

get-payment-links

  • The response will contain the current status of the payment link, which will look something like this:
{
  "paymentLinkId": "rGtqz6DafS",
  "merchantId": "merchantId",
  "url": "https://playground-pay.beamcheckout.com/merchantId/rGtqz6DafS",
  "status": "ACTIVE",
  "order": {
    "netAmount": 100,
    "currency": "THB",
    "description": "Pets Shop",
    "referenceId": "order#10001",
    "internalNote": "string",
    "orderItems": [
      {
        "quantity": 2,
        "sku": "S",
        "itemName": "American shorthair",
        "description": "Cat",
        "imageUrl": "https://encrypted-tbn3.gstatic.com/images?q=tbn:ANd9GcQhgTNCuDgVXM3besQcyklPg1UG_yct9CbGEiAqAlFu3SjHmjdWcJtjqpM8on3RGifxrsApvWGqisu49inxSZDFpQ",
        "price": 1000000,
        "productId": "automated_01"
      },
      {
        "quantity": 1,
        "sku": "XS",
        "itemName": "Chihuahua",
        "description": "Dog",
        "imageUrl": "https://cdn05.zipify.com/TArsw3DvFfNX8o-_adR4MItDEM8=/fit-in/1940x0/6d8d9a148fd542fba5faa74e9aeb5f60/2.jpeg",
        "price": 1000000,
        "productId": "automated_02"
      }
    ]
  },
  "linkSettings": {
    "card": {
      "isEnabled": true
    },
    "cardInstallments": {
      "isEnabled": true,
      "installments3m": {
        "isEnabled": true
      },
      "installments4m": {
        "isEnabled": true
      },
      "installments6m": {
        "isEnabled": true
      },
      "installments10m": {
        "isEnabled": true
      }
    },
    "qrPromptPay": {
      "isEnabled": true
    },
    "eWallets": {
      "isEnabled": true
    },
    "mobileBanking": {
      "isEnabled": true
    },
    "buyNowPayLater": {
      "isEnabled": false
    }
  },
  "collectDeliveryAddress": false,
  "redirectUrl": "https://www.beamcheckout.com",
  "expiresAt": "2026-06-05T11:20:04.067+07:00",
  "feeType": "TRANSACTION_FEE"
}
  1. Handle Payment Completion
  • Once the shopper completes the payment, if the payment link is set up with a redirectUrl, the shopper will be redirected to that URL. Once the payment link is paid, the status will change to PAID and (if configured) a payment_link.paid webhook will be sent to your webhook endpoint. The schema for the webhook payload should be the same as the response from the previous step when you queried the /api/v1/payment-links/{paymentLinkId} endpoint.