Skip to main content

Wallet

Business accounts pay from a prepaid Naira wallet. Booking a delivery debits the quote total, and cancelling while the delivery's cancellable is true refunds it in full. Reeds never collects money at the door: the rider collects nothing from the receiver, and Reeds doesn't offer cash on delivery.

Get the wallet​

GET /wallet returns the balance and billing mode.

curl https://api.getreeds.co/shipping/v1/wallet \
  -H "Authorization: Bearer $REEDS_ACCESS_TOKEN"
Response 200, prepaid
{
  "status": "success",
  "data": {
    "livemode": true,
    "balance": 5000000,
    "currency": "NGN",
    "billing_mode": "prepaid",
    "low_balance_threshold": 500000,
    "credit": null
  }
}

Amounts are in kobo, so 5000000 is ₦50,000.

An account on monthly invoicing gets billing_mode: "invoice" and an extra credit block:

Response 200, invoice account
{
  "status": "success",
  "data": {
    "livemode": true,
    "balance": 0,
    "currency": "NGN",
    "billing_mode": "invoice",
    "low_balance_threshold": null,
    "credit": {
      "limit": 50000000,
      "unbilled": 12000000,
      "unpaid_invoices": 8000000,
      "available": 30000000
    }
  }
}

Fund the wallet​

POST /wallet/fund with an amount in kobo returns a Paystack payment_url. Open it, or send whoever pays for your Reeds account there. It is not for your own customers. It requires an Idempotency-Key header.

curl -X POST https://api.getreeds.co/shipping/v1/wallet/fund \
  -H "Authorization: Bearer $REEDS_ACCESS_TOKEN" \
  -H "Idempotency-Key: fund-2026-10-26-001" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 5000000 }'
Response 201
{
  "status": "success",
  "data": {
    "amount": 5000000,
    "currency": "NGN",
    "payment_url": "https://checkout.paystack.com/...",
    "reference": "fund-8f3a1c7e5b2d4a6f9e0c"
  }
}
  • This works in Live mode only. In Test mode use POST /sandbox/wallet/fund; a test token gets 409 ACTION_NOT_ALLOWED.
  • The amount is from ₦1,000 (100000) to ₦100,000,000 (10000000000). Anything else gets 422 INVALID_REQUEST.
  • Your credentials act for the account, not for a person: any live credentials can start a top-up, and Paystack sends the receipt to the account Owner's email. (In the dashboard, only an Owner or Admin can fund the wallet.)
  • Reeds pays Paystack's fee. The wallet is credited the full amount paid.
  • When the money lands, Reeds sends a wallet.funded webhook with the same reference, so you can match it to the top-up you started. It also carries the amount, the new balance and the wallet transaction.
  • Invoice accounts have no wallet to fund: 409 ACTION_NOT_ALLOWED.

How bookings use the wallet​

  • Booking (POST /deliveries, POST /deliveries/{id}/book) debits the quote total in one wallet transaction. It can't be applied twice.
  • Cancelling while cancellable is true refunds the full amount to the wallet.

When the balance is short​

If the wallet doesn't cover the total, booking returns 402:

Response 402
{
  "status": "failed",
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "The wallet balance does not cover this delivery",
    "doc_url": "https://developer.getreeds.co/errors/INSUFFICIENT_BALANCE"
  }
}

Fund the wallet, then retry the same request with the same Idempotency-Key. A 402 releases the key, so the retry runs normally and can't create a second delivery. See Idempotency.

For a draft created with auto_book: true, there is no error. The draft gets a FUND_WALLET required action, and Reeds books it automatically once the wallet is funded. See Drafts and required actions.

Transactions​

GET /wallet/transactions lists debits and credits, newest first, each linked to its delivery. It is paginated; see Pagination.

curl "https://api.getreeds.co/shipping/v1/wallet/transactions?limit=20" \
  -H "Authorization: Bearer $REEDS_ACCESS_TOKEN"

Low-balance alerts​

Set a low-balance threshold in the dashboard under Wallet. When a debit takes the balance to or below it, Reeds sends the wallet.low_balance webhook and emails the account's Owners and Admins (in Test mode, the webhook only). It is sent once, and again only after the balance has recovered past the threshold plus a margin (₦1,000 or 10% of the threshold, whichever is more) and fallen again. See Events.

Closing an account​

Once your deliveries have finished and nothing is owed, Reeds pays the remaining balance out to a bank account in the business's verified name, and the wallet is closed. Test balances are discarded.

Next steps​