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

# Accept payments with Stripe on your Cartble store

> Connect Stripe for online card payments or enable manual payments for bank transfer and cash — all with zero transaction fees from Cartble.

Cartble supports two payment methods out of the box: **Stripe** for online card payments (credit cards, debit cards, Apple Pay, and Google Pay), and **Manual** for offline scenarios like bank transfer or cash on delivery. You can enable both simultaneously and let the customer choose at checkout. Cartble never adds its own transaction fees on top of your payment provider's standard rates.

## Payment methods at a glance

<CardGroup cols={2}>
  <Card title="Stripe" icon="credit-card">
    Accept online payments worldwide. Customers pay with credit or debit cards, Apple Pay, or Google Pay directly on your checkout page. Funds settle into your Stripe account on your normal payout schedule.
  </Card>

  <Card title="Manual Payment" icon="building-columns">
    Display custom payment instructions to customers at checkout (e.g., bank account details or cash-on-delivery instructions). You confirm the payment manually once funds are received.
  </Card>
</CardGroup>

## Connecting Stripe

<Steps>
  <Step title="Open Payment Settings">
    In your admin dashboard, go to **Settings → Payments** (or navigate to **Plugins → Stripe Payments**). You'll see the Stripe Payments configuration panel.
  </Step>

  <Step title="Enable the Stripe plugin">
    Toggle **Stripe Payments** to the enabled position at the top of the panel.
  </Step>

  <Step title="Enter your API keys">
    Paste your **Publishable Key** (starts with `pk_live_` or `pk_test_`) and your **Secret Key** (starts with `sk_live_` or `sk_test_`) from your [Stripe Dashboard → Developers → API keys](https://dashboard.stripe.com/apikeys).
  </Step>

  <Step title="Create a webhook endpoint in Stripe">
    In your Stripe Dashboard, go to **Developers → Webhooks → Add endpoint**. Set the endpoint URL to your Cartble webhook URL (shown in the Stripe settings panel). Select the events listed in the [Webhook events](#webhook-events) section below, then save the endpoint. Stripe will display a **Signing Secret** (starts with `whsec_`) — keep this available for your server-side configuration, as it allows Cartble to verify that incoming webhook calls genuinely originate from Stripe.
  </Step>

  <Step title="Test with a Stripe test card">
    Keep **Test Mode** toggled on and use a [Stripe test card](https://stripe.com/docs/testing#cards) (e.g., `4242 4242 4242 4242`) to place a test order. Verify the order appears in your dashboard with a `paid` financial status before switching to live mode.
  </Step>
</Steps>

<Warning>
  Never share or expose your Stripe **Secret Key** publicly — not in client-side code, public repositories, or support tickets. The secret key grants full access to your Stripe account. If you suspect it has been compromised, roll it immediately from your Stripe Dashboard.
</Warning>

### Test mode

The Stripe settings panel includes a **Test Mode** toggle. While test mode is active, transactions are processed against Stripe's test environment and no real money moves. Disable test mode only after you have verified your integration end-to-end with a test card.

## Webhook events

Cartble listens for the following Stripe webhook events to keep your orders and subscriptions in sync:

| Stripe event                    | What Cartble does                                                                                 |
| ------------------------------- | ------------------------------------------------------------------------------------------------- |
| `checkout.session.completed`    | Registers a completed checkout session and creates the associated subscription record in Cartble. |
| `invoice.paid`                  | Records a successful subscription or invoice payment against the customer's account.              |
| `invoice.payment_failed`        | Marks the related subscription payment as failed so you can follow up with the customer.          |
| `customer.subscription.created` | Creates a new active subscription record in Cartble.                                              |
| `customer.subscription.updated` | Syncs subscription status, current period end, and plan changes.                                  |
| `customer.subscription.deleted` | Marks the subscription as cancelled in Cartble.                                                   |

<Info>
  Make sure all six event types above are selected when you configure your Stripe webhook endpoint. Missing events can cause payment records or subscriptions to fall out of sync with your Cartble dashboard.
</Info>

## Manual payments

Manual payments are ideal when customers pay offline — for example, by direct bank transfer, cash on delivery, or in-person at pickup.

<Steps>
  <Step title="Enable manual payments">
    Go to **Settings → Payments** and enable the **Manual Payment** option.
  </Step>

  <Step title="Add your payment instructions">
    Enter the instructions customers will see at checkout — for example, your bank name, account number, and reference format. Be specific so customers know exactly how to complete the transfer.
  </Step>

  <Step title="Confirm payments manually">
    When a customer chooses manual payment and places an order, the order is created with a `pending` financial status. Once you confirm receipt of funds, open the order in your dashboard and update the financial status to `paid`.
  </Step>
</Steps>

## Viewing payment records

Navigate to **Admin → Payments** to see a full transaction history across all payment methods.

Each record shows:

* **Transaction number** — matches the order number for easy cross-referencing.
* **Amount** — total charged including tax and shipping.
* **Financial status** — `paid`, `pending`, `refunded`, `partially_paid`, or `voided`.
* **Date** — timestamp of the transaction.
* **Payment method** — Stripe or Manual.

<Tip>
  Use the status filter at the top of the Payments view to surface all `pending` manual payment orders at once, making it easy to reconcile your bank statement against outstanding orders each day.
</Tip>

## Currencies

Your store's currency is set in **Settings → Regional**. All prices, discounts, and transaction records are stored and displayed in the currency you configure there. Stripe supports multi-currency payouts — ensure your Stripe account is enabled for any currencies you plan to accept.