Fund an account

You fund a customer’s account in two moves: you pay into your wallet, and then you allocate from your wallet to the account. The customer can trade once the allocation is booked.

1. Pay into your wallet

Pay by bank transfer. There’s no API call for this step. We send you the bank, account name, account number and your payer reference by email from partners@matambaintelligence.com when we set up your live access. They don’t change. Put your payer reference in each transfer’s narration, so we know the payment is yours. If anyone asks you to pay into a different account, don’t pay: confirm it with us first, at the address on Get access and support, never at one given in the request. We credit your wallet the same business day we confirm your payment as received, during support hours: 9:00 to 17:00 West Africa Time (WAT), Monday to Friday. There’s no event for a credit, so look for it in GET /v1/wallet/transfers. In the sandbox there’s no bank. Your sandbox wallet opens with ₦10,000,000.00 of test money when we set up your sandbox access, credited once. For more, ask us. It’s a credit in GET /v1/wallet/transfers, with a bank_reference that starts with SANDBOXOPENINGCREDIT. A restart of the sandbox doesn’t reset your wallet.

2. Find the credit

The credit adds to credited_kobo and available_kobo on GET /v1/wallet, and appears in GET /v1/wallet/transfers as an entry of type credit:

Credit entry

{
  "object": "wallet_transfer",
  "id": "wtr_1",
  "type": "credit",
  "amount_kobo": 100000000,
  "available_change_kobo": 100000000,
  "allocation": null,
  "account": null,
  "bank_reference": "100004260924101500000123456789",
  "created_at": "2026-09-24T09:30:00Z"
}

bank_reference is the bank’s own reference for your transfer: for an instant transfer, its session ID, the long number on your transfer receipt; for another kind of transfer, the reference on your bank’s receipt. It’s different for every transfer, and it’s shown in capitals with only its letters and digits. Match your payments to credits by it. We credit each bank reference once, however often the transfer is reported to us, so a payment is never counted twice. If a payment doesn’t appear, send us its date, its amount and the bank’s reference.

3. Allocate to the account

Send POST /v1/allocations with the account and the amount, and a new Idempotency-Key:

POST /v1/allocations
Authorization: Bearer $KEY
Content-Type: application/json
Idempotency-Key: alloc-0001

{
  "account": "$ACCOUNT",
  "amount_kobo": 5000000
}

curl -X POST https://$HOST/v1/allocations \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: alloc-0001" \
  --data-binary @- <<EOF
{
  "account": "$ACCOUNT",
  "amount_kobo": 5000000
}
EOF

Response

HTTP/1.1 201 Created

{
  "object": "allocation",
  "id": "alc_4hn7vz2qe6wk3pma5rtd",
  "account": "$ACCOUNT",
  "amount_kobo": 5000000,
  "state": "booked",
  "reason": null,
  "reject_reason": null,
  "created_at": "2026-09-25T06:07:15Z",
  "updated_at": "2026-09-25T06:07:15Z",
  "client_reference": null
}

We reserve the amount in your wallet, then send the allocation to the broker once. booked means the amount is in the account’s balance at the broker, and you also receive an allocation.booked event. Read the balance with GET /v1/accounts/{account}/balance.

Response	What to do
`201` with `state` `booked`	Nothing. The customer can trade.
`201` with `state` `uncertain`	Wait. The amount stays reserved while it is reconciled with the broker. See Handle an uncertain result.
`503 outcome_not_recorded`	Its outcome was not recorded. Retrieve the allocation the error’s `allocation` names until it resolves. Don’t send it again under a new key.
The allocation still reads `sending` after your request has ended	Its outcome was not recorded. We send a `201`, `403 feature_not_enabled`, `422 allocation_rejected` or `503 allocation_not_sent` only once the outcome is recorded, so this never follows one of them. The amount stays reserved, and another allocation to the same account for the same amount is refused until it resolves. Don’t send it again under a new key. Our operations team reconciles it with the broker, and it becomes `booked`, or `rejected` with `reject_reason` `not_booked` and the amount returned to your wallet. See Identical allocations.
`422 allocation_rejected`	Act on its `reject_reason`. The amount has been returned to your wallet.
`422 wallet_too_low`	Pay in more, then send it again. Nothing was stored, so you can reuse the key.
`503 allocation_not_sent`	Send it again with a new key. The amount has been returned to your wallet.
`409 similar_allocation_unresolved`	Nothing was stored. Retrieve the allocation the error’s `allocation` names until it resolves. If it becomes `booked`, the account is funded: send yours again with the same key only if it is a separate allocation, not a repeat of that one. If it becomes `rejected`, send yours again with the same key. See Identical allocations.

Every other refusal, and whether each one stored your key, is in Idempotency.

Check your wallet adds up

available_kobo always equals credited_kobo minus allocated_kobo minus reserved_kobo, and the available_change_kobo of every ledger entry adds up to available_kobo. See Wallet for what each figure and each entry means.

Get started

Concepts

How-to

Reference

1. Pay into your wallet

2. Find the credit

3. Allocate to the account

Check your wallet adds up

​1. Pay into your wallet

​2. Find the credit

​3. Allocate to the account

​Check your wallet adds up

1. Pay into your wallet

2. Find the credit

3. Allocate to the account

Check your wallet adds up