> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stardeck.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Payments

> Accept payments using Stardeck's built-in Beam Checkout and Stripe Connect integrations

## Overview

Stardeck has built-in support for two payment providers: **Beam Checkout** and **Stripe Connect**. These are managed through the Payments tab in your project settings and provide a native SDK for your app to accept payments without manual API key management.

For third-party payment gateways using environment variables (Stripe direct, Omise, etc.), see [Third-Party Payment Gateways](/third-party-payment-gateways).

## Beam Checkout

Beam is a Thai payment gateway supporting QR PromptPay, credit cards, e-wallets (LINE Pay, TrueMoney, ShopeePay), mobile banking, and buy-now-pay-later options. All amounts are in satang (100 satang = 1 THB).

### Minimum App Version

Beam features require your app to be on a minimum version:

| Feature                                | Min Version |
| -------------------------------------- | ----------- |
| Payment Links                          | 5.2.0       |
| Direct Charges, Bolt Intents, Webhooks | 6.7.0       |

You can check your app version in the project settings. If your app is below the required version, ask the agent to upgrade it.

### Getting Started with Playground

You can start building and testing payment flows immediately using Beam Playground, a shared test environment that requires no Beam account or API keys.

1. Open your project in the Stardeck dashboard
2. Go to [**Settings** > **Payments**](https://www.stardeck.ai/projects/~/dashboard/services/payments)
3. Select **Beam Checkout** and click **Set Up Beam**
4. The **Sandbox** toggle is enabled by default under "Use Beam Playground"

Your sandbox environment is now configured to route payment API calls to Beam's test environment. You can start building payment features right away.

### Playground Deployment Targets

You can control which deployment types use the Beam Playground:

| Target         | Description                                       |
| -------------- | ------------------------------------------------- |
| **Sandbox**    | Your development environment (enabled by default) |
| **Preview**    | Preview deployments from branches                 |
| **Production** | Your live production deployment                   |

Toggle these on or off in the Beam Playground section. Changes take effect on the next sandbox restart (triggered automatically for sandbox deployments).

### Configuring Payment Methods

In the **Allowed Payment Methods** section, toggle which payment types are available on your payment links:

* Card Payments
* QR PromptPay
* E-Wallets (LINE Pay, TrueMoney, ShopeePay)
* Mobile Banking
* Buy Now Pay Later (Atome)
* Card Installments (3, 4, 6, or 10 months)

These settings apply to both playground and production environments.

### Using the Payments SDK

Your app uses the `@stardeck-customer-apps/payments-sdk` package (pre-installed in all Stardeck projects) to create payments. The SDK supports two approaches:

#### Payment Links (Hosted Checkout)

Payment links redirect the customer to a Beam-hosted checkout page. Beam handles the payment UI, and the customer is redirected back to your app after payment. The **Allowed Payment Methods** settings control which methods are available on the checkout page.

```
Create a checkout page for my online store using Beam payment links.

Requirements:
- Show the cart items and total before checkout
- Create a Beam payment link and redirect the customer to pay
- After payment, redirect back to an order confirmation page
- Store the order in the database with payment status
```

#### Direct Charges (API-Integrated)

Direct charges let you build a fully custom payment experience within your app. Instead of redirecting to Beam, your server creates a charge and gets back either a QR code image (for PromptPay) or a redirect URL (for card/e-wallet payments). This gives you full control over the payment UI.

```
Build an inline PromptPay payment flow for my restaurant POS.

Requirements:
- Create a direct charge with QR_PROMPT_PAY payment method
- Display the QR code image directly on the page (no redirect)
- Poll for payment status and show a success message when paid
- Store the transaction in the database
```

Direct charges support all Beam payment methods including `QR_PROMPT_PAY`, `CARD`, `LINE_PAY`, `TRUE_MONEY`, `SHOPEE_PAY`, and more. The response tells you what action is needed:

* **ENCODED\_IMAGE** — Display the returned QR code (PromptPay)
* **REDIRECT** — Redirect the customer to the returned URL (cards, e-wallets)
* **NONE** — Payment completed immediately

#### Bolt Terminals (Physical Devices)

For physical point-of-sale setups, use Bolt intents to send payment requests to paired terminals. See [Bolt Paired Devices](#bolt-paired-devices) below.

```
Build a POS checkout that sends a card payment to my Bolt terminal.

Requirements:
- Select a paired Bolt device from the list
- Send a payment intent for the order total
- Poll for charge status to confirm payment
- Print a receipt after successful payment
```

### Testing in Playground

When using Beam Playground, payments are processed in test mode. You can use test card numbers and QR codes to simulate transactions without real money.

<Info>
  Beam Playground transactions do not charge real money. All payment links and charges created in
  playground mode use Beam's test environment.
</Info>

### Going Live with Production

When you're ready to accept real payments:

1. Create a Beam merchant account at [Beam Lighthouse](https://lighthouse.beamcheckout.com)
2. In the Payments tab, enter your **Beam Merchant ID** in the Production section
3. Add your **Beam API Key** (found in Beam Lighthouse under Developers)
4. Configure your **Webhook Secret** (register `https://your-domain/api/webhooks/beam` in Beam Lighthouse under Developers > Webhooks, then paste the HMAC key)
5. Turn off the **Sandbox** playground toggle for your production deployment

You can keep playground enabled for sandbox and preview deployments while running production with real credentials, and switch between them without redeploying.

### Bolt Paired Devices

For physical point-of-sale setups, Beam supports pairing physical payment terminals (Bolt devices). In the Payments tab under **Bolt+ Paired Devices**, you can:

* Pair a device using its pairing code (8 characters, letters and numbers, e.g. `4TY9JDH2`)
* View connection status
* Remove paired devices

Bolt devices can be paired in either sandbox or production mode.

## Stripe Connect

Stripe Connect lets you accept credit card payments, subscriptions, and more through your **own** Stripe account. You connect the Stripe account you already use, and payments are charged directly to it — Stardeck never holds your funds, and you keep your existing Stripe dashboard, payouts, and branding.

### Connecting your Stripe account

1. Open your project in the Stardeck dashboard
2. Go to [**Settings** > **Payments**](https://www.stardeck.ai/projects/~/dashboard/services/payments)
3. Select **Stripe Connect** and click **Connect with Stripe**
4. You'll be sent to Stripe to sign in and authorize access, then brought back to the Payments tab

That's the whole setup — there's no API key to copy or paste. If you don't have a Stripe account yet, you can create one during the authorization step.

<Info>
  You connect an account you control. Stripe remains the system of record for your payments,
  payouts, customers, and tax settings — manage all of that in your own [Stripe
  dashboard](https://dashboard.stripe.com).
</Info>

### Connection status

Once connected, the Payments tab shows your account status:

* **Charges Enabled** — your account can accept payments. When this is on, you're ready to go live.
* **Payouts Enabled** — Stripe can pay out to your bank account.

If charges aren't enabled yet, Stripe still needs some information (business details, bank account, identity verification). Finish those steps in your [Stripe dashboard](https://dashboard.stripe.com), then refresh the Payments tab — the status updates automatically.

### Managing products

When charges are enabled, the Payments tab shows a **Products** section where you can create products and prices (one-time or recurring) without leaving Stardeck. These are created on your Stripe account and are immediately usable in checkout. You can also manage them directly in your Stripe dashboard.

### Disconnecting

To disconnect, use the Payments tab. This revokes Stardeck's access to your Stripe account on Stripe's side as well, so no further charges can be created through your app. Your Stripe account and its data are unaffected — only the connection is removed.

### Using the SDK with Stripe Connect

The same `@stardeck-customer-apps/payments-sdk` works for Stripe Connect. Example prompts:

```
Create a checkout flow for my SaaS app using Stripe.

Requirements:
- Monthly subscription at $29/mo
- Annual plan at $290/year
- Redirect to dashboard after successful payment
- Show billing portal link for managing subscriptions
```

<Note>
  Already have a Stripe account that our team connected for you, or need help? Contact
  [support@stardeck.ai](mailto:support@stardeck.ai).
</Note>