Create a charge

curl --request POST \
  --url https://api.bachs.io/v1/charges \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer": "cust_1a2b3c4d5e6f",
  "amount": "29.00",
  "currency": "USD",
  "description": "April usage",
  "reference": "INV-2026-04-881"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customer: 'cust_1a2b3c4d5e6f',
    amount: '29.00',
    currency: 'USD',
    description: 'April usage',
    reference: 'INV-2026-04-881'
  })
};

fetch('https://api.bachs.io/v1/charges', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.bachs.io/v1/charges"

payload = {
    "customer": "cust_1a2b3c4d5e6f",
    "amount": "29.00",
    "currency": "USD",
    "description": "April usage",
    "reference": "INV-2026-04-881"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bachs.io/v1/charges"

	payload := strings.NewReader("{\n  \"customer\": \"cust_1a2b3c4d5e6f\",\n  \"amount\": \"29.00\",\n  \"currency\": \"USD\",\n  \"description\": \"April usage\",\n  \"reference\": \"INV-2026-04-881\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "payment_id": "ch_389305e973a841cc",
  "status": "processing",
  "amount": "30.85",
  "amount_paid": "0.00",
  "amount_remaining": "30.85",
  "currency": "USD",
  "fees": {
    "amount": "1.85",
    "currency": "USD"
  },
  "payment_method": "CARD",
  "checkout_id": null,
  "narration": "April usage",
  "reference": "INV-2026-04-881",
  "billing_reason": "purchase",
  "customer": {
    "name": "Jane Doe",
    "email": "jane@example.com"
  },
  "created_at": "2026-04-27T12:05:00.000Z",
  "updated_at": "2026-04-27T12:05:00.000Z"
}

{
  "detail": "Invalid request parameters",
  "error_code": "VALIDATION_ERROR",
  "errors": [
    {
      "field": "amount",
      "message": "Amount must be a positive decimal string",
      "type": "value_error"
    }
  ]
}

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

{
  "detail": "API key does not have permission for this operation",
  "error_code": "FORBIDDEN"
}

{
  "detail": "Resource not found",
  "error_code": "NOT_FOUND"
}

{
  "detail": "Rate limit exceeded. Please retry after a few seconds.",
  "error_code": "TOO_MANY_REQUESTS"
}

{
  "detail": "An unexpected error occurred. Please try again later.",
  "error_code": "INTERNAL_SERVER_ERROR"
}

Payments

Create a charge

In beta. This endpoint might change, including field names and the shape of the response. Pin your integration to what you test.

Charge a customer’s saved card off-session, meaning with nobody on a payment page. Use this for money a customer agreed to once and you collect later, such as a usage invoice or a top-up. An off-session charge cannot ask the customer to authenticate, so a card whose issuer demands it is refused.

The card must have been saved on an earlier checkout. See Charge a saved card.

This always answers with a payment, never an error, when the card is refused: a refusal is an outcome you read from status. The payment is usually processing, and the result reaches you as a collection.succeeded or collection.failed webhook. A card refused while the request is still open comes back already failed. A 201 is not payment received.

Send an Idempotency-Key header. Without one, a retry after a timeout charges the customer twice.

POST

charges

Create a charge

curl --request POST \
  --url https://api.bachs.io/v1/charges \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer": "cust_1a2b3c4d5e6f",
  "amount": "29.00",
  "currency": "USD",
  "description": "April usage",
  "reference": "INV-2026-04-881"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    customer: 'cust_1a2b3c4d5e6f',
    amount: '29.00',
    currency: 'USD',
    description: 'April usage',
    reference: 'INV-2026-04-881'
  })
};

