Glossary

The terms that recur across the Bachs docs, in alphabetical order. Each one links to the page that explains it in full.

​

A

​

Account verification

The one-time review your account goes through before you can take real payments and withdraw. It covers your product, your identity and your withdrawal account, and most reviews finish within 48 hours. See Create and verify your account.

​

Acting as an account

Sending a request on behalf of a connected account by adding its id in the X-Account-Id header. Your platform still uses its own API key; the header decides whose balance, charge or payout the request affects. See Acting as an account.

​

API key

The secret key you send in the Authorization header of every API request. It tells Bachs which organization is calling and in which environment: a sk_sandbox_ key works only in the sandbox, and a sk_live_ key works only in live. See API keys and authentication.

​

Automatic payouts

A schedule that pays out your settled customer collections to your default payout destination, for example every day or every week. You set it for each balance currency, and it does not pay out top-ups, transfers you received or conversions. See Set up automatic payouts.

​

B

​

Balance

The money Bachs holds for you, with one balance for each currency. A new charge first sits in your pending balance, and only your available balance can fund payouts and transfers. A balance cannot go below zero, except after a lost dispute. See Balances.

​

Balance currency

A currency you can hold money in. Today these are USD and NGN, and USD is always held. A payment in any other currency converts into a currency you hold when it reaches your balance. See Supported currencies.

​

C

​

Capability

Permission for a connected account to do one thing with money, such as payouts or transfers. Each capability belongs to a configuration, merchant for accepting payments or recipient for receiving money, and it stays inactive until its requirements are met. See Capabilities.

​

Charge

The record of one payment from your customer. Its status, such as open, succeeded or failed, tells you where the payment stands and whether to fulfil the order. See Payment statuses.

​

Checkout session

A request to collect a payment. It ties a price to a customer and returns a hosted checkout_url, where Bachs shows the payment methods and takes the payment. You send your customer to that URL and wait for the webhook. See Accept a payment with Checkout.

​

Collection

A payment your customer makes to you. Payment events use this name, for example collection.succeeded, and the money collected is held in your Bachs balance. See Set up webhooks.

​

Collection currency

A currency your customer can pay in at checkout. Which currencies are available depends on the payment method, and this set is different from the currencies you can hold or withdraw. See Supported currencies.

​

Connect

The Bachs product for platforms, also called sub accounts. You create an account for each business or person who sells through you or gets paid by you, and you move money between those accounts and your own. See Connect.

​

Connected account

A financial identity you create for a seller, creator or contractor through Connect. It has its own balance, capabilities and requirements, and you control it; the person behind it does not sign up for Bachs. See Accounts.

​

Conversion

Changing money from one currency to another. A payment in a currency you do not hold converts into one you do as it reaches your balance. See Supported currencies.

​

Customer

The record of one buyer, which groups their payments, subscriptions and saved payment methods. Bachs creates a customer the first time someone completes a payment, matched by email, or you can create one yourself. See Manage customers.

​

Customer portal

A hosted page where your customers manage their own billing. Depending on the settings you choose, they can view or cancel subscriptions, switch plans, read past invoices and update their card. See Set up the customer portal.

​

D

​

Destination charge

A split payment where the sale belongs to your platform. You create the checkout as yourself and name the connected account in transfer_data.destination; the money lands in your balance, and the seller’s share moves to the account at settlement. See Destination charges.

​

Direct charge

A split payment where the sale belongs to the connected account. You create the checkout as the account with X-Account-Id, the money lands in its balance, and your platform fee comes to you. See Direct charges.

​

Dispute

A customer’s request to their bank or card network to reverse a payment, also called a chargeback. You can respond with evidence until the dispute’s response_deadline_at, and the evidence decides whether it ends in your favour. See Handle disputes.

​

E

​

Event

A record of something that happened in your account, such as collection.succeeded or payout.failed. Bachs sends events to your webhook endpoints. Every event has an id, which you use to ignore a delivery you have already handled. See Set up webhooks.

​

I

​

Idempotency key

A value you send in the Idempotency-Key header on a POST or PATCH request, so that a retry of the same operation does not run it twice. Use one key for one operation, and reuse it only to retry that operation. See Idempotency.

​

Invoice

The bill Bachs opens for each billing period of a subscription. Bachs charges your customer’s saved card for it, and invoice.* events tell you whether it was paid. See How subscriptions work.

​

L

​

Live

The Bachs environment where real money moves, also called production. It uses the base URL https://api.bachs.io and sk_live_ keys, which you get after account verification. See How Bachs works.

​

O

