Skip to Content
Payment LinksPayment Links

Payment Links

Payment links are hosted checkout URLs that direct your shoppers to Beam’s payment UI that allows you to securely accept payments without the need for a full-fledged integration.

Along with creating payment links from your merchant account in Lighthouse , you can create and manage them via API calls to Beam.

For full API details, see the Payment Links API Specification and the Payment Links API Integration Guide.

Your merchant account has a default set of payment methods, which you configure in Lighthouse . You can override those defaults for a single link with the linkSettings object on the create request:

  • Omit linkSettings: the link offers your default payment methods.
  • Send linkSettings: it replaces the defaults for that link, and the link offers only what you enable there.
Important

Once you send linkSettings, your defaults no longer apply to that link. Any group you leave out of the object is disabled. A request that sends only card creates a card-only link, even if your account defaults offer more.

So list every group you want to offer on that link, and omit linkSettings when you want your defaults.

Each group covers a family of payment methods and is switched with its own isEnabled flag:

linkSettings groupOffers
cardCard payments.
cardInstallmentsCard installments over 3, 4, 6, or 10 months, each period with its own flag.
qrPromptPayQR PromptPay.
eWalletsAll eWallet providers: Line Pay, TrueMoney, Alipay, WeChat Pay, and Shopee Pay.
mobileBankingAll mobile banking providers: Krungthai NEXT, Krungsri App, and SCB Easy.
buyNowPayLaterAll buy now, pay later providers.
Note

cardInstallments has a flag for each period (installments3m, installments4m, installments6m, installments10m) as well as its own isEnabled. Setting the group’s isEnabled to false turns off every period, even the ones set to true. Setting it to true lets each period follow its own flag.

Tip

To accept payments from Alipay app users, enable qrPromptPay. They scan the same PromptPay QR code, because Alipay and Thailand’s PromptPay network work together across borders, so the same QR code works for both.

For a request that turns several groups on, see the Integration Guide. For the exact shape of each group, see LinkSettings.

These groups are not the same thing as the paymentMethodType value you send when you create a charge yourself through the Charges API. Both draw on Beam’s pool of online payment methods, which also covers store links and QR PromptPay links. The difference is how you choose: a charge names a single paymentMethodType, while a payment link enables whole groups and lets the shopper pick on the checkout page. See Available payment methods for the full pool.

The following shows a flow of creating a payment link that results in a successful payment.

  1. Shopper initiates checkout: The shopper clicks “Pay” or equivalent on the merchant’s website.

  2. Frontend requests payment: The merchant’s frontend calls the merchant’s backend to initiate the payment.

  3. Create payment link: The merchant’s backend calls Beam’s POST /api/v1/payment-links endpoint, passing the order details.

  4. Beam returns the payment link: Beam responds with the unique payment link URL.

  5. Backend forwards URL to frontend: The merchant’s backend passes the payment link URL back to its frontend.

  6. Redirect shopper to payment link: The merchant’s frontend redirects the shopper’s browser to Beam’s hosted payment link page.

  7. Payment page loads: The shopper sees Beam’s payment UI with available payment methods and the order summary.

  8. Shopper submits payment: The shopper enters their payment details and submits.

  9. Beam processes the payment: Beam’s payment link page sends the payment data to Beam’s server, which processes the transaction.

  10. Payment confirmed: Beam’s server confirms the payment result to the payment link page.

After payment, two things happen in parallel

  1. Shopper sees confirmation (frontend): The payment link page redirects the shopper’s browser to a completion page so they get immediate visual confirmation.

  2. Webhook to merchant (backend): At the same time, Beam’s server sends a webhook to the merchant’s backend with the payment result. The merchant’s backend should use this webhook to trigger order fulfillment, since it arrives reliably even if the shopper closes their browser after paying.

  3. Merchant acknowledges: The merchant’s backend responds with a success status (HTTP 2xx).

Tip

Build your order fulfillment logic on the webhook (step 12), not on the frontend redirect (step 11). The webhook is the reliable signal that payment succeeded.

  • ACTIVE: The payment link is active and can be used to accept payments. A newly created payment link will be in this state.
  • PAID: The payment link has successfully accepted a payment and cannot be reused.
  • EXPIRED: The payment link has expired and cannot be used to accept payments.
  • DISABLED: The payment link is disabled and cannot be used to accept payments.
  • VOIDED: The payment for this link was reversed, so the link can no longer be used to accept payments.
  • REFUNDED: The payment for this link was refunded, so the link can no longer be used to accept payments.

