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-side 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.

Payment link flow — successful payment

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

11. Frontend: shopper sees confirmation — The payment link page redirects the shopper’s browser to a completion page so they get immediate visual confirmation.

12. Backend: webhook to merchant — 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.

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

Recommendation: 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.

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.

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

Link Expiry

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 lifecycle

• 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 charge associated with the payment link has been voided. Therefore, the payment link can no longer be used to accept payments.
• REFUNDED: The charge associated with the payment link has been refunded. Therefore, the payment link can no longer be used to accept payments.

Listen to Payment Link Webhooks

You can configure your webhook endpoint to listen to payment-link-related events by following the instructions in the Webhook guide.

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.