# Kori API

## Docs

- [API Reference](https://docs.kori.ml/api-reference.md): Complete reference for every merchant API endpoint.
- [Generate a scoped Bearer token](https://docs.kori.ml/api-reference/authentication/generate-a-scoped-bearer-token.md): Exchange your API key (`X-API-Key`) and secret (`X-API-Secret`) for a JWT Bearer token. Optionally restrict the token to a subset of `scopes` (defaults to `["pay","deposit","balance"]`) and set an expiry between 1 and 720 hours (default 24). Rate limited to 20 requests / 15 minutes.
- [Service status](https://docs.kori.ml/api-reference/authentication/service-status.md): Public health/status probe. No authentication required.
- [Create a beneficiary](https://docs.kori.ml/api-reference/beneficiaries/create-a-beneficiary.md): Save a payout recipient. **Requires scope `beneficiaries`.**
- [Delete (deactivate) a beneficiary](https://docs.kori.ml/api-reference/beneficiaries/delete-deactivate-a-beneficiary.md): **Requires scope `beneficiaries`.**
- [Get a beneficiary](https://docs.kori.ml/api-reference/beneficiaries/get-a-beneficiary.md): **Requires scope `beneficiaries`.**
- [List beneficiaries](https://docs.kori.ml/api-reference/beneficiaries/list-beneficiaries.md): Saved payout recipients. **Requires scope `beneficiaries`.**
- [Update a beneficiary](https://docs.kori.ml/api-reference/beneficiaries/update-a-beneficiary.md): **Requires scope `beneficiaries`.**
- [Add recipients to a draft batch](https://docs.kori.ml/api-reference/bulk-pay/add-recipients-to-a-draft-batch.md): Only draft batches accept new recipients. **Requires scope `bulk_pay`.**
- [Cancel a batch](https://docs.kori.ml/api-reference/bulk-pay/cancel-a-batch.md): **Requires scope `bulk_pay`.**
- [Create a bulk-pay batch](https://docs.kori.ml/api-reference/bulk-pay/create-a-bulk-pay-batch.md): Create a draft batch of disbursements. Up to a fixed maximum number of recipients per batch. **Requires scope `bulk_pay`.**
- [Get a bulk-pay batch](https://docs.kori.ml/api-reference/bulk-pay/get-a-bulk-pay-batch.md): **Requires scope `bulk_pay`.**
- [List bulk-pay batches](https://docs.kori.ml/api-reference/bulk-pay/list-bulk-pay-batches.md): **Requires scope `bulk_pay`.**
- [List recipients in a batch](https://docs.kori.ml/api-reference/bulk-pay/list-recipients-in-a-batch.md): **Requires scope `bulk_pay`.**
- [Process a batch](https://docs.kori.ml/api-reference/bulk-pay/process-a-batch.md): Start disbursing a draft batch. Responds `202`; recipients are paid asynchronously. Requires sufficient balance. **Requires scope `bulk_pay`.**
- [Create a payment link](https://docs.kori.ml/api-reference/payment-links/create-a-payment-link.md): Create a shareable hosted payment page. **Requires scope `payment_links`.**
- [Delete (deactivate) a payment link](https://docs.kori.ml/api-reference/payment-links/delete-deactivate-a-payment-link.md): **Requires scope `payment_links`.**
- [Get a payment link](https://docs.kori.ml/api-reference/payment-links/get-a-payment-link.md): **Requires scope `payment_links`.**
- [List payment links](https://docs.kori.ml/api-reference/payment-links/list-payment-links.md): **Requires scope `payment_links`.**
- [Update a payment link](https://docs.kori.ml/api-reference/payment-links/update-a-payment-link.md): **Requires scope `payment_links`.**
- [Collect a payment from a customer](https://docs.kori.ml/api-reference/payments/collect-a-payment-from-a-customer.md): Initiate a mobile-money **collection**. The provider pushes a prompt to the customer's phone (or, for Wave, returns a hosted `payment_url`). Responds `202` with `status: "pending"` — settlement happens later via webhook/reconciliation. **Requires scope `pay`.**
- [Disburse funds to a customer (top-up)](https://docs.kori.ml/api-reference/payments/disburse-funds-to-a-customer-top-up.md): Send money **to** a customer's mobile-money account, debiting your merchant balance. Unlike `/pay`, a disbursement settles synchronously: `status` is `success` or `failed` in the response. **Requires scope `deposit`.**
- [Get a transaction](https://docs.kori.ml/api-reference/payments/get-a-transaction.md): Retrieve a single transaction by id. **Requires scope `balance`.**
- [Get account balance](https://docs.kori.ml/api-reference/payments/get-account-balance.md): Returns the current merchant balance. **Requires scope `balance`.**
- [List transactions](https://docs.kori.ml/api-reference/payments/list-transactions.md): Paginated transaction history. **Requires scope `balance`.**
- [Approve a pending payout](https://docs.kori.ml/api-reference/payouts/approve-a-pending-payout.md): Approve a payout awaiting approval; funds are then disbursed. **Requires scope `payout`.**
- [Cancel a pending payout](https://docs.kori.ml/api-reference/payouts/cancel-a-pending-payout.md): Cancel a payout that has not yet been processed. **Requires scope `payout`.**
- [Create a payout](https://docs.kori.ml/api-reference/payouts/create-a-payout.md): Withdraw your balance to a mobile-money number or (soon) a bank account. Payouts may require approval depending on your settings. **Requires scope `payout`.**
- [Get a payout](https://docs.kori.ml/api-reference/payouts/get-a-payout.md): Retrieve a single payout by id. **Requires scope `payout`.**
- [List payouts](https://docs.kori.ml/api-reference/payouts/list-payouts.md): Paginated payout history. **Requires scope `payout`.**
- [Get account settings](https://docs.kori.ml/api-reference/settings/get-account-settings.md): **Requires scope `settings`.**
- [Update account settings](https://docs.kori.ml/api-reference/settings/update-account-settings.md): **Requires scope `settings`.**
- [Change a team member's role](https://docs.kori.ml/api-reference/team/change-a-team-members-role.md): **Requires scope `team`.**
- [Get a team member](https://docs.kori.ml/api-reference/team/get-a-team-member.md): **Requires scope `team`.**
- [Invite a team member](https://docs.kori.ml/api-reference/team/invite-a-team-member.md): **Requires scope `team`.**
- [List team members](https://docs.kori.ml/api-reference/team/list-team-members.md): **Requires scope `team`.**
- [Remove a team member](https://docs.kori.ml/api-reference/team/remove-a-team-member.md): **Requires scope `team`.**
- [Delete a webhook](https://docs.kori.ml/api-reference/webhooks/delete-a-webhook.md): **Requires scope `webhooks`.**
- [Get a webhook](https://docs.kori.ml/api-reference/webhooks/get-a-webhook.md): **Requires scope `webhooks`.**
- [List webhook endpoints](https://docs.kori.ml/api-reference/webhooks/list-webhook-endpoints.md): **Requires scope `webhooks`.**
- [Register a webhook endpoint](https://docs.kori.ml/api-reference/webhooks/register-a-webhook-endpoint.md): Register a URL to receive event notifications. Up to 5 endpoints per merchant. Deliveries are signed with `X-Kori-Signature` (HMAC-SHA256 of the raw body, keyed with the returned `secret`). **Requires scope `webhooks`.**
- [Send a test event](https://docs.kori.ml/api-reference/webhooks/send-a-test-event.md): Delivers a sample `test` event to the endpoint. **Requires scope `webhooks`.**
- [Update a webhook](https://docs.kori.ml/api-reference/webhooks/update-a-webhook.md): **Requires scope `webhooks`.**
- [Authentication](https://docs.kori.ml/authentication.md): Exchange your API key and secret for a scoped Bearer token.
- [Errors](https://docs.kori.ml/errors.md): Status codes and error handling.
- [Introduction](https://docs.kori.ml/introduction.md): Accept and disburse mobile-money payments across Mali with the Kori Merchant API.
- [Quickstart](https://docs.kori.ml/quickstart.md): Authenticate and collect your first payment.
- [Scopes](https://docs.kori.ml/scopes.md): What each API key permission grants.
- [Webhooks](https://docs.kori.ml/webhooks.md): Receive real-time notifications for payments, payouts, and more.

## OpenAPI Specs

- [openapi](https://docs.kori.ml/openapi.yaml)