Custom Checkout (Server-to-Server)

Overview

Custom checkout (ui_mode: "custom") is for headless / server-to-server flows where you render the entire payment experience yourself instead of redirecting to Bachs’s hosted page. You drive the flow through a small set of endpoints on a single checkout resource, and Bachs returns the instructions the customer must act on (a bank account to transfer into, a mobile-money prompt, or a crypto address). Use custom checkout when:

You’re building a custom or embedded payment experience inside your app
You want full control over the UI and branding
You’re building a native mobile integration

Non-card methods only. Custom checkout supports bank transfer, mobile money, and crypto. Card is not supported here (it requires client-side card capture / PCI handling). For cards, use standard hosted checkout.
Access is gated. To enable custom checkout in production, email hello@bachs.io to discuss your use case.

This flow replaces the deprecated one-shot POST /v1/payments/whitelabel endpoint. Instead of one call, you now use a small, explicit lifecycle on /v1/checkout-sessions/{id}, which gives you a stable checkout id, a payment_status you can branch on, and price locking. See Migrating from /v1/payments/whitelabel.

The flow

Create the checkout

POST /v1/checkout-sessions with ui_mode: "custom". Returns a checkout_id. No hosted URL is returned. You render everything.

Set the payment method & get a price

PATCH /v1/checkout-sessions/{id} with the chosen method + currency. Bachs prices it, locks that price for a short window, and returns the amount, fee, and rate to show the customer.

Confirm

POST /v1/checkout-sessions/{id}/confirm when the customer commits. Returns a next_step describing what the customer must do (transfer, approve, or submit an OTP).

Advance (if needed)

For OTP flows, POST /v1/checkout-sessions/{id}/next with the OTP. Bank transfer and STK-push flows skip this.

Poll or receive a webhook

GET /v1/checkout-sessions/{id} returns the live payment_status, or subscribe to webhooks for automatic updates.

Authentication

Type: API Key (required)

Header	Required	Description
`Authorization`	Yes	Format: `Bearer sk_sandbox_...` or `Bearer sk_live_...`
`Content-Type`	Yes	Must be `application/json`

Scope required: payments:write (for create / patch / confirm / next), payments:read (for the status GET).

Step 1: Create the checkout

POST /v1/checkout-sessions

{
  "ui_mode": "custom",
  "pricing": { "base_currency": "USD", "amount": "100.00" },
  "customer": { "email": "user@example.com", "name": "Jane Doe" },
  "payment_method_types": ["NGN_BANK_TRANSFER", "MOMO_GHS"],
  "reference": "order_789"
}

View request fields

string

required

Set to custom for the server-to-server flow. (standard returns a hosted URL; embedded is reserved for future use.)

object

Raw pricing. Supply exactly one pricing source: pricing, or product_cart / line_items (products).

string

Merchant base currency (e.g. USD, NGN).

string

Amount in the base currency.

array

Existing product IDs + quantities. Alternative to pricing.

array

Inline product details created on the fly (hidden from your catalog). Alternative to pricing.

object

required

Either { "customer_id": "cust_..." } for an existing customer, or { "email": "...", "name": "..." } to create one.

array

Restrict which corridors this checkout accepts (e.g. NGN_BANK_TRANSFER, MOMO_GHS, CRYPTO). Any card corridor (USD_CARD, NGN_CARD) is rejected for custom. See Restrict payment methods for the full corridor list.

string

Your idempotent client reference (unique per organization).

object

Custom metadata (max 20 keys, 10KB).

Response

{
  "checkout_id": "chk_4P5q6R7s8T9u0V1w",
  "ui_mode": "custom",
  "status": "open",
  "source_type": "API",
  "amount": "100.00",
  "currency": "USD",
  "reference": "order_789",
  "checkout_url": null,
  "client_secret": null,
  "products": null,
  "created_at": "2026-07-08T10:00:00.000Z"
}

checkout_url is null for custom checkouts: there is no hosted page. You own the UI. Keep the checkout_id; every following step targets it.

Step 2: Set the payment method & lock a price

PATCH /v1/checkout-sessions/{checkout_id}

{
  "payment_method": "NGN_BANK_TRANSFER",
  "currency": "NGN",
  "payment_rail": "bank_transfer_ng"
}

View request fields

string

required

An exact non-card corridor: NGN_BANK_TRANSFER, a mobile-money corridor (e.g. MOMO_GHS), or CRYPTO.

string

required

The currency the customer pays in (e.g. NGN, GHS, USDT_TRC20).

string

Optional. The specific network/rail (e.g. mtn_momo_gh). If omitted, Bachs auto-selects the default rail for the method + currency. See Discovering rails.

