curl --request GET \
--url https://{host}/v1/allocations/{id} \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://{host}/v1/allocations/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{host}/v1/allocations/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://{host}/v1/allocations/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"object": "allocation",
"id": "alc_4hn7vz2qe6wk3pma5rtd",
"account": "1000000001",
"amount_kobo": 5000000,
"state": "booked",
"reason": null,
"reject_reason": null,
"created_at": "2026-09-25T06:07:15Z",
"updated_at": "2026-09-25T06:07:15Z"
}{
"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>"
}
}Retrieve an allocation
Returns the allocation’s current state.
curl --request GET \
--url https://{host}/v1/allocations/{id} \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://{host}/v1/allocations/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://{host}/v1/allocations/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://{host}/v1/allocations/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"object": "allocation",
"id": "alc_4hn7vz2qe6wk3pma5rtd",
"account": "1000000001",
"amount_kobo": 5000000,
"state": "booked",
"reason": null,
"reject_reason": null,
"created_at": "2026-09-25T06:07:15Z",
"updated_at": "2026-09-25T06:07:15Z"
}{
"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.
Path Parameters
The allocation's id.
Response
An allocation.
"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 balance. 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