fetch('https://api.bachs.io/v1/charges', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.bachs.io/v1/charges"

payload = {
    "customer": "cust_1a2b3c4d5e6f",
    "amount": "29.00",
    "currency": "USD",
    "description": "April usage",
    "reference": "INV-2026-04-881"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.bachs.io/v1/charges"

	payload := strings.NewReader("{\n  \"customer\": \"cust_1a2b3c4d5e6f\",\n  \"amount\": \"29.00\",\n  \"currency\": \"USD\",\n  \"description\": \"April usage\",\n  \"reference\": \"INV-2026-04-881\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "payment_id": "ch_389305e973a841cc",
  "status": "processing",
  "amount": "30.85",
  "amount_paid": "0.00",
  "amount_remaining": "30.85",
  "currency": "USD",
  "fees": {
    "amount": "1.85",
    "currency": "USD"
  },
  "payment_method": "CARD",
  "checkout_id": null,
  "narration": "April usage",
  "reference": "INV-2026-04-881",
  "billing_reason": "purchase",
  "customer": {
    "name": "Jane Doe",
    "email": "jane@example.com"
  },
  "created_at": "2026-04-27T12:05:00.000Z",
  "updated_at": "2026-04-27T12:05:00.000Z"
}

{
  "detail": "Invalid request parameters",
  "error_code": "VALIDATION_ERROR",
  "errors": [
    {
      "field": "amount",
      "message": "Amount must be a positive decimal string",
      "type": "value_error"
    }
  ]
}

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

{
  "detail": "API key does not have permission for this operation",
  "error_code": "FORBIDDEN"
}

{
  "detail": "Resource not found",
  "error_code": "NOT_FOUND"
}

{
  "detail": "Rate limit exceeded. Please retry after a few seconds.",
  "error_code": "TOO_MANY_REQUESTS"
}

{
  "detail": "An unexpected error occurred. Please try again later.",
  "error_code": "INTERNAL_SERVER_ERROR"
}

Authorizations

Authorization

string

header

required

Bearer token authentication. Pass your API key as Authorization: Bearer sk_.... See Authentication for keys, scopes, and sandbox vs production.

Body

application/json

customer

string

required

The customer to charge, by their cust_ id. They must already have a saved card, or the request is refused with NO_SAVED_PAYMENT_METHOD.

amount

string

required

The amount to collect, as a decimal string (for example "29.00"). Must be greater than zero. This is the amount before the processing fee: when your account passes the fee to the customer, the card is charged more than this and the response amount shows the total.

currency

string

required

The currency of amount, in ISO 4217 format (for example USD). Your account must be able to collect card payments in this currency, or the request is refused with PAYMENT_METHOD_NOT_ENABLED.

payment_method

string | null

The saved card to charge, by its pm_ id. Omit to charge the customer's default saved card, which is the first card they saved. A card belonging to a different customer is refused with SAVED_PAYMENT_METHOD_NOT_FOUND.

description

string | null

What the charge is for. Returned as narration on the payment, and shown on your dashboard.

Maximum string length: 255

reference

string | null

Your own identifier for this charge, returned unchanged on the payment so you can match it to your records.

Maximum string length: 128

metadata

object | null

Key-value pairs you attach to the charge and get back on the payment and its webhooks.

Response

Success - Charge created and submitted to the card

Detailed payment response for API integrations.

payment_id

string

required

Unique identifier for the payment.

Example:

"pay_1a2b3c4d5e"

status

enum<string>

required

Current status of the payment. created: the charge exists and no attempt has succeeded yet. processing: an attempt is in flight and is being verified. succeeded: the payment is confirmed and settled in full. accepted: an underpayment or overpayment was accepted as final settlement. failed: the payment failed and no funds were captured. expired: the payment window elapsed before any payment arrived. cancelled: cancelled before completion. refunded: the full amount was returned to the customer. partially_refunded: part of the amount was returned to the customer. auto_refunded: we automatically returned the full amount to the customer. underpaid: the customer paid less than the amount owed. overpaid: the customer paid more than the amount owed.

Available options:

created,

processing,

succeeded,

accepted,

failed,

expired,

cancelled,

refunded,

partially_refunded,

auto_refunded,

underpaid,

overpaid

Example:

"succeeded"

amount

string

required

Requested amount in currency.

Example:

"10.00"

currency

string

required

Payment currency code.

Example:

"USD"

created_at

string<date-time>

required

Creation timestamp.

Example:

"2026-04-27T12:00:00Z"

updated_at

string<date-time>

required

Last update timestamp.

Example:

"2026-04-27T12:00:05Z"

reference

string | null

Checkout reference when available.

Example:

"order_9876"

billing_reason

enum<string>

Why this payment exists. purchase: a one-time purchase. subscription_create: the first cycle of a new subscription. subscription_cycle: a subscription renewal. subscription_update: an off-cycle charge from a mid-cycle plan change (proration).

Available options:

purchase,

subscription_create,

subscription_cycle,

subscription_update

Example:

"purchase"

checkout_id

string | null

Checkout identifier, when linked.

Example:

"chk_8T9u0V1w2X3y4Z5a"

is_refundable

boolean | null

Whether this payment can currently be refunded.

Example:

true

amount_paid

string | null

Amount received so far.

Example:

"10.00"

amount_remaining

string | null

Remaining amount still expected.

Example:

"0.00"

fee_usd

string | null

Processing fee for this payment, converted to USD and expressed as a decimal string. null until the payment settles.

Example:

"0.59"

fees

object | null

The processing fee on this payment, in the currency it was charged in. Prefer this over fee_usd when the payment was not collected in USD: fee_usd is a conversion of the same fee, this is the amount actually taken. null on a payment that carries no processing fee. See Fees.

Show child attributes

merchant_bears_cost

boolean | null

Whether merchant bears processing cost.

Example:

true

platform_fee

string | null

What the platform took out of this sale, beside the gross it was taken from, in the base currency of the sale. null when the charge carried no platform fee, and on a charge that split the sale with transfer_data.amount instead. See Platform fees.

Example:

null

destination_amount

string | null

The seller's contracted share of this sale, in the base currency of the sale. Null on a charge that carries no split, and on one that split the sale with platform_fee instead.

Example:

null

fee_paid_by

enum<string> | null

Who Bachs's processing fee actually came from on this charge, read back from the ledger posting rather than a flag decided in advance. merchant: the fee came out of the charge. platform: the platform's own balance covered it. On a destination charge this never reads platform; the fee always comes from the charge there. See Processing fees.

Available options:

merchant,

platform

Example:

"merchant"

payment_method

string | null

Payment method used for this payment. For every method except card, this is the exact corridor collected, such as NGN_BANK_TRANSFER, MOMO_GHS, or CRYPTO. Card charges report CARD rather than USD_CARD or NGN_CARD; read the currency to tell which card corridor collected it.

Example:

"NGN_BANK_TRANSFER"

channel

string | null

Origin channel (for example api).

Example:

"checkout"

narration

string | null

payment description/narration.

Example:

"Pro plan"

General

Checkout Sessions

Connected Accounts

Products

Subscriptions

Customers

Customer sessions

Payments

Refunds

Payouts

Payout Destinations

Balance

Media

Misc

Transfers

Persons

Platform Fees

Reference

Create a charge

Authorizations

Body

Response