Response

{
  "checkout_id": "chk_4P5q6R7s8T9u0V1w",
  "status": "requires_confirmation",
  "payment_method": "NGN_BANK_TRANSFER",
  "payment_rail": "bank_transfer_ng",
  "currency": "NGN",
  "amount": "151250.00",
  "base_amount": "150000.00",
  "processing_fee": "1250.00",
  "exchange_rate": "1500.00",
  "quote_expires_at": "2026-07-08T10:02:00.000Z"
}

string

The total the customer will pay (base + fee, where the customer bears it). Show this number to the customer.

string

Fee amount. 0 when your organization absorbs the fee.

string|null

FX rate used. 1.0 for same-currency payments (e.g. NGN → NGN).

string

When the locked price lapses. Confirm before this to guarantee the shown price. See Price locking & expiry.

You don’t manage a quote_id. PATCH prices the checkout and holds that price internally. Confirm only references the checkout, and the price is honored automatically within the window.

Step 3: Confirm (initiate payment)

Call this when the customer clicks “Pay”. This is the point where money starts moving.

POST /v1/checkout-sessions/{checkout_id}/confirm

{
  "phone_number": "+2348012345678"
}

View request fields

string

Required for mobile money. The customer’s wallet number.

string

Optional. Provide payment_method + currency (the same exact-corridor values as PATCH) to price and confirm in one call (skipping PATCH).

string

Optional. Required only if you skipped PATCH.

string

Optional / advanced. Omit it to use the locked price from PATCH.

string

Sandbox only. success, failed, or underpaid.

Response

{
  "checkout_id": "chk_4P5q6R7s8T9u0V1w",
  "charge_id": "ch_9f8e7d6c5b4a3928",
  "status": "requires_action",
  "payment_method": "NGN_BANK_TRANSFER",
  "currency": "NGN",
  "amount": 151250,
  "next_step": {
    "type": "display_instructions",
    "bank_account": {
      "account_name": "Bachs Collections",
      "account_number": "9876543210",
      "bank_name": "Access Bank",
      "bank_code": "044",
      "expires_at": "2026-07-08T10:30:00.000Z",
      "reference": "order_789",
      "payment_reference": "pay_ref_123"
    },
    "poll_url": "/v1/checkout-sessions/chk_4P5q6R7s8T9u0V1w",
    "expires_at": "2026-07-08T10:30:00.000Z"
  }
}

The response always carries a next_step: the single, typed object that tells you what to render next.

The `next_step` object

next_step is discriminated by type. Key on it to know which payload is populated and what the customer must do:

`type`	What it means	Payload populated
`display_instructions`	Show the customer where/how to pay	`bank_account` or `crypto`
`approve_on_phone`	An STK push was sent; customer approves on device	`mobile_money`
`submit_otp`	Collect an OTP and call `/next`	`mobile_money`
`poll`	Nothing to render; poll for the result	None
`done`	Terminal; read `payment_status`	None

Every next_step also includes a poll_url (where to read status) and an expires_at.

bank_account (display_instructions)

{
  "account_name": "Bachs Collections",
  "account_number": "9876543210",
  "bank_name": "Access Bank",
  "bank_code": "044",
  "expires_at": "2026-07-08T10:30:00.000Z",
  "reference": "order_789",
  "payment_reference": "pay_ref_123"
}

string

Account the customer transfers into.

string

Destination account name.

string

Destination bank.

string

Bank identifier code.

string

The reference for this payment, for reconciliation and support queries. Display it prominently.

mobile_money (approve_on_phone / submit_otp)

{
  "network": "mtn_momo_gh",
  "phone_number": "+233200123456",
  "action": "enter_otp",
  "instruction": "Enter the OTP sent to your mobile number to continue.",
  "auth_model": "OTP",
  "expires_at": "2026-07-08T10:30:00.000Z",
  "reference": "order_789",
  "payment_reference": "pay_ref_123"
}

string

enter_otp or approve_on_phone.

string|null

OTP, STK_PROMPT, etc. When OTP, next_step.type is submit_otp.

string

Human-readable instruction to display.

string

The mobile money rail handling the payment.

crypto (display_instructions)

{
  "asset": "USDT",
  "network": "TRC20",
  "wallet_address": "TXY7GhbJ9kLmN3oPqR5sTuV8wXyZ1aB2cD",
  "qr_code": "https://example.com/qr.png",
  "expires_at": "2026-07-08T10:30:00.000Z",
  "reference": "order_789",
  "payment_reference": "pay_ref_123"
}

string

Destination wallet the customer sends to.

string

Digital asset to send (e.g. USDT).

string

Blockchain network required.

