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

# Quickstart

> Authenticate, start a payment, pay at checkout and verify it, all in test mode, in about ten minutes.

This quickstart takes you from a test key to a verified payment without moving real money. Every call runs in **test mode**.

```bash cURL theme={null}
curl -X POST https://api.spotflow.co/api/v1/payments/initialize \
  -H "Authorization: Bearer $SPOTFLOW_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order-1001",
    "amount": 5.00,
    "currency": "GHS",
    "customer": { "email": "john@example.com" }
  }'
```

```javascript Node.js theme={null}
const res = await fetch("https://api.spotflow.co/api/v1/payments/initialize", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SPOTFLOW_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    reference: "order-1001",
    amount: 5.0,
    currency: "GHS",
    customer: { email: "john@example.com" },
  }),
});
const payment = await res.json();
console.log(payment.checkoutUrl);
```

```python Python theme={null}
import os, requests

res = requests.post(
    "https://api.spotflow.co/api/v1/payments/initialize",
    headers={"Authorization": f"Bearer {os.environ['SPOTFLOW_SECRET_KEY']}"},
    json={
        "reference": "order-1001",
        "amount": 5.00,
        "currency": "GHS",
        "customer": {"email": "john@example.com"},
    },
)
print(res.json()["checkoutUrl"])
```

```json 200 theme={null}
{
  "reference": "order-1001",
  "checkoutUrl": "https://checkout.spotflow.co/paymentCode",
  "paymentCode": "PAY123456789",
  "status": "pending",
  "mode": "TEST",
  "expiryTime": "2025-11-03T10:16:26.948278058"
}
```

## Before you start

* A Spotflow account. [Sign up](https://app.spotflow.co/signup) if you don't have one.
* You don't need KYB verification to use test mode. You'll need it before you can go live. See [KYB verification](https://docs.spotflow.one/expert-desk/verification-process.md).

**1. Get your test secret key**

In the [Spotflow dashboard](https://app.spotflow.co/), switch to **test mode** and open **Settings → API Keys**. Copy your secret key. It starts with `sk_test_`.

Store it as an environment variable, never in code:

```bash theme={null}
export SPOTFLOW_SECRET_KEY="sk_test_..."
```

> [!WARNING]
>
> Your secret key grants full access to your account. Keep it on your server and never put it in frontend code. Client-side integrations use your public key (`pk_test_…`). See [Authentication](https://docs.spotflow.one/api-reference/authentication.md).

**2. Start a payment**

Call [Initialize Payment](https://docs.spotflow.one/api-reference/payments/initialize-collection.md) with a unique `reference`, the `amount`, the `currency` and the customer's email. The request and response are shown alongside this page, in cURL, Node.js and Python.

* `amount` is in the **major unit** of the currency: `5.00` with `GHS` means five Ghana cedis.
* `reference` is yours. Keep it unique per payment. It's also your [idempotency key](https://docs.spotflow.one/api-reference/idempotency.md), so a retry with the same reference won't create a second payment.

The response includes a `checkoutUrl` and a `status` of `pending`.

**3. Pay at checkout**

Open the `checkoutUrl` in your browser and pay with one of the test cards or test mobile money numbers on [Testing payments](https://docs.spotflow.one/expert-desk/testing-payments.md). Test details only work with test keys.

**4. Verify the payment**

Check the result with [Verify Payment](https://docs.spotflow.one/api-reference/payments/verify-collection.md), using your reference:

```bash cURL theme={null}
curl "https://api.spotflow.co/api/v1/payments/verify?reference=order-1001" \
  -H "Authorization: Bearer $SPOTFLOW_SECRET_KEY"
```

```javascript Node.js theme={null}
const res = await fetch(
  "https://api.spotflow.co/api/v1/payments/verify?reference=order-1001",
  { headers: { Authorization: `Bearer ${process.env.SPOTFLOW_SECRET_KEY}` } }
);
console.log(await res.json());
```

```python Python theme={null}
res = requests.get(
    "https://api.spotflow.co/api/v1/payments/verify",
    params={"reference": "order-1001"},
    headers={"Authorization": f"Bearer {os.environ['SPOTFLOW_SECRET_KEY']}"},
)
print(res.json())
```

A payment moves from `PENDING` to `SUCCESSFUL`, `FAILED` or `CANCELLED`. See [Payment lifecycle](https://docs.spotflow.one/developer-resources/payment-states.md).

> [!TIP]
>
> Don't poll more than once every 5 seconds. In production, use [webhooks](https://docs.spotflow.one/developer-resources/webhooks/overview.md) to learn when a payment completes, then verify it before you fulfil the order.

## Troubleshooting

| What you see | What it means | What to do |
| - | - | - |
| **401** Unauthorized | Missing or invalid secret key | Send `Authorization: Bearer sk_test_...` over HTTPS |
| **400** on Initialize Payment | A required field is missing or invalid | Send `reference`, `currency` and `customer.email`, plus `amount` unless you use a `planId` |
| **429** Too Many Requests | Rate limit reached | Wait for the seconds in `Retry-After`. See [Rate limits](https://docs.spotflow.one/api-reference/rate-limits.md) |
| A test card is declined | Using test details with a live key, or the wrong test details | Use your `sk_test_` key and the details on [Testing payments](https://docs.spotflow.one/expert-desk/testing-payments.md) |
| Payment stays `PENDING` | The customer hasn't completed checkout | Finish paying at the `checkoutUrl`, then verify again |
| Retrying a `FAILED` payment fails | A failed payment can't be retried with the same reference | Start a new payment with a new reference |

## Next steps

> [card] [Receive webhooks](https://docs.spotflow.one/developer-resources/webhooks/overview.md)
>
> Get notified when payments, subscriptions and accounts change.

> [card] [Try the API in your browser](https://docs.spotflow.one/api-reference/payments/initialize-collection.md)
>
> Every endpoint page has an interactive playground for test requests.

> [card] [Bill a customer every month](https://docs.spotflow.one/developer-resources/guides/bill-a-customer-every-month.md)
>
> Set up a subscription plan and recurring billing.

> [card] [Go live](https://docs.spotflow.one/expert-desk/verification-process.md)
>
> Complete KYB verification, then switch to your live key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.