Pairing Mode

Pairing Mode allows your Bolt device to accept payment requests from your server by establishing a secure connection wirelessly through the internet.

Choose this mode when your own system already knows what the shopper is paying for. You send the amount, and you can send your own referenceId too, so the payment ties back to the order, delivery, or inventory record it belongs to. That makes reconciliation straightforward. Choose Standalone Mode instead if you do not want to build an integration, or Deep Link Mode if the shopper is already in your own application on the device.

Pairing Mode runs on a Bolt+  device, or on your own Android device with the Beam Bolt app installed from Google Play . See Where Beam Bolt runs for the internet and NFC requirements.

Before you start

• Log in to the Beam Bolt app on the device, under the merchant account you intend to use. You have to log in before you can do anything else on the device.
• Connect the device to your server once, before you take any payments. Every payment request needs the Bolt Connection that step gives you. See Connecting to a device.
• In the diagrams on this page, Terminal means your own point-of-sale app or till, the software your staff use.

Connecting to a device

After Beam Bolt enters Pairing Mode, the device displays a Pairing Code and its expiry time. You then connect your server to that device with the Create Bolt Connection API.

1. Merchant selects Pairing Mode: Your staff pick Pairing Mode on the Beam Bolt device.

2. Device shows a Pairing Code: Beam Bolt displays a Pairing Code and the time it expires.

3. Merchant enters the code on the Terminal: Your staff type the Pairing Code into your own app.

4. Terminal sends the code to your server: Your app passes the Pairing Code and its Terminal ID to your own backend. Only the Pairing Code is sent on to Beam.

5. Create the Bolt Connection: Your backend calls POST /api/v1/bolt-connections with the Pairing Code.

After that, two things happen in parallel

6. Beam returns the Bolt Connection: The response contains the Bolt Connection id and the deviceId it belongs to.

7. Your server stores the connection: Save the Bolt Connection ID against the Terminal or store, so you can reuse it for every later payment request.

8. Your server confirms to the Terminal: Your backend tells your app that pairing succeeded.

9. Terminal confirms to the merchant: Your staff see that the device is paired.

10. Beam notifies the device: At the same time, Beam tells the Beam Bolt device that the connection is established.

11. Device becomes ready: Beam Bolt shows the “Ready for payments” screen and waits for payment requests.

Here is an example request for Pairing Code “123456”:

POST https://api.beamcheckout.com/api/v1/bolt-connections
Content-Type: application/json
Authorization: Basic <base64(merchantId:apiKey)>
 
{
  "pairingCode": "123456"
}

To check later that a connection is still valid, use the Get Bolt Connection API.

Take a payment

Once the Bolt Connection is established, you are ready to forward payment requests to the connected device by creating a Bolt Intent with mode.type set to PAIRING and boltConnectionId set to the connection you stored. You can request any of the supported payment methods.

Steps 1 to 8 create the payment request and put it in front of the shopper:

1. Shopper places an order: The shopper orders at your Terminal.

2. Terminal creates the order: Your app calls your backend to create the order.

3. Create the Bolt Intent: Your backend calls POST /api/v1/bolt-intents with the amount, the payment method, and the boltConnectionId of the device that should take the payment.

4. Beam returns the Bolt Intent: Your backend receives the created Bolt Intent, including its id.

5. Beam hands the Bolt Intent to the device: Beam pushes the payment request to the connected Beam Bolt device.

6. Backend returns the order: Your backend returns the order to your Terminal.

7. Device prompts the shopper: Beam Bolt shows the payment screen for the payment method you asked for, for example a PromptPay QR code or a card prompt.

8. Shopper pays: The shopper taps their card or scans the QR code on the device.

Example payment request

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

Wait for the “Ready for payments” screen

If you create a Bolt Intent while Beam Bolt is not on the “Ready for payments” screen, the payment request is discarded. Wait 5 seconds after the device connects, or after a Bolt Intent is canceled or expires, before you create the next Bolt Intent.

Get the result

Steps 9 to 17 of the flow diagram are how you learn the outcome. Three things happen in parallel:

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

10. Your server fulfills the order: Treat the webhook as the reliable signal and run your fulfillment logic here. It still reaches you if your polling stops or your service restarts.

11. Your server acknowledges: Reply with a success status (HTTP 2xx).

12. Your server polls Beam: At the same time, your backend calls GET /api/v1/bolt-intents/{boltIntentId}.

13. Beam returns the Bolt Intent: Repeat steps 12 and 13 until the result field is not empty.

14. Your server marks the order: Mark the order as succeeded, failed, expired, or canceled, so your Terminal can read it without waiting for the webhook. For what each result value means, see Tracking the payment result.

15. Your Terminal polls your server: Your app polls your own backend for the order.

16. Your server returns the finished order: Once the order is succeeded or failed, your backend returns it.

17. Terminal shows the result: Your app shows the outcome to the shopper.

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.

Disconnecting from a device

You can disconnect your server from the Beam Bolt device with the Delete Bolt Connection API.

1. Merchant asks to disconnect: Your staff trigger a disconnect on your Terminal.

2. Terminal calls your server: Your app sends the disconnect request with its Terminal ID.

3. Your server finds the connection: Look up the Bolt Connection ID you stored for that Terminal.

4. Delete the Bolt Connection: Your backend calls DELETE /api/v1/bolt-connections/{boltConnectionId}.

After that, two things happen in parallel

5. Beam confirms the deletion: Your backend receives a successful response.

6. Your server drops the connection: Remove the stored Bolt Connection ID so you do not reuse it.

7. Your server confirms to the Terminal: Your backend tells your app that the disconnect succeeded.

8. Terminal confirms to the merchant: Your staff see that the device is disconnected.

9. Beam notifies the device: At the same time, Beam tells the Beam Bolt device that the connection is deleted.

10. Device returns to mode selection: Beam Bolt shows the “Select Mode” screen.