string|null

URL to a QR code image, if available.

Step 4: Advance a payment (`/next`)

Only needed for OTP flows (next_step.type: "submit_otp"). Bank transfer and STK-push flows go straight to polling.

POST /v1/checkout-sessions/{checkout_id}/next

{ "action": "submit_otp", "otp": "123456" }

View request fields

string

required

submit_otp, resend_otp, or resend_stk.

string

Required when action is submit_otp. The OTP the customer received.

Response

{
  "checkout_id": "chk_4P5q6R7s8T9u0V1w",
  "status": "processing",
  "next_step": { "type": "poll", "poll_url": "/v1/checkout-sessions/chk_4P5q6R7s8T9u0V1w" }
}

Returns the next next_step. Keep advancing until type is poll or done.

Step 5: Poll the status

GET /v1/checkout-sessions/{checkout_id}

{
  "checkout_id": "chk_4P5q6R7s8T9u0V1w",
  "status": "open",
  "payment_status": "processing",
  "source_type": "API",
  "amount": "100.00",
  "currency": "USD",
  "payment_method": "NGN_BANK_TRANSFER",
  "charge": { "charge_id": "ch_9f8e7d6c5b4a3928", "status": "processing", "amount": "151250" }
}

Read payment_status for the customer-facing lifecycle, and charge.status for the underlying charge. Prefer webhooks over polling where possible.

`payment_status` lifecycle

A status derived from the checkout and its charge/attempt:

Status	Meaning
`requires_payment_method`	No method chosen yet (call `PATCH`)
`requires_confirmation`	Method set + price locked (call `confirm`)
`requires_action`	Customer must act (transfer, approve, or submit OTP)
`processing`	Awaiting rail confirmation
`succeeded`	Payment confirmed
`failed`	Payment failed
`canceled`	Checkout canceled

Price locking & expiry

PATCH locks the price it returns for a short window (quote_expires_at). Behavior at confirm:

Within the window → the locked price is honored.
After the window → Bachs re-prices at current rates. If the total hasn’t changed, confirm proceeds. If it has changed, confirm returns 409 CHECKOUT_PRICE_CHANGED with the new amount. A fresh price is already locked, so show the customer the new amount and confirm again.

{
  "detail": "The quoted price expired and has changed. Show the customer the new amount and confirm again.",
  "error_code": "CHECKOUT_PRICE_CHANGED",
  "details": { "amount": "151800.00", "currency": "NGN", "previous_amount": "151250.00" }
}

To refresh proactively, call PATCH again. It returns the current price and resets the lock. For FX-sensitive flows, always render the amount from the latest PATCH/confirm response rather than a value you cached earlier.

Discovering payment rails

payment_rail is optional. Omit it and Bachs auto-selects the default rail for the method + currency. To show the customer a choice of networks (mobile money) or banks, list the available rails:

GET /v1/payment-methods/rails?payment_method=MOBILE_MONEY&currency=GHS&country_code=GH

Returns the rails (id, name) you can present. See List Payment Rails. Bank transfer via virtual accounts and crypto typically have no meaningful rail to choose, so skip the picker.

Which methods and currencies your account can accept is configured during onboarding. There is no per-checkout discovery endpoint for enabled methods.

Example: end-to-end (bank transfer, NGN)

Sample.js

const BASE = "https://api.bachs.io";
const headers = {
  Authorization: "Bearer sk_live_abc123xyz...",
  "Content-Type": "application/json",
};

// 1. Create the custom checkout
const create = await fetch(`${BASE}/v1/checkout-sessions`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    ui_mode: "custom",
    pricing: { base_currency: "USD", amount: "100.00" },
    customer: { email: "user@example.com", name: "Jane Doe" },
    payment_method_types: ["NGN_BANK_TRANSFER"],
    reference: "order_789",
  }),
}).then((r) => r.json());

// 2. Price it: show the customer NGN 151,250
const priced = await fetch(`${BASE}/v1/checkout-sessions/${create.checkout_id}`, {
  method: "PATCH",
  headers,
  body: JSON.stringify({ payment_method: "NGN_BANK_TRANSFER", currency: "NGN" }),
}).then((r) => r.json());

displayAmount(priced.amount, priced.currency); // "151250.00" NGN

// 3. Customer clicks Pay → confirm
const confirmed = await fetch(
  `${BASE}/v1/checkout-sessions/${create.checkout_id}/confirm`,
  { method: "POST", headers, body: JSON.stringify({}) },
).then((r) => r.json());

// 4. Render the bank details from next_step
const acct = confirmed.next_step.bank_account;
displayBankInstructions({
  bank: acct.bank_name,
  accountNumber: acct.account_number,
  amount: confirmed.amount,
  paymentReference: acct.payment_reference,
});