Both VOIDED and REFUNDED follow a successful refund on the link’s payment. Treat them the same: the link cannot be used again, and the money has been returned to the shopper.

Optional features

Redirect after payment (redirectUrl)

You can redirect shoppers to your own URL after a successful payment by providing the redirectUrl field in the payment link creation request. This URL replaces the default completion page in step 11 of the payment flow above.

If redirectUrl is omitted, the shopper sees Beam’s default completion page after paying.

Cancellation (cancelUrl)

If the shopper decides not to complete payment, they can click the cancel button on Beam’s payment link page. Beam redirects them to a cancelUrl you provide when creating the payment link, so you can release reserved inventory, log the cancellation, or return the shopper to their cart.

This feature is optional. The cancel button is only rendered when you provide a cancelUrl field.

Configuring cancelUrl

When creating the payment link via POST /api/v1/payment-links, include a cancelUrl field. The URL can point to either your frontend or your backend. Both patterns are supported, and the right choice depends on what you need to do on cancellation.

Query parameters are preserved. You can encode your own order reference in the URL (for example, https://shop.com/cancel?orderId=abc123) and Beam will redirect the shopper to that exact URL on cancellation. This is how you correlate the cancellation back to the original order on your side.

Note

Do not include sensitive data (session tokens, API keys, personal information) in the cancelUrl query string. It will be visible in the shopper’s browser history and HTTP logs.

Cancellation flow

Steps 1–7 are identical to the payment flow above (up to and including “Payment page loads”).

  1. Shopper cancels: The shopper clicks the cancel button on Beam’s payment link page.

  2. Redirect to cancelUrl: Beam redirects the shopper’s browser to the cancelUrl you provided, preserving any query parameters you included.

From here, the flow depends on whether your cancelUrl points to your backend or your frontend.

Use this pattern when cancellation needs to trigger backend logic such as releasing inventory or logging the cancellation event. The backend runs the cleanup logic reliably before the shopper sees the cart again.

  1. Browser hits cancelUrl: The shopper’s browser sends a GET request to your backend’s cancelUrl endpoint.

  2. Backend handles cancellation: Your backend releases inventory, logs the cancellation, or runs whatever cleanup is needed. Use the query parameters from the URL (for example, orderId) to identify which order was canceled.

  3. Redirect to cart: Your backend responds with an HTTP 302 redirecting the shopper to your cart page.

  4. Cart page loads: The shopper’s browser loads the cart page from your frontend.

  5. Cart displayed: The shopper sees their cart, ready to retry or modify their order.

Option B: cancelUrl points to your frontend

Use this pattern when cancellation only requires frontend state changes (for example, showing a “payment canceled” message) and any backend cleanup can be triggered from the frontend.

  1. Browser hits cancelUrl: The shopper’s browser loads the cancelUrl page from your frontend.

  2. Frontend notifies backend: Your frontend calls your backend to register the cancellation, passing the order reference from the URL’s query parameters.

  3. Backend acknowledges: Your backend runs any cleanup logic and confirms receipt.

  4. Cart displayed: Your frontend shows the cart page to the shopper.

Tip

Option A is more reliable for inventory release and other critical cleanup, because the backend runs before the shopper’s browser reaches the cart page. With Option B, a shopper who closes their browser between Beam’s redirect and your frontend’s call to your backend may leave inventory in a reserved state.

Fee Type

By default, fee types are TRANSACTION_FEE. To unlock SERVICE_FEE fee type calculation, please contact us for approval.

Collect shopper details

The following can be toggled on to collect additional details from the shopper as they pay:

  • collectDeliveryAddress - will render a form for shoppers to fill in their delivery address
  • collectPhoneNumber - will render a form for shoppers to fill in their phone number

You can set when you want the link to expire, so that after the timestamp indicated, the payment link becomes invalid automatically. This can be set with expiresAt.

  • payment_link.paid: the link has been paid. Use this event to fulfill the order.
  • charge.succeeded and charge.failed: the outcome of each payment attempt on the link. See Charges.
  • transaction.created: Beam recorded the transaction for the payment.

See Event Types for each payload and the Webhook guide for how to set your endpoint up. For which event to act on, see step 12 of the payment link flow above.

Limitations

We do not recommend rendering Beam’s payment link inside an iframe . Beam attaches the X-Frame-Options: DENY header for security. See the MDN reference  for more.

Currently only single use payment links are supported. This means that once a payment link is used to make a payment, it cannot be reused.

Next steps

Last updated on
Switching to ProductionPayment Links API