Bachs - PayKit

npm install @paykit-sdk/core @paykit-sdk/bachs

Bachs is a hosted-checkout-first payments and billing platform for African internet businesses selling globally (docs.bachs.io).

Setup

Environment variables
Direct config

import { PayKit } from '@paykit-sdk/core';
import { bachs } from '@paykit-sdk/bachs';

export const paykit = new PayKit(bachs());

Required env vars:

BACHS_API_KEY=sk_sandbox_...
BACHS_SANDBOX=true

The key’s prefix decides sandbox vs live, and overrides isSandbox if the two disagree.

import { PayKit } from '@paykit-sdk/core';
import { createBachs } from '@paykit-sdk/bachs';

export const paykit = new PayKit(
  createBachs({
    apiKey: 'sk_sandbox_...',
    isSandbox: true,
  }),
);

Creating a checkout

Products (and their prices) live in your Bachs product catalog. item_id is a Bachs product_id. Bachs resolves the amount/currency from the product itself, so you don’t pass either:

const checkout = await paykit.checkouts.create({
  customer: { email: 'jane@example.com' }, // or { id: 'cust_...' } for an existing customer
  item_id: 'prod_abc123',
  quantity: 1,
  session_type: 'one_time',
  success_url: 'https://shop.example.com/thanks',
  cancel_url: 'https://shop.example.com/cart',
  metadata: { order_id: 'ORD-9876' },
});

// Redirect the customer to checkout.payment_url

If prod_abc123 has a billing_cycle configured on Bachs, completing this same checkout creates a subscription automatically. You’ll get both a payment.succeeded and a subscription.created webhook.

Creating a payment directly

Same underlying flow, mapped onto Payment. Needs success_url in provider_metadata since Bachs still redirects the customer even for a direct payment:

const payment = await paykit.payments.create({
  customer: { email: 'jane@example.com' },
  amount: 50, // informational only - Bachs resolves the real amount from the product
  currency: 'USD',
  item_id: 'prod_abc123',
  capture_method: 'automatic', // Bachs captures automatically, no manual step
  provider_metadata: {
    success_url: 'https://shop.example.com/thanks',
    cancel_url: 'https://shop.example.com/cart', // optional
  },
});

payment.id (and checkout.id) is Bachs’ checkout_id for the lifetime of the payment. Keep using this same checkout_id for paykit.payments.retrieve and paykit.refunds.create.

Safe retries

paykit.checkouts.create and paykit.payments.create each make two calls under the hood: create the session, then fetch it back to resolve pricing. If your own code might retry the whole call, pass a stable idempotencyKey (your own order ID works well) so a retry returns the original session instead of creating a duplicate:

await paykit.checkouts.create({
  // ...
  provider_metadata: { idempotencyKey: `order-${order.id}` },
});

paykit.refunds.create supports the same option.

Customers

Full support except delete, Bachs has no endpoint for it:

const customer = await paykit.customers.create({
  email: 'jane@example.com',
  name: 'Jane Doe',
  billing: null,
});

await paykit.customers.update(customer.id, { name: 'Jane D.' });

Subscriptions

Bachs has no direct way to create a subscription. Create one by calling paykit.checkouts.create with a recurring-configured product instead. Retrieve, update, and cancel work directly:

const subscription =
  await paykit.subscriptions.retrieve('sub_1a2b3c4d5e');

await paykit.subscriptions.update('sub_1a2b3c4d5e', {
  metadata: {},
  provider_metadata: { product_id: 'prod_xyz456' }, // move to a different plan
});

await paykit.subscriptions.cancel('sub_1a2b3c4d5e'); // cancels immediately

Refunds

await paykit.refunds.create({
  payment_id: 'chk_1a2b3c4d5e', // the checkout_id
  amount: 29,
  reason: 'Customer request',
  metadata: null,
});

The payment must have actually succeeded. Refunding a checkout that hasn’t been paid throws ResourceNotFoundError.

Webhooks

Add a webhook endpoint from your Bachs Developer Portal and pass its signing secret to webhookSecret:

const webhook = paykit.webhooks
  .setup({ webhookSecret: process.env.BACHS_WEBHOOK_SECRET! }) // whsec_...
  .on('payment.succeeded', async event => {})
  .on('payment.failed', async event => {})
  .on('payment.updated', async event => {})
  .on('subscription.created', async event => {})
  .on('subscription.updated', async event => {})
  .on('subscription.canceled', async event => {})
  .on('refund.created', async event => {})
  .on('customer.created', async event => {})
  .on('customer.updated', async event => {});

await webhook.handle({
  body: await request.text(),
  headersAsObject: Object.fromEntries(request.headers),
  fullUrl: request.url,
});

Raw Bachs events

Opt into any native Bachs event type, typed against Bachs’ payload:

paykit.webhooks
  .setup({ webhookSecret: process.env.BACHS_WEBHOOK_SECRET! })
  .on('bachs.payout.paid', async event => {
    // event.data is the raw Bachs payload
  });

All available raw events and their PayKit mappings:

Raw event	PayKit event
`bachs.collection.succeeded`	`payment.succeeded`
`bachs.collection.failed`	`payment.failed`
`bachs.collection.abandoned`	`payment.failed`
`bachs.collection.underpaid`	`payment.updated`
`bachs.refund.created`	`refund.created`
`bachs.refund.paid`	`refund.created`
`bachs.refund.failed`	`refund.created`
`bachs.customer.subscription.created`	`subscription.created`
`bachs.customer.subscription.updated`	`subscription.updated`
`bachs.customer.subscription.deleted`	`subscription.canceled`
`bachs.customer.created`	`customer.created`
`bachs.customer.updated`	`customer.updated`
`bachs.payout.*`	(raw only)
`bachs.invoice.*`	(raw only)
`bachs.dispute.*`	(raw only)
`bachs.conversion.*`	(raw only)

​Setup

​Creating a checkout

​Creating a payment directly

​Safe retries

​Customers

​Subscriptions

​Refunds

​Webhooks

​Raw Bachs events