# Chipper Platform ## Docs - [Introduction](https://docs.platform.chipper.ai/index.md): Payouts, collections, and FX across African rails — bank, mobile money, and stablecoins — through one API. - [Quickstart](https://docs.platform.chipper.ai/quickstart.md): From an API key to a completed payout and its webhook, in about five minutes on sandbox. - [Authentication](https://docs.platform.chipper.ai/authentication.md): Bearer API keys — test and live — with scopes, IP allowlists, and spend caps. - [Sandbox](https://docs.platform.chipper.ai/sandbox.md): A complete, separate stack with simulated money — and deterministic ways to make things fail. - [The rails](https://docs.platform.chipper.ai/concepts/rails.md): Mobile money, bank via virtual accounts, and stablecoins — how each one actually moves money, and what that means for your integration. - [Money & currencies](https://docs.platform.chipper.ai/concepts/money.md): String amounts, zero-decimal currencies, balances, FX, and how rates are locked. - [Idempotency & references](https://docs.platform.chipper.ai/concepts/idempotency.md): externalReference is how you make money-moving calls safe to retry. - [Errors](https://docs.platform.chipper.ai/concepts/errors.md): One envelope, stable codes, and what each one means. - [Lifecycles](https://docs.platform.chipper.ai/concepts/lifecycles.md): The state machines behind payouts, collections, orders, and checkout — and which webhook fires at each step. - [Conventions](https://docs.platform.chipper.ai/concepts/conventions.md): Envelopes, pagination, ids, versioning, and rate limits — the rules that hold across every endpoint. - [Send a payout](https://docs.platform.chipper.ai/guides/send-a-payout.md): Validate, send, and confirm — including cross-currency and crypto destinations. - [Accept payments](https://docs.platform.chipper.ai/guides/accept-payments.md): Three ways money comes in — pull a mobile money charge, give a bank account number, or give a crypto address — and when to use each. - [Payment links & hosted checkout](https://docs.platform.chipper.ai/guides/payment-links.md): Charge anyone with a URL. Chipper hosts the checkout; the payer picks mobile money, bank transfer, or stablecoin. - [Orders](https://docs.platform.chipper.ai/guides/orders.md): Take money in on one rail and pay it out on another — in one call. - [Convert currency](https://docs.platform.chipper.ai/guides/convert-currency.md): Quote, then execute — moving money between two of your own balances at a locked rate. - [Webhooks](https://docs.platform.chipper.ai/guides/webhooks.md): Signed, retried, replayable event delivery — and every event you can subscribe to. - [Going live](https://docs.platform.chipper.ai/guides/going-live.md): From sandbox to real money. - [Building with AI agents](https://docs.platform.chipper.ai/guides/ai-agents.md): Give an agent its own key with a budget it can't exceed — and let it read these docs directly. - [Chipper Platform API Reference](https://docs.platform.chipper.ai/api-reference/introduction.md): Base URLs, authentication, versioning, pagination, and error shapes for the Chipper Platform API. - [Get your organization](https://docs.platform.chipper.ai/api-reference/organization/get-your-organization.md): The organization the calling API key belongs to. Useful as a connectivity check and to confirm which account a key controls. - [List capabilities](https://docs.platform.chipper.ai/api-reference/capabilities/list-capabilities.md): The full method catalog, grouped by country and currency. `payouts` is where you can send money, `collections` is where you can charge customers, and `deposits` lists the stablecoins and chains you can receive on. Every `code` the API accepts (`gh_mtn`, `ng_gtbank`, `usdc_solana`…) comes from this c… - [List capabilities for a country](https://docs.platform.chipper.ai/api-reference/capabilities/list-capabilities-for-a-country.md): Payout and collection methods available in one country. Use this to build a country-specific method picker without filtering the whole catalog client-side. - [Get a payment method](https://docs.platform.chipper.ai/api-reference/capabilities/get-a-payment-method.md): One method with its live status, limits, settlement estimate, and the input `fields` it needs. Check this before creating a recipient or payout on a rail to catch limit or outage problems up front. - [Get an exchange rate](https://docs.platform.chipper.ai/api-reference/rates/get-an-exchange-rate.md): The rate your organization would get right now for converting `origin` into `destination`. It already includes your organization's spread — this is the effective rate applied when a cross-currency payout or conversion executes, not the mid-market rate. Rates refresh every minute; for a rate held for… - [Validate a destination](https://docs.platform.chipper.ai/api-reference/validation/validate-a-destination.md): Resolves the account holder name for bank/mobile-money destinations, checks address format for crypto, and routing numbers where applicable. Validate before creating a payout to catch typos while the money is still yours. - [Validate destinations in bulk](https://docs.platform.chipper.ai/api-reference/validation/validate-destinations-in-bulk.md): Up to 100 per call. - [List recipients](https://docs.platform.chipper.ai/api-reference/recipients/list-recipients.md) - [Create a recipient](https://docs.platform.chipper.ai/api-reference/recipients/create-a-recipient.md): Saves a payout destination. Provide `accountNumber` for fiat rails or `address` (+ optional `tag`) for crypto. The account holder name is resolved via validation where the rail supports it. - [Create recipients in bulk](https://docs.platform.chipper.ai/api-reference/recipients/create-recipients-in-bulk.md): Up to 100 per call. Partial success is normal — check `failed` for rejects. - [Get a recipient](https://docs.platform.chipper.ai/api-reference/recipients/get-a-recipient.md) - [Update a recipient](https://docs.platform.chipper.ai/api-reference/recipients/update-a-recipient.md): Only the display fields are mutable. To change the destination account, create a new recipient. - [Delete a recipient](https://docs.platform.chipper.ai/api-reference/recipients/delete-a-recipient.md): Existing payouts keep their history; the recipient just stops being usable for new ones. - [List payouts](https://docs.platform.chipper.ai/api-reference/payouts/list-payouts.md) - [Create a payout](https://docs.platform.chipper.ai/api-reference/payouts/create-a-payout.md): Sends money to a bank account, mobile money wallet, or crypto address. Amount goes on exactly one side: `to.amount` ("deliver exactly this much") or `from.amount` ("debit exactly this much" — cross-currency converts at the live rate). `externalReference` is your idempotency key: retrying with the sa… - [Get a payout by your reference](https://docs.platform.chipper.ai/api-reference/payouts/get-a-payout-by-your-reference.md): Look up a payout by the externalReference you supplied — useful when you never stored our id. - [Get a payout](https://docs.platform.chipper.ai/api-reference/payouts/get-a-payout.md): Includes `timeline` — the full audit trail: state changes, provider attempts, ledger debits/fees, webhook deliveries. - [List accounts](https://docs.platform.chipper.ai/api-reference/accounts-&-ledger/list-accounts.md): One balance account per currency. Accounts are created automatically the first time money in that currency touches your organization — there is no create endpoint. Not paginated; `hasMore` is always false. - [Get an account](https://docs.platform.chipper.ai/api-reference/accounts-&-ledger/get-an-account.md): Balances are computed from the ledger on every call, so `availableBalance` is what a payout created right now could draw on. - [List an account's ledger entries](https://docs.platform.chipper.ai/api-reference/accounts-&-ledger/list-an-accounts-ledger-entries.md): The statement for one account — the same rows as `GET /v1/ledger?accountNumber=…`, newest first. Every balance change is here, so paging back to the start reproduces `totalBalance` exactly. - [List ledger entries](https://docs.platform.chipper.ai/api-reference/accounts-&-ledger/list-ledger-entries.md): Every entry across all your accounts, exactly as booked, newest first. Filter by `accountNumber` or `currency` for one account, by `type` for e.g. only fees, or by `referenceId` to see everything a single payout or collection touched. `from`/`to` are ISO 8601 timestamps. - [Get a ledger entry](https://docs.platform.chipper.ai/api-reference/accounts-&-ledger/get-a-ledger-entry.md) - [Create a conversion quote](https://docs.platform.chipper.ai/api-reference/conversions/create-a-conversion-quote.md): Locks a rate between two of your balances for 10 minutes. Give the amount on exactly one side: `from.amount` ("sell exactly this much") or `to.amount` ("buy exactly this much"). The quoted `rate` already includes our spread, so `to.amount` is exactly what lands in your balance. Nothing moves until y… - [Get a conversion quote](https://docs.platform.chipper.ai/api-reference/conversions/get-a-conversion-quote.md): Check whether a quote is still `pending` before executing it. A lapsed quote is reported as `expired`. - [List conversions](https://docs.platform.chipper.ai/api-reference/conversions/list-conversions.md) - [Execute a conversion](https://docs.platform.chipper.ai/api-reference/conversions/execute-a-conversion.md): Executes a pending quote: `from.amount` is debited from your `from.currency` balance and `to.amount` is credited to your `to.currency` balance atomically, at the quoted rate. A quote can only be executed once; expired or already-executed quotes are rejected with 400, so request a fresh quote and try… - [Get a conversion](https://docs.platform.chipper.ai/api-reference/conversions/get-a-conversion.md) - [List collections](https://docs.platform.chipper.ai/api-reference/collections/list-collections.md): All inbound money in one list: charges you initiated plus virtual account and crypto deposits. - [Create a collection](https://docs.platform.chipper.ai/api-reference/collections/create-a-collection.md): Charges a payer's mobile money wallet. `from.accountNumber` is the payer's phone number and `from.code` the rail (e.g. `gh_mtn`); the payer gets a prompt on their phone and must approve it, so the collection starts `pending` and finishes `completed` or `failed` — listen for the `collection.completed… - [Get a collection by your reference](https://docs.platform.chipper.ai/api-reference/collections/get-a-collection-by-your-reference.md): Look up a charge by the externalReference you supplied — useful when you never stored our id. - [Get a collection](https://docs.platform.chipper.ai/api-reference/collections/get-a-collection.md): Status is read live from the underlying charge or deposit, so this is safe to poll while a payer approves. - [List virtual accounts](https://docs.platform.chipper.ai/api-reference/virtual-accounts/list-virtual-accounts.md) - [Create a virtual account](https://docs.platform.chipper.ai/api-reference/virtual-accounts/create-a-virtual-account.md): Provisions a dedicated bank account number your customer can transfer into from any bank. Every deposit is credited to your balance in that currency and fires a `collection.completed` webhook — no polling, no manual reconciliation. Typically one per customer: set `externalReference` to your customer… - [Get a virtual account](https://docs.platform.chipper.ai/api-reference/virtual-accounts/get-a-virtual-account.md): To see the deposits into it, list collections with `virtualAccountId`. - [Pause or reactivate a virtual account](https://docs.platform.chipper.ai/api-reference/virtual-accounts/pause-or-reactivate-a-virtual-account.md): Pause an account you no longer want to hand out (a churned customer, suspected abuse) and reactivate it later — the account number never changes, so nothing the customer saved goes stale. - [List crypto addresses](https://docs.platform.chipper.ai/api-reference/crypto-addresses/list-crypto-addresses.md) - [Create a crypto address](https://docs.platform.chipper.ai/api-reference/crypto-addresses/create-a-crypto-address.md): Provisions a deposit address for one asset on one chain (e.g. USDC on Solana). Deposits are credited to your balance in that asset once confirmed and fire a `collection.completed` webhook. Addresses are one per `currency` + `chain` per organization: re-requesting the same pair returns the existing a… - [Get a crypto address](https://docs.platform.chipper.ai/api-reference/crypto-addresses/get-a-crypto-address.md): To see the deposits into it, list collections with `cryptoAddressId`. - [Update a crypto address](https://docs.platform.chipper.ai/api-reference/crypto-addresses/update-a-crypto-address.md): Only `metadata` is mutable — the on-chain address itself is permanent. - [List orders](https://docs.platform.chipper.ai/api-reference/orders/list-orders.md) - [Create an order](https://docs.platform.chipper.ai/api-reference/orders/create-an-order.md): Collect on one rail and pay out on another in a single call — e.g. take USDC on Solana and deliver GHS to an MTN mobile money wallet. Give the amount on exactly one side: `to.amount` ("deliver exactly this much") or `from.amount` ("the customer sends exactly this much"); cross-currency orders lock t… - [Get an order by your reference](https://docs.platform.chipper.ai/api-reference/orders/get-an-order-by-your-reference.md): Look up an order by the externalReference you supplied — useful when you never stored our id. - [Get an order](https://docs.platform.chipper.ai/api-reference/orders/get-an-order.md): Includes `timeline` — every state change across the order and its two legs (the collection and the payout), merged and sorted oldest first. - [List payment pages](https://docs.platform.chipper.ai/api-reference/payment-pages/list-payment-pages.md) - [Create a payment page](https://docs.platform.chipper.ai/api-reference/payment-pages/create-a-payment-page.md): A reusable checkout URL for anyone — a donation page, a product, a top-up. Omit `amount` to let each payer choose. Every payer who starts a checkout gets their own child payment link under the page, so each payment is tracked individually. - [Get a payment page](https://docs.platform.chipper.ai/api-reference/payment-pages/get-a-payment-page.md): To see the individual payments, list payment links with `parentType=payment_page&parentId=`. - [Update a payment page](https://docs.platform.chipper.ai/api-reference/payment-pages/update-a-payment-page.md): Change what the checkout accepts or how it looks. Set `status: "closed"` to stop new checkouts; child links already in progress are unaffected. Amount and currency are fixed — create a new page to change them. - [List payment links](https://docs.platform.chipper.ai/api-reference/payment-links/list-payment-links.md): Includes links spawned by payment pages — filter with `parentType` and `parentId` to see one page's payments. - [Create a payment link](https://docs.platform.chipper.ai/api-reference/payment-links/create-a-payment-link.md): A single-use charge for one customer: their `email` plus a fixed `amount`. Send them the returned `url`; Chipper hosts the checkout (mobile money, bank transfer via virtual account, or stablecoins) and the link moves `active` → `paid`. `customerReference` is your idempotency key — reusing it returns… - [Get a payment link](https://docs.platform.chipper.ai/api-reference/payment-links/get-a-payment-link.md): Includes `sessions` — every checkout attempt the customer made, newest first. A paid link has one `complete` session; abandoned or switched attempts show as `failed` or `expired`. - [Update a payment link](https://docs.platform.chipper.ai/api-reference/payment-links/update-a-payment-link.md): Set `status: "closed"` to void an unpaid link, or adjust `expiresAt`, `redirectUrl` and `branding`. Amount, currency and email are fixed — create a new link to change them. - [List transactions](https://docs.platform.chipper.ai/api-reference/transactions/list-transactions.md): The unified ledger across every balance: payouts, collections, deposits, conversions, fees and refunds, with a running balance per row. Use it for reconciliation instead of stitching the per-resource lists together. - [Get a transaction](https://docs.platform.chipper.ai/api-reference/transactions/get-a-transaction.md) - [Export transactions](https://docs.platform.chipper.ai/api-reference/transactions/export-transactions.md): Everything in a date range (up to 10,000 rows), for accounting. `format=csv` returns a `text/csv` attachment with columns `id,type,reference,amount,runningBalance,currency,description,status,relatedId,createdAt`; add `email` to have the CSV sent as an attachment instead. `format=json` (default) retu… - [List webhook endpoints](https://docs.platform.chipper.ai/api-reference/webhooks/list-webhook-endpoints.md): All endpoints for the organization, newest first. Not paginated — `hasMore` is always false. - [Create a webhook endpoint](https://docs.platform.chipper.ai/api-reference/webhooks/create-a-webhook-endpoint.md): Registers a public https URL to receive events. Event types: `payout.completed`, `payout.failed`, `conversion.completed`, `account.credited`, `collection.pending`, `collection.completed`, `collection.failed`, `order.awaiting_funds`, `order.awaiting_confirmations`, `order.funds_received`, `order.proc… - [Get a webhook endpoint](https://docs.platform.chipper.ai/api-reference/webhooks/get-a-webhook-endpoint.md) - [Delete a webhook endpoint](https://docs.platform.chipper.ai/api-reference/webhooks/delete-a-webhook-endpoint.md): Stops all future deliveries to this URL. Pending deliveries for it are marked failed with `endpoint_unavailable`. - [Update a webhook endpoint](https://docs.platform.chipper.ai/api-reference/webhooks/update-a-webhook-endpoint.md): Change the URL, description or subscriptions, or set `status` to pause (`disabled`) or resume (`active`) delivery. Setting `active` also clears `failureCount` and `disabledReason`, which is how you recover an auto-disabled endpoint. Non-2xx responses and timeouts (10s) are retried at 30s, 2m, 8m, 32… - [Send a test event](https://docs.platform.chipper.ai/api-reference/webhooks/send-a-test-event.md): POSTs a signed `webhook.test` event to the endpoint right now and waits up to 10s for the response, so you can verify your handler and signature check end to end. The attempt is recorded as an event and a delivery like any other, but is never retried. - [Get the signing secret](https://docs.platform.chipper.ai/api-reference/webhooks/get-the-signing-secret.md): Each endpoint has its own secret. Every delivery is signed per [Standard Webhooks](https://www.standardwebhooks.com): headers `webhook-id`, `webhook-timestamp` (unix seconds) and `webhook-signature` (`v1,` over `${id}.${timestamp}.${body}`, keyed with the base64-decoded bytes aft… - [Rotate the signing secret](https://docs.platform.chipper.ai/api-reference/webhooks/rotate-the-signing-secret.md): Replaces the secret immediately — deliveries already in flight were signed with the old one, so update your verifier before rotating. - [List events](https://docs.platform.chipper.ai/api-reference/webhooks/list-events.md): Every event emitted for the organization, whether or not an endpoint was subscribed. Use it to backfill after an outage. - [Get an event](https://docs.platform.chipper.ai/api-reference/webhooks/get-an-event.md): Includes the full payload that was (or would have been) delivered. - [List deliveries](https://docs.platform.chipper.ai/api-reference/webhooks/list-deliveries.md): One delivery per event per subscribed endpoint. Filter by `status: failed` to find what needs a retry. Non-2xx responses and timeouts (10s) are retried at 30s, 2m, 8m, 32m, 2h, 6h, 6h, 6h — about a day — before the delivery is marked failed. After 10 consecutive failed attempts the endpoint is auto-… - [Retry a delivery](https://docs.platform.chipper.ai/api-reference/webhooks/retry-a-delivery.md): Re-sends the delivery with a fresh retry schedule. A failed or pending delivery is reset in place; a successful one is re-sent as a new delivery row so the history is kept. The endpoint must be active. - [List disputes](https://docs.platform.chipper.ai/api-reference/disputes/list-disputes.md): Disputes are opened by Chipper against a completed collection; the disputed amount is held on your balance until resolution. Subscribe to `dispute.created` rather than polling. - [Get a dispute](https://docs.platform.chipper.ai/api-reference/disputes/get-a-dispute.md): Includes the `messages` thread between you and Chipper, oldest first. - [Respond to a dispute](https://docs.platform.chipper.ai/api-reference/disputes/respond-to-a-dispute.md): Only for `open` disputes. `accept` concedes and the held amount is refunded. `contest` moves it to `under_review`; attach evidence as `fileIds` uploaded with purpose `dispute.evidence`, and `reason` is posted as the first message. - [Add a message](https://docs.platform.chipper.ai/api-reference/disputes/add-a-message.md): Post to the dispute thread — follow-up evidence, questions, context. Not allowed once the dispute is `accepted` or `declined`. - [List files](https://docs.platform.chipper.ai/api-reference/files/list-files.md) - [Upload a file](https://docs.platform.chipper.ai/api-reference/files/upload-a-file.md): `multipart/form-data` with a `file` part and a `purpose` text field. The purpose fixes the size and type limits. Purposes and limits: `dispute.evidence` (10MB; image/jpeg, image/png, image/webp, application/pdf); `identity.document` (5MB; image/jpeg, image/png, application/pdf); `identity.selfie` (5… - [List upload purposes](https://docs.platform.chipper.ai/api-reference/files/list-upload-purposes.md): The accepted `purpose` values with their limits, so clients can validate before uploading. - [Get a file](https://docs.platform.chipper.ai/api-reference/files/get-a-file.md): Returns metadata plus a fresh signed `url`. Fetch again when the URL expires rather than storing it. - [List sandbox behaviours](https://docs.platform.chipper.ai/api-reference/simulations/list-sandbox-behaviours.md): Sandbox only — responds 404 on production. An index of every deterministic sandbox behaviour: the POST simulation endpoints below, plus the triggers built into the normal API. Collections and payouts pick their outcome from the last two decimal digits of `amount` (e.g. a payout of `100.01` is reject… - [Fund a balance](https://docs.platform.chipper.ai/api-reference/simulations/fund-a-balance.md): Sandbox only — responds 404 on production. Credits a fiat balance instantly so you can test payouts and conversions without a real inflow. Crypto currencies are rejected. `externalReference` is idempotent: the same value replays the original credit with 200. - [Simulate a virtual account deposit](https://docs.platform.chipper.ai/api-reference/simulations/simulate-a-virtual-account-deposit.md): Sandbox only — responds 404 on production. Pushes a bank transfer into one of your virtual accounts through the real deposit workflow, so the collection, ledger credit and webhooks fire exactly as in production. `outcome: failed` exercises the failure path. Same `externalReference` replays with 200. - [Pay a bank-transfer checkout](https://docs.platform.chipper.ai/api-reference/simulations/pay-a-bank-transfer-checkout.md): Sandbox only — responds 404 on production. Completes a bank-transfer checkout session by depositing into its pooled virtual account. `amount` defaults to the payment link's remaining balance; pass less to test underpayment or more for overpayment. Same `externalReference` replays with 200. - [Changelog](https://docs.platform.chipper.ai/changelog.md): What's new in Chipper Platform — API, dashboard, and checkout. ## OpenAPI Specs - [openapi](https://docs.platform.chipper.ai/api-reference/openapi.json)