Quickstart

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" }
  }'

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);

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"])

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

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" }
  }'

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);

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"])

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

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

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" }
  }'

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);

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"])

{
  "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 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.

Get your test secret key

In the Spotflow dashboard, 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:

export SPOTFLOW_SECRET_KEY="sk_test_..."

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.

Start a payment

Call Initialize Payment 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, so a retry with the same reference won’t create a second payment.

The response includes a checkoutUrl and a status of pending.

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. Test details only work with test keys.

Verify the payment

Check the result with Verify Payment, using your reference:

curl "https://api.spotflow.co/api/v1/payments/verify?reference=order-1001" \
  -H "Authorization: Bearer $SPOTFLOW_SECRET_KEY"

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());

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.

Don’t poll more than once every 5 seconds. In production, use webhooks 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
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
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

Receive webhooks

Get notified when payments, subscriptions and accounts change.

Try the API in your browser

Every endpoint page has an interactive playground for test requests.

Bill a customer every month

Set up a subscription plan and recurring billing.

Go live

Complete KYB verification, then switch to your live key.

Welcome

Onboard with us

Find your use case

What we support

Test and go live

Before you start

Troubleshooting

Next steps

Receive webhooks

Try the API in your browser

Bill a customer every month

Go live