// 5. Poll (or use webhooks) until succeeded
const status = await fetch(`${BASE}/v1/checkout-sessions/${create.checkout_id}`, {
  headers,
}).then((r) => r.json());
// status.payment_status === "processing" | "succeeded" | ...

For mobile money with OTP, add a step between 4 and 5:

// next_step.type === "submit_otp"
await fetch(`${BASE}/v1/checkout-sessions/${create.checkout_id}/next`, {
  method: "POST",
  headers,
  body: JSON.stringify({ action: "submit_otp", otp: userEnteredOtp }),
});

Errors

400 Bad Request

Validation or state errors, e.g. a card corridor (USD_CARD, NGN_CARD) on a custom checkout, missing payment_method, or an explicitly supplied expired quote_id.

{ "detail": "Quote expired or not found. Please get a new quote.", "error_code": "BAD_REQUEST" }

409 Price Changed

The locked price expired and moved. Show the new amount (in details) and confirm again. A fresh price is already locked.

{
  "detail": "The quoted price expired and has changed. Show the customer the new amount and confirm again.",
  "error_code": "CHECKOUT_PRICE_CHANGED",
  "details": { "amount": "151800.00", "currency": "NGN", "previous_amount": "151250.00" }
}

401 Unauthorized

{ "detail": "Invalid API key", "error_code": "UNAUTHORIZED" }

Testing

In sandbox (sk_sandbox_...), pass simulated_outcome on confirm to control the final result:

Create + price + confirm

Run the flow with sk_sandbox_... keys.

Force an outcome

Include "simulated_outcome": "success" (or failed / underpaid) on the confirm call.

Observe status

Poll GET /v1/checkout-sessions/{id} or receive the webhook for the simulated result.

Migrating from `/v1/payments/whitelabel`

The old one-shot POST /v1/payments/whitelabel endpoint has been removed. Map it to the new lifecycle:

Old (one-shot whitelabel)	New (custom checkout)
`POST /v1/payments/whitelabel` with `quote_id`	`POST /v1/checkout-sessions` → `PATCH` → `POST .../confirm`
You manage a `quote_id` (30s TTL)	The price is locked on the checkout; no `quote_id` juggling
Response envelope `{ status, message, data }`	`confirm` returns `{ charge_id, payment_status, next_step }`
`data.bank_account` / `data.mobile_money` / …	`next_step.bank_account` / `next_step.mobile_money` / `next_step.crypto`
OTP via `POST /v1/payments/charges/mobile-money/authorize`	`POST /v1/checkout-sessions/{id}/next` with `action: submit_otp`
Poll `GET .../charges/{id}/status`	`GET /v1/checkout-sessions/{id}` (`payment_status` + `charge`)

Card was never supported by whitelabel, and still isn’t here.

List Payment Rails: discover rails for a method + currency
Get Charge Status: charge-level status
Webhook Events: receive payment updates automatically

Get Started

Products & pricing

Subscriptions

Customer portal

Payments

Payouts

Dashboard

Developer Portal

CLI

For You and Your Customers

Custom Checkout (Server-to-Server)

Overview

The flow

Authentication

Step 1: Create the checkout

Response

Step 2: Set the payment method & lock a price

Response

Step 3: Confirm (initiate payment)

Response

The `next_step` object

Step 4: Advance a payment (`/next`)

Response

Step 5: Poll the status

`payment_status` lifecycle

Price locking & expiry

Discovering payment rails

Example: end-to-end (bank transfer, NGN)

Errors

Testing

Migrating from `/v1/payments/whitelabel`

​Overview

​The flow

​Authentication

​Step 1: Create the checkout

​Response

​Step 2: Set the payment method & lock a price

​Response

​Step 3: Confirm (initiate payment)

​Response

​The next_step object

​Step 4: Advance a payment (/next)

​Response

​Step 5: Poll the status

​payment_status lifecycle

​Price locking & expiry

​Discovering payment rails

​Example: end-to-end (bank transfer, NGN)

​Errors

​Testing

​Migrating from /v1/payments/whitelabel

​Related endpoints

Overview

The flow

Authentication

Step 1: Create the checkout

Response

Step 2: Set the payment method & lock a price

Response

Step 3: Confirm (initiate payment)

Response

The `next_step` object

Step 4: Advance a payment (`/next`)

Response

Step 5: Poll the status

`payment_status` lifecycle

Price locking & expiry

Discovering payment rails

Example: end-to-end (bank transfer, NGN)

Errors

Testing

Migrating from `/v1/payments/whitelabel`

Related endpoints