Payouts API

The Payouts API withdraws money from your organization's Seev balance to a mobile money recipient, initiated by your own server rather than from the Dashboard. It is the programmatic counterpart to the Dashboard Send Money flow. A payout debits your balance the moment you create it, so the request is authorized with a payments:write key and every create must carry an Idempotency-Key.

This page assumes you already hold a key. If you do not, create one first in API Keys, and read Idempotency before you send money.

Scope and limits at launch

Check your balance before a payout

Read your balance first so a payout is not rejected for insufficient funds. The balance endpoint is authorized with a payments:read key.

curl "https://api.seevplus.com/api/v1/merchants/balance" \
  -H "Authorization: Bearer $SEEV_API_KEY"

{
  "total_deposits": 5000.0,
  "total_withdrawals": 1200.0,
  "total_fees": 38.0,
  "total_merchant_fees": 12.0,
  "available_balance": 3750.0,
  "pending_balance": 100.0,
  "paid_settlements": 0.0,
  "reserved_settlements": 0.0,
  "currency": "GHS",
  "transaction_count": 42,
  "balance_source": "wallet"
}

Check that available_balance covers your payout amount plus the withdrawal fee before you create the payout. Because available_balance already excludes funds held by earlier in-flight payouts, reading it immediately before each payout is the reliable way to avoid a 422 INSUFFICIENT_BALANCE.

Create a payout

Send the request from your server with an Idempotency-Key. The amount is in the currency's smallest unit, and the merchant is charged the withdrawal fee on top of the amount, so your available balance must cover amount + merchant fee.

curl -X POST "https://api.seevplus.com/api/v1/merchants/payouts" \
  -H "Authorization: Bearer $SEEV_API_KEY" \
  -H "Idempotency-Key: payout_order_123_attempt_1" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "channel": "mobile_money",
    "recipient": {
      "name": "Kwame Asante",
      "phone": "0551234567",
      "network": "MTN"
    }
  }'

A successful create returns 202 Accepted. The payout is now processing; the funds are already reserved against your balance, and the transfer resolves asynchronously (see Follow a payout to completion).

Request headers

Request body

Read a payout response

Create, get, and list all return the same payout object. It carries the status, the amount, and the fee breakdown you are charged, and it deliberately omits the upstream provider name, provider reference, and raw provider payloads.

{
  "id": "3f1c9a2e-...",
  "reference": "PAY-20260915-3f1c9a2e-...",
  "type": "payout",
  "env": "production",
  "status": "processing",
  "currency": "GHS",
  "amount": 10000,
  "final_amount": 10000,
  "channels": ["mobile_money"],
  "phone": "0551234567",
  "network": "MTN",
  "recipient": { "name": "Kwame Asante", "phone": "0551234567" },
  "transactions": [
    {
      "id": "b8e0...",
      "channel": "mobile_money",
      "status": "processing",
      "amount": 10000,
      "currency": "GHS",
      "gross_amount": 10000,
      "fee_amount": 100,
      "net_amount": 9900,
      "fee_bearer": "merchant",
      "customer_fee": 0,
      "merchant_fee": 100,
      "failure_reason": "",
      "created_at": "2026-09-15T10:12:00Z",
      "updated_at": "2026-09-15T10:12:00Z"
    }
  ],
  "expires_at": null,
  "completed_at": null,
  "created_at": "2026-09-15T10:12:00Z",
  "updated_at": "2026-09-15T10:12:00Z"
}

The transactions[] entries expose the fee math you are charged (gross_amount, fee_amount, net_amount, merchant_fee, customer_fee, fee_bearer) and a failure_reason when a transfer fails. In the withdraw direction the recipient absorbs the customer-borne portion of the fee, and only the merchant-borne fee is added to what your balance must cover.

Follow a payout to completion

A payout create returns 202 and a processing status. The transfer itself completes asynchronously, and Seev resolves the payout when the provider confirms the result. Poll the payout by reference, or wait for the corresponding webhook, rather than treating the 202 as proof the money arrived.

curl "https://api.seevplus.com/api/v1/merchants/payouts/PAY-20260915-3f1c9a2e-..." \
  -H "Authorization: Bearer $SEEV_API_KEY"

List payouts

Fetch a paginated history for the authenticated organization, newest first.

curl "https://api.seevplus.com/api/v1/merchants/payouts?limit=20&offset=0" \
  -H "Authorization: Bearer $SEEV_API_KEY"

The response wraps the payout objects with a total count:

{
  "payouts": [ { "reference": "PAY-...", "status": "completed" } ],
  "total": 42
}

Fix a rejected payout

Errors return a code and a message. Branch on the HTTP status; the message is a human-readable detail for your logs, not a stable contract.

Check before you send money in production

• Send a stable Idempotency-Key on every create, derived from your own order or payout intent plus an attempt counter.
• Read GET /api/v1/merchants/balance and confirm available_balance covers amount + merchant fee, converting for the major-unit difference.
• Send the recipient fields mobile money requires: phone and network.
• Treat the 202 as "accepted", not "paid". Confirm completed by polling the reference or handling the webhook before you tell anyone the recipient was paid.
• Never create a replacement while a payout is still processing.
• Store the payout reference against your own record for reconciliation.

Related docs

• Send Money
• Developer API Keys
• Developer Transactions
• Developer Webhooks
• Idempotency
• Errors and codes