Bolt Intent

A Bolt Intent is an intent to receive a payment from a shopper through a Beam Bolt device.

It specifies how you want your shopper to pay. This includes the amount, the payment method (e.g. Card, Card Installments, QR PromptPay), and any details specific to that payment method (e.g. the installment period).

In Pairing Mode, you create a Bolt Intent to send a payment request to the connected Beam Bolt device.

In Deep Link Mode, you create a Bolt Intent to generate a deep link URL. The URL redirects your application to the Beam Bolt app to process the payment.

Once a Bolt Intent is created and handed off to the Beam Bolt device or app, the device or app prompts the shopper to pay according to the Bolt Intent details.

When the shopper attempts to pay, a Charge is created with source BOLT and sourceId equal to the Bolt Intent’s id. Charges created from Bolt appear on the Bolt Charges page in Lighthouse.

To create, read, and cancel Bolt Intents, see the Bolt Intent API.

Supported payment methods

The following payment methods are supported on Bolt Intents:

Card (CARD)
Card Installments (CARD_INSTALLMENTS)
QR PromptPay (QR_PROMPT_PAY)
Alipay (ALIPAY)
Alipay Plus (ALIPAY_PLUS)
Line Pay (LINE_PAY)
Shopee Pay (SHOPEE_PAY)
TrueMoney (TRUE_MONEY)
WeChat Pay (WECHAT_PAY)
SPayLater (SPAY_LATER)

Note

Available Bolt payment methods are not the same as those supported in Charges API. This is indicated in BoltPaymentMethodType and OnlinePaymentMethodType enum respectively in the API Reference.

To accept a payment from a shopper paying with Alipay, create the Bolt Intent with paymentMethodType set to QR_PROMPT_PAY, not ALIPAY. Alipay app users can scan the same PromptPay QR code to pay, through cross-border QR payment interoperability between Alipay and Thailand’s PromptPay network.

Expiry and cancellation

Every Bolt Intent expires. expiryDurationInSec is required when you create one, and it must be between 90 and 600 seconds (90 seconds to 10 minutes). A request outside that range is rejected.

You can also cancel a Bolt Intent before it expires, with the Cancel Bolt Intent API.

Tip

Pick the shortest duration that still gives your shopper time to pay. The expiry is what stops your server and the Beam Bolt device waiting for a result that is never coming, and a shorter one frees the device for the next order sooner.

Bolt Intent lifecycle

ACTIVE - The Bolt Intent is active and ready to accept payments.
PAID - The Bolt Intent has accepted a successful payment and can no longer accept payments.
CANCELED - The Bolt Intent is canceled and can no longer accept payments.
EXPIRED - The Bolt Intent has expired and can no longer accept payments.
VOIDED - The Charge associated with the Bolt Intent has been voided, so the Bolt Intent can no longer accept payments.
REFUNDED - The Charge associated with the Bolt Intent has been refunded, so the Bolt Intent can no longer accept payments.

Note

A canceled or expired Bolt Intent does not accept further payment attempts. You cannot create a new Charge from it. Charges created before it was canceled or expired can still succeed or fail afterwards.

Here is a state diagram of the Bolt Intent statuses:

Tracking the payment result

There are two ways to learn how a payment went, and a complete integration uses both. They do different jobs:

Webhooks tell your server the outcome. Beam calls your endpoint once the payment finishes. This is the reliable signal, because it still reaches you if your service restarts or your polling stops. Build your order fulfillment on it. See Listen to Bolt Intent webhooks below.
Polling gives you an answer straight away. Call the Get Bolt Intent API with boltIntentId until the result field is not empty. Your staff and your shopper are waiting at the device, so poll to update the screen without waiting for the webhook to arrive.

Important

The webhook and a poll can reveal the same outcome, and either one can reach you first. Make your handling idempotent, so processing an outcome twice does not fulfil an order twice. See the Go-live Checklist for the pattern we recommend.

The result field carries the outcome either way:

`result`	Meaning	Recommended action
(empty)	No Charge yet, or latest Charge is still pending	Continue polling
`CH_SUCCEEDED`	Latest Charge succeeded	Mark order as succeeded
`CH_PROCESSING_FAILED`	Latest Charge failed: processing error	Mark order as failed
`CH_INSUFFICIENT_FUNDS`	Latest Charge failed: insufficient funds	Mark order as failed
`CH_CARD_EXPIRED`	Latest Charge failed: card expired	Mark order as failed
`CH_CARD_DECLINED`	Latest Charge failed: card issuer declined	Mark order as failed
`CH_CARD_RESTRICTED`	Latest Charge failed: card restricted	Mark order as failed
`CH_CARD_INCORRECT_DETAILS`	Latest Charge failed: incorrect card details	Mark order as failed
`CH_CARD_INCORRECT_PIN`	Latest Charge failed: incorrect PIN	Mark order as failed
`CH_CARD_PIN_ATTEMPT_EXCEEDED`	Latest Charge failed: PIN attempts exceeded	Mark order as failed
`CH_AUTHENTICATION_FAILED`	Latest Charge failed: authentication error	Mark order as failed
`BI_EXPIRED`	Bolt Intent expired	Mark order as expired
`BI_CANCELED`	Bolt Intent was canceled	Mark order as canceled

A Bolt Intent also has three fields that point at its latest Charge: latestChargeId, latestChargeStatus and latestChargeFailureCode. You can read more about them in the Get Charge API.

Warning

A Charge created just before expiry or cancellation could still succeed after the Bolt Intent transitions to BI_EXPIRED or BI_CANCELED. If this happens, refund the Charge manually from Lighthouse to avoid capturing funds for an expired or canceled order.

Listen to Bolt Intent webhooks

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

Beam sends bolt_intent.paid, bolt_intent.canceled and bolt_intent.expired. See Event Types for the full list and payload examples.

There is no bolt_intent.failed event. A failed payment arrives as charge.failed instead, so subscribe to charge.failed as well if you want to know when a payment was declined and prompt the shopper to try another card. You can match the event to the Bolt Intent through the Charge’s sourceId.