> ## Documentation Index > Fetch the complete documentation index at: https://docs.kori.ml/llms.txt > Use this file to discover all available pages before exploring further. # Disburse funds to a customer (top-up) > 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`.** ## OpenAPI ````yaml /openapi.yaml post /merchant/api/deposit openapi: 3.1.0 info: title: Kori Merchant API version: 1.0.0 description: > The Kori Merchant API lets your application collect and disburse mobile-money payments across Mali (Orange Money, Wave, Sama, Moov) and manage payouts, beneficiaries, bulk payments, payment links, your team, webhooks and settings. Every endpoint documented here is reachable with a **merchant API key**. You exchange your API key + secret for a short-lived **Bearer token** scoped to a set of permissions, then call the rest of the API with that token. The scopes you can grant are exactly the ones shown in the **API Keys** screen of your Kori dashboard. ## Authentication flow 1. `POST /merchant/api/auth` with `X-API-Key` and `X-API-Secret` headers. Optionally request a subset of `scopes` and an expiry (`expires_in_hours`, 1–720). 2. Use the returned `data.token` as `Authorization: Bearer ` on every other call. 3. Each endpoint requires a specific scope; a token missing that scope gets `403`. ## Response envelope All responses share the shape `{ "success": boolean, "message"?: string, "request_id"?: string, "data"?: object }`. Errors set `success: false` and a human-readable `message`. ## Asynchronous payments `POST /merchant/api/pay` returns `202` with `status: "pending"` — the customer has only been *prompted*. Wait for the `payment_received` webhook (or poll the transaction) before treating a collection as paid. Never rely on the HTTP response alone to mark an order complete. contact: name: Kori Support url: https://kori.ml servers: - url: https://api.kori.ml description: Production - url: https://dev.kori.ml description: Sandbox / development security: - BearerAuth: [] tags: - name: Authentication description: Exchange your API key + secret for a scoped Bearer token. - name: Payments description: >- Collect from customers (`pay`), disburse (`deposit`), check balance and transactions. - name: Payouts description: Withdraw your balance to mobile money or bank accounts. - name: Beneficiaries description: Saved payout recipients. - name: Payment Links description: Shareable hosted payment pages. - name: Bulk Pay description: Batch disbursements to many recipients. - name: Team description: Manage dashboard team members and roles. - name: Webhooks description: Register endpoints to receive event notifications. - name: Settings description: Merchant account preferences. paths: /merchant/api/deposit: post: tags: - Payments summary: Disburse funds to a customer (top-up) description: > 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`.** requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DepositRequest' responses: '200': description: Deposit processed successfully. content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: data: $ref: '#/components/schemas/TransactionResult' '400': description: Validation error, insufficient balance, or provider failure. content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/DuplicateReference' components: schemas: DepositRequest: type: object required: - amount - payment_method - customer_phone properties: amount: type: number format: float minimum: 0.01 maximum: 1000000 example: 5000 payment_method: $ref: '#/components/schemas/PaymentMethod' currency: type: string default: USD customer_phone: type: string example: '+22370000000' reference: type: string Envelope: type: object properties: success: type: boolean example: true message: type: string request_id: type: string format: uuid TransactionResult: type: object properties: transaction_id: type: integer reference: type: string amount: type: number format: float currency: type: string payment_method: $ref: '#/components/schemas/PaymentMethod' status: $ref: '#/components/schemas/TransactionStatus' payment_url: type: - string - 'null' description: Hosted checkout URL (e.g. Wave); null for USSD push. initiated_at: type: string format: date-time Error: type: object properties: success: type: boolean example: false message: type: string example: Invalid or missing parameter request_id: type: string format: uuid PaymentMethod: type: string description: Mobile-money provider for collections/deposits. enum: - OrangeMoney - Wave - Sama - Moov TransactionStatus: type: string enum: - pending - processing - success - failed - cancelled - reversed - expired responses: Unauthorized: description: Missing, invalid, or expired Bearer token. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Token lacks the required scope (or IP not whitelisted). content: application/json: schema: $ref: '#/components/schemas/Error' DuplicateReference: description: A transaction with this reference already exists. content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - type: object properties: existing_transaction: type: object properties: id: type: integer status: $ref: '#/components/schemas/TransactionStatus' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: Scoped Bearer token from `POST /merchant/api/auth`. ````