curl --request POST \
--url https://{host}/v1/allocations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"account": "1000000001",
"amount_kobo": 5000000
}
'const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({account: '1000000001', amount_kobo: 5000000})
};
fetch('https://{host}/v1/allocations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{host}/v1/allocations"
payload = {
"account": "1000000001",
"amount_kobo": 5000000
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{host}/v1/allocations"
payload := strings.NewReader("{\n \"account\": \"1000000001\",\n \"amount_kobo\": 5000000\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"object": "allocation",
"id": "<string>",
"account": "<string>",
"amount_kobo": 123,
"state": "sending",
"reason": "<string>",
"reject_reason": "invalid_amount",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}{
"object": "allocation",
"id": "<string>",
"account": "<string>",
"amount_kobo": 123,
"state": "sending",
"reason": "<string>",
"reject_reason": "invalid_amount",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}{
"error": {
"type": "authentication_error",
"code": "unauthorized",
"message": "<string>",
"doc_url": "<string>",
"param": "<string>",
"reject_reason": "<string>"
}
}{
"error": {
"type": "authentication_error",
"code": "unauthorized",
"message": "<string>",
"doc_url": "<string>",
"param": "<string>",
"reject_reason": "<string>"
}
}{
"error": {
"type": "authentication_error",
"code": "unauthorized",
"message": "<string>",
"doc_url": "<string>",
"param": "<string>",
"reject_reason": "<string>"
}
}{
"error": {
"type": "authentication_error",
"code": "unauthorized",
"message": "<string>",
"doc_url": "<string>",
"param": "<string>",
"reject_reason": "<string>"
}
}{
"error": {
"type": "authentication_error",
"code": "unauthorized",
"message": "<string>",
"doc_url": "<string>",
"param": "<string>",
"reject_reason": "<string>"
}
}{
"error": {
"type": "authentication_error",
"code": "unauthorized",
"message": "<string>",
"doc_url": "<string>",
"param": "<string>",
"reject_reason": "<string>"
}
}{
"error": {
"type": "authentication_error",
"code": "unauthorized",
"message": "<string>",
"doc_url": "<string>",
"param": "<string>",
"reject_reason": "<string>"
}
}{
"error": {
"type": "authentication_error",
"code": "unauthorized",
"message": "<string>",
"doc_url": "<string>",
"param": "<string>",
"reject_reason": "<string>"
}
}{
"error": {
"type": "authentication_error",
"code": "unauthorized",
"message": "<string>",
"doc_url": "<string>",
"param": "<string>",
"reject_reason": "<string>"
}
}{
"error": {
"type": "authentication_error",
"code": "unauthorized",
"message": "<string>",
"doc_url": "<string>",
"param": "<string>",
"reject_reason": "<string>"
}
}Allocate from your wallet
Moves money from your wallet to the cash balance of one of your accounts at the broker, and it’s booked only once. We reserve the amount in the same step that checks your wallet. If an allocation ends in uncertain, the amount stays reserved and we don’t send it again.
curl --request POST \
--url https://{host}/v1/allocations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"account": "1000000001",
"amount_kobo": 5000000
}
'const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({account: '1000000001', amount_kobo: 5000000})
};
fetch('https://{host}/v1/allocations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{host}/v1/allocations"
payload = {
"account": "1000000001",
"amount_kobo": 5000000
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{host}/v1/allocations"
payload := strings.NewReader("{\n \"account\": \"1000000001\",\n \"amount_kobo\": 5000000\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"object": "allocation",
"id": "<string>",
"account": "<string>",
"amount_kobo": 123,
"state": "sending",
"reason": "<string>",
"reject_reason": "invalid_amount",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}{
"object": "allocation",
"id": "<string>",
"account": "<string>",
"amount_kobo": 123,
"state": "sending",
"reason": "<string>",
"reject_reason": "invalid_amount",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}{
"error": {
"type": "authentication_error",
"code": "unauthorized",
"message": "<string>",
"doc_url": "<string>",
"param": "<string>",
"reject_reason": "<string>"
}
}{
"error": {
"type": "authentication_error",
"code": "unauthorized",
"message": "<string>",
"doc_url": "<string>",
"param": "<string>",
"reject_reason": "<string>"
}
}{
"error": {
"type": "authentication_error",
"code": "unauthorized",
"message": "<string>",
"doc_url": "<string>",
"param": "<string>",
"reject_reason": "<string>"
}
}{
"error": {
"type": "authentication_error",
"code": "unauthorized",
"message": "<string>",
"doc_url": "<string>",
"param": "<string>",
"reject_reason": "<string>"
}
}{
"error": {
"type": "authentication_error",
"code": "unauthorized",
"message": "<string>",
"doc_url": "<string>",
"param": "<string>",
"reject_reason": "<string>"
}
}{
"error": {
"type": "authentication_error",
"code": "unauthorized",
"message": "<string>",
"doc_url": "<string>",
"param": "<string>",
"reject_reason": "<string>"
}
}{
"error": {
"type": "authentication_error",
"code": "unauthorized",
"message": "<string>",
"doc_url": "<string>",
"param": "<string>",
"reject_reason": "<string>"
}
}{
"error": {
"type": "authentication_error",
"code": "unauthorized",
"message": "<string>",
"doc_url": "<string>",
"param": "<string>",
"reject_reason": "<string>"
}
}{
"error": {
"type": "authentication_error",
"code": "unauthorized",
"message": "<string>",
"doc_url": "<string>",
"param": "<string>",
"reject_reason": "<string>"
}
}{
"error": {
"type": "authentication_error",
"code": "unauthorized",
"message": "<string>",
"doc_url": "<string>",
"param": "<string>",
"reject_reason": "<string>"
}
}Authorizations
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
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.
1 - 255^[!-~]+$Body
We reject unknown fields and any field that appears twice, even with different letter case.
Response
This idempotency key was already used for this same allocation, so we didn't send anything new.
"allocation"Unique identifier for the allocation, also used as the broker's reference for the deposit. Starts with alc_.
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.
sending, booked, uncertain, rejected, refused A sentence explaining the allocation's current state. It's for people to read, so don't use it in your logic.
Why the broker rejected the allocation. Set only when state is rejected.
invalid_amount, closed_financial_year, account_not_at_broker, rejected_by_broker, null