​

Onboarding

Collecting a connected account’s requirements so its capabilities can turn on. You send the account a hosted link, or you build the forms yourself and submit the information through the API. See Onboarding.

​

P

​

Payment method

The way your customer pays at checkout: card, bank transfer, mobile money or crypto. Every method is in the same checkout, and your customer sees only the ones that fit their currency and location. See Pay-ins and withdrawals.

​

Payment recovery

What Bachs does when a subscription renewal charge fails. The subscription moves to past_due, Bachs retries the charge three times over about nine days and emails your customer a link to update their card. If every retry fails, the subscription is canceled or marked unpaid, depending on your setting. See Recover failed payments.

​

Payout

Moving money from your Bachs balance to your own bank account or wallet. A payout that Bachs has accepted is not yet complete: wait for payout.paid or payout.failed. The dashboard calls a payout a withdrawal. See Payouts.

​

Payout destination

A bank account or wallet you save to receive payouts. It must belong to the account holder and be approved and usable before Bachs can send money to it. You can save more than one and choose a destination for each payout. See How payouts work.

​

Platform fee

Your platform’s cut of a connected account’s sale, sent as platform_fee on the checkout. It comes out of the account’s share, not out of the Bachs processing fee, and it is always an amount, never a percentage. See Platform fees.

​

Processing fee

The fee Bachs takes from each payment. The rate depends on the payment method and the currency your customer paid in, and every payment shows the fee that was applied to it. See Fees.

​

Product

One thing you sell, with a name, a price and a currency. Its price is fixed, free, or custom, where the customer chooses the amount. A product with a billing_cycle is recurring and is sold as a subscription; a product without one is a one-time purchase. See Create and manage products.

​

Proration

How Bachs settles the price difference when a subscription changes in the middle of a billing period. The customer is charged or credited for the exact time left, and proration_behavior decides whether that happens now, at the next renewal, or not at all. See How proration works.

​

Q

​

Quote

A fixed exchange rate and fixed amounts, valid until its expires_at time. You create a quote before a payout in another currency, then send its quote_id to carry it out. See Supported currencies.

​

R

​

Refund

Money returned to your customer from a payment you collected, in full or in part. A payment can take one refund, and a refund.* webhook tells you the result. See Issue a refund.

​

Requirement

Information a connected account must provide, and Bachs must accept, before a capability turns on. The capabilities you request decide which requirements apply, so request only what the account needs. See Requirements.

​

S

​

Sandbox

A separate Bachs environment where payments are simulated and no real money moves. It has its own base URL, keys and data, and it works the same way as live, so you can test every flow before your account is verified. See Test your integration.

​

Scope

A permission on an API key, written as <resource>:<action>, such as payments:read. A key can only call the endpoints its scopes allow, so give each key only the scopes it needs. See API keys and authentication.

​

Settlement

The point at which the money from a charge becomes available to move. A charge first sits in your pending balance and moves to your available balance on settlement, and your balance shows the date for each pending amount. See How money moves.

​

Split payment

One charge that is divided between your platform and the connected account that earned it. The customer pays once, and the split happens as the charge settles. It comes in two shapes: a direct charge and a destination charge. See Split payments.

​

Sub account

Another name for a connected account. See Connected account.

​

Subscription

The ongoing relationship between one customer and one recurring product. It starts when the customer completes a checkout and renews at the end of each billing cycle until you or the customer cancel it. See How subscriptions work.

​

T

​

Transfer

A move of money from one available balance to another, between your platform and a connected account, in either direction. It happens at once, uses one currency and cannot be reversed; to get the money back you send a transfer in the other direction. See Transfers.

​

Trial

A free period at the start of a subscription. Your customer’s card is saved at checkout but not charged until the trial ends. You add a trial to a product with trial_period. See Offer a free trial.

​

V

​

Virtual account

A permanent NGN bank account number for your account or for a connected account. Anyone can pay into it by bank transfer at any time, and each deposit becomes a payment in your balance that you match to a customer yourself. See Accept bank transfers with a virtual account.

​

W

​

Webhook

A POST request Bachs sends to your server when an event happens. Check its X-Bachs-Signature with your endpoint’s signing secret before you trust it, and use the webhook, not the redirect, as the signal to fulfil an order. See Set up webhooks.

​

Withdrawal

The name the dashboard uses for a payout. See Payout.

​

Withdrawal currency

A currency you can send to your own bank account or wallet. This set is separate from the currencies you collect and the currencies you hold, and international bank and mobile money withdrawals are paid from your USD balance. See Supported currencies.