Skip to main content
POST
Allocate from your wallet

Authorizations

Authorization
string
header
required

Authorization: Bearer <key>. Sandbox keys start with mgw_test_ and live keys start with mgw_live_. Each key works only in its own environment, and a live key works only from the IP addresses or ranges registered for it.

Headers

Idempotency-Key
string
required

A key you choose to identify this request. Send the same key every time you retry the request. Once used, a key stays tied to that request permanently. It must be printable ASCII with no spaces, and we compare it byte for byte. Send the header only once.

Required string length: 1 - 255
Pattern: ^[!-~]+$

Body

application/json

We reject unknown fields and any field that appears twice, even with different letter case.

account
string
required

An account code. Case-insensitive on input, and returned in uppercase.

Pattern: ^[A-Za-z0-9]{1,64}$
amount_kobo
integer<int64>
required

The amount in kobo, as a whole number. At most ₦100,000,000.

Required range: 1 <= x <= 10000000000

Response

This idempotency key was already used for this same allocation, so we didn't send anything new.

object
string
required
Allowed value: "allocation"
id
string
required

Unique identifier for the allocation, also used as the broker's reference for the deposit. Starts with alc_.

account
string
required
amount_kobo
integer<int64>
required
state
enum<string>
required

sending: reserved, and the send is in progress. booked: the broker booked it into the account's cash. uncertain: we don't know whether the broker booked it. The amount stays reserved, we don't send it again, and we reconcile it with the broker. rejected: the broker rejected it, and the amount is returned to your wallet. refused: it never reached the broker, and the amount is returned to your wallet.

Available options:
sending,
booked,
uncertain,
rejected,
refused
reason
string | null
required

A sentence explaining the allocation's current state. It's for people to read, so don't use it in your logic.

reject_reason
enum<string> | null
required

Why the broker rejected the allocation. Set only when state is rejected.

Available options:
invalid_amount,
closed_financial_year,
account_not_at_broker,
rejected_by_broker,
null
created_at
string<date-time>
required
updated_at
string<date-time>
required