curl -X POST https://api.handle.ng/v1/charges/resolve-handle \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"handle": "ayodeji",
"amount": 1500000,
"reference": "ORD-1092"
}'
const res = await fetch('https://api.handle.ng/v1/charges/resolve-handle', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.HANDLE_SECRET_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
handle: 'ayodeji',
amount: 1500000,
reference: 'ORD-1092',
}),
});
const data = await res.json();
{
"status": "success",
"message": "Handle resolved successfully",
"data": {
"customer": {
"handle": "@ayodeji",
"name": "Ayodeji P.",
"avatarUrl": "https://cdn.handle.ng/avatars/ayodeji.png"
},
"availableAuthChannels": [
{ "id": "handle_push", "name": "Handle App Push Notification", "isRecommended": true },
{ "id": "handle_qr", "name": "Scan Dynamic QR Code" }
],
"linkedBanks": [
{
"bankId": "bnk_gtb_01",
"bankName": "Guaranty Trust Bank",
"bankCode": "058",
"accountNumberMasked": "******4819",
"mandateStatus": "ACTIVE"
}
]
}
}
Charges
Resolve Handle
Look up customer by @handle and retrieve active mandate banks
POST
/
v1
/
charges
/
resolve-handle
curl -X POST https://api.handle.ng/v1/charges/resolve-handle \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"handle": "ayodeji",
"amount": 1500000,
"reference": "ORD-1092"
}'
const res = await fetch('https://api.handle.ng/v1/charges/resolve-handle', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.HANDLE_SECRET_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
handle: 'ayodeji',
amount: 1500000,
reference: 'ORD-1092',
}),
});
const data = await res.json();
{
"status": "success",
"message": "Handle resolved successfully",
"data": {
"customer": {
"handle": "@ayodeji",
"name": "Ayodeji P.",
"avatarUrl": "https://cdn.handle.ng/avatars/ayodeji.png"
},
"availableAuthChannels": [
{ "id": "handle_push", "name": "Handle App Push Notification", "isRecommended": true },
{ "id": "handle_qr", "name": "Scan Dynamic QR Code" }
],
"linkedBanks": [
{
"bankId": "bnk_gtb_01",
"bankName": "Guaranty Trust Bank",
"bankCode": "058",
"accountNumberMasked": "******4819",
"mandateStatus": "ACTIVE"
}
]
}
}
Request Body
string
required
The customer’s Handle (e.g.
ayodeji or @ayodeji) or registered phone number.integer
required
The charge amount in Kobo (e.g.
1500000 = ₦15,000).string
required
A unique merchant-generated order reference to prevent duplicate billing.
Response
string
Returns
success or error.object
curl -X POST https://api.handle.ng/v1/charges/resolve-handle \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"handle": "ayodeji",
"amount": 1500000,
"reference": "ORD-1092"
}'
const res = await fetch('https://api.handle.ng/v1/charges/resolve-handle', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.HANDLE_SECRET_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
handle: 'ayodeji',
amount: 1500000,
reference: 'ORD-1092',
}),
});
const data = await res.json();
{
"status": "success",
"message": "Handle resolved successfully",
"data": {
"customer": {
"handle": "@ayodeji",
"name": "Ayodeji P.",
"avatarUrl": "https://cdn.handle.ng/avatars/ayodeji.png"
},
"availableAuthChannels": [
{ "id": "handle_push", "name": "Handle App Push Notification", "isRecommended": true },
{ "id": "handle_qr", "name": "Scan Dynamic QR Code" }
],
"linkedBanks": [
{
"bankId": "bnk_gtb_01",
"bankName": "Guaranty Trust Bank",
"bankCode": "058",
"accountNumberMasked": "******4819",
"mandateStatus": "ACTIVE"
}
]
}
}