Deep Link Mode

Deep Link Mode allows your application to redirect to Beam Bolt on the same device via deep link to process payments seamlessly. After completing the payment journey on Beam Bolt, automatically redirect back to your application to process your orders.

Choose this mode when your shopper is already in your own application and you want them to stay there. Beam Bolt takes the payment and hands the shopper straight back. Choose Pairing Mode instead if your staff take the payment on a separate device, or Standalone Mode if you do not want to build an integration at all.

Important

Deep Link Mode runs on your own Android device, with both your application and the Beam Bolt app installed side by side. A Bolt+ device cannot run Deep Link Mode, because it is locked to Beam Bolt and cannot switch to another application. On a Bolt+, use Pairing Mode or Standalone Mode instead.

Before you start

Install Beam Bolt on the device from Google Play , alongside your own application.
Log in to the Beam Bolt app under the merchant account you intend to use. If it is logged in to the wrong account, Bolt cannot process the payment.
Decide the returnUrl your application should be reopened at once the payment is done.

Take a payment

Create a Bolt Intent with mode.type set to DEEP_LINK and mode.deepLink.returnUrl set to the URL that Beam Bolt should return to after the payment. You can request any of the supported payment methods.

Here is an example flow of how to integrate Deep Link Mode into your application:

Shopper starts the payment: The shopper taps “Pay” or equivalent in your app.
Your app calls your server: Your app asks your backend to start the payment.
Create the Bolt Intent: Your backend calls POST /api/v1/bolt-intents with the amount, the payment method, and the returnUrl that Beam Bolt should send the shopper back to.
Beam returns the Bolt Intent: The response contains the Bolt Intent id and mode.deepLink.deepLinkUrl.
Backend forwards the deep link: Your backend passes deepLinkUrl back to your app.
App opens Beam Bolt: Your app opens deepLinkUrl, which hands the payment over to the Beam Bolt app on the same device.
Shopper pays in Beam Bolt: The Beam Bolt app takes the payment.
Beam Bolt returns to your app: The Beam Bolt app opens the returnUrl you provided, bringing the shopper back.
Your app asks for the result: Your app calls your backend to find out how the payment went. Do not trust the redirect alone as proof of payment. Always confirm with Beam.

Example request and response

Request:


POST https://api.beamcheckout.com/api/v1/bolt-intents
Content-Type: application/json
Authorization: Basic <base64(merchantId:apiKey)>
 
{
  "amount": 10000,
  "boltConnectionId": null,
  "currency": "THB",
  "expiryDurationInSec": 90,
  "internalNote": "Matcha Latte Less Sweet",
  "mode": {
    "deepLink": {
      "returnUrl": "yourapp://payment-completed/session_12345"
    },
    "type": "DEEP_LINK"
  },
  "paymentMethod": {
    "paymentMethodType": "QR_PROMPT_PAY",
    "qrPromptPay": {}
  },
  "referenceId": "ref12345"
}

Response:


{
  "amount": 10000,
  "boltConnectionId": null,
  "createdAt": "2026-02-03T15:01:33.896225+07:00",
  "createdBy": "[examplemerchantid]apk_399QCOeX6yFjpVHMS4NVBvIzIvz@api.beamcheckout.com",
  "currency": "THB",
  "expiresAt": "2026-02-03T15:03:03.896225+07:00",
  "id": "bolti_399QENW9gljWZrpIBS78VWEZO4q",
  "internalNote": "Matcha Latte Less Sweet",
  "merchant": {
    "merchantId": "examplemerchantid",
    "name": "Example Merchant",
    "logoUrl": "https://storage.googleapis.com/beam-organisation-logos/example-img.png"
  },
  "mode": {
    "type": "DEEP_LINK",
    "deepLink": {
      "deepLinkUrl": "https://beamcheckout.com/bolt/payment?boltIntentId=bolti_399QENW9gljWZrpIBS78VWEZO4q",
      "returnUrl": "yourapp://payment-completed/session_12345"
    }
  },
  "paymentMethod": {
    "paymentMethodType": "QR_PROMPT_PAY",
    "qrPromptPay": {}
  },
  "referenceId": "ref12345",
  "status": "ACTIVE",
  "updatedAt": "2026-02-03T15:01:33.896225+07:00",
  "updatedBy": "[examplemerchantid]apk_399QCOeX6yFjpVHMS4NVBvIzIvz@api.beamcheckout.com"
}

Note

mode.deepLink.deepLinkUrl in the response is the deep link URL that you can use to redirect your application to Beam Bolt app for payment processing.

Get the result

Steps 10 to 16 of the flow diagram are how you learn the outcome. Two things happen in parallel:

Beam sends the webhook: Once the payment finishes, Beam calls your webhook endpoint with bolt_intent.paid, or with charge.failed if the payment failed.
Your server fulfills the order: Treat the webhook as the reliable signal and run your fulfillment logic here.
Your server acknowledges: Reply with a success status (HTTP 2xx).
Your server polls Beam: At the same time, your backend calls GET /api/v1/bolt-intents/{boltIntentId}.
Beam returns the Bolt Intent: Repeat steps 13 and 14 until the result field is not empty.
Your server marks the order: Mark the order as succeeded, failed, expired, or canceled, so your app can read it without waiting for the webhook.
Your app shows the outcome: Your backend tells your app the final state, and your app shows it to the shopper.

For what each result value means and how to act on it, see Tracking the payment result.

Note

The shopper may never come back to your app. They could close it after paying, or the redirect could fail. The webhook in step 10 is what makes the result reliable, so fulfill the order from it rather than from the returnUrl redirect. The polling loop in steps 13 and 14 is there so your app can show the outcome as soon as the shopper does come back. A shopper who abandons the Beam Bolt app leaves the Bolt Intent to expire, which reaches you as bolt_intent.expired.

For the events to subscribe to, see Events on Beam Bolt. For where these payments show up in Lighthouse and the API, see Where Bolt payments appear.