curl -X POST https://api.handle.ng/v1/charges/dispatch \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"reference": "ORD-1092",
"authChannel": "handle_push",
"description": "Nike Air Max at SneakerHub"
}'
const res = await fetch('https://api.handle.ng/v1/charges/dispatch', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.HANDLE_SECRET_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
reference: 'ORD-1092',
authChannel: 'handle_push', // or 'handle_qr'
description: 'Nike Air Max at SneakerHub',
}),
});
const { data } = await res.json();
if (data.status === 'SUCCESS') {
// Case 2: Instant Auto-Debit paid immediately
console.log('Payment successful via Auto-Debit:', data.paidAt);
} else if (data.status === 'PENDING_AUTHORIZATION') {
// Case 1: Biometric Push prompt sent to customer phone
console.log('Customer will approve on Handle app with FaceID:', data.expiresAt);
}
import requests
import os
url = "https://api.handle.ng/v1/charges/dispatch"
headers = {
"Authorization": f"Bearer {os.getenv('HANDLE_SECRET_KEY')}",
"Content-Type": "application/json"
}
payload = {
"reference": "ORD-1092",
"authChannel": "handle_push",
"description": "Nike Air Max at SneakerHub"
}
response = requests.post(url, json=payload, headers=headers).json()
data = response.get("data", {})
if data.get("status") == "SUCCESS":
print("Auto-Debit completed instantly:", data.get("paidAt"))
elif data.get("status") == "PENDING_AUTHORIZATION":
print("Biometric push sent, waiting for customer approval...")
{
"status": "success",
"message": "Authorization prompt dispatched to customer's phone",
"data": {
"reference": "ORD-1092",
"status": "PENDING_AUTHORIZATION",
"authChannel": "handle_push",
"promptType": "biometric_push",
"expiresAt": "2026-09-22T08:35:00Z"
}
}
{
"status": "success",
"message": "Charge completed instantly via pre-authorized Auto-Debit",
"data": {
"reference": "ORD-1093",
"status": "SUCCESS",
"authChannel": "handle_push",
"promptType": "instant_auto_debit",
"amount": 1500000,
"fee": 30000,
"netAmount": 1470000,
"paidAt": "2026-09-22T08:30:12Z"
}
}
{
"status": "success",
"message": "Dynamic QR code generated successfully",
"data": {
"reference": "ORD-1094",
"status": "PENDING_SCAN",
"authChannel": "handle_qr",
"qrCodeUrl": "https://api.handle.ng/v1/qr/ORD-1094.png",
"qrData": "handle://pay?ref=ORD-1094&amt=1500000",
"expiresAt": "2026-09-22T08:45:00Z"
}
}
Charges
Dispatch Authorization
Trigger in-app biometric push notification or generate a dynamic QR code
POST
/
v1
/
charges
/
dispatch
curl -X POST https://api.handle.ng/v1/charges/dispatch \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"reference": "ORD-1092",
"authChannel": "handle_push",
"description": "Nike Air Max at SneakerHub"
}'
const res = await fetch('https://api.handle.ng/v1/charges/dispatch', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.HANDLE_SECRET_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
reference: 'ORD-1092',
authChannel: 'handle_push', // or 'handle_qr'
description: 'Nike Air Max at SneakerHub',
}),
});
const { data } = await res.json();
if (data.status === 'SUCCESS') {
// Case 2: Instant Auto-Debit paid immediately
console.log('Payment successful via Auto-Debit:', data.paidAt);
} else if (data.status === 'PENDING_AUTHORIZATION') {
// Case 1: Biometric Push prompt sent to customer phone
console.log('Customer will approve on Handle app with FaceID:', data.expiresAt);
}
import requests
import os
url = "https://api.handle.ng/v1/charges/dispatch"
headers = {
"Authorization": f"Bearer {os.getenv('HANDLE_SECRET_KEY')}",
"Content-Type": "application/json"
}
payload = {
"reference": "ORD-1092",
"authChannel": "handle_push",
"description": "Nike Air Max at SneakerHub"
}
response = requests.post(url, json=payload, headers=headers).json()
data = response.get("data", {})
if data.get("status") == "SUCCESS":
print("Auto-Debit completed instantly:", data.get("paidAt"))
elif data.get("status") == "PENDING_AUTHORIZATION":
print("Biometric push sent, waiting for customer approval...")
{
"status": "success",
"message": "Authorization prompt dispatched to customer's phone",
"data": {
"reference": "ORD-1092",
"status": "PENDING_AUTHORIZATION",
"authChannel": "handle_push",
"promptType": "biometric_push",
"expiresAt": "2026-09-22T08:35:00Z"
}
}
{
"status": "success",
"message": "Charge completed instantly via pre-authorized Auto-Debit",
"data": {
"reference": "ORD-1093",
"status": "SUCCESS",
"authChannel": "handle_push",
"promptType": "instant_auto_debit",
"amount": 1500000,
"fee": 30000,
"netAmount": 1470000,
"paidAt": "2026-09-22T08:30:12Z"
}
}
{
"status": "success",
"message": "Dynamic QR code generated successfully",
"data": {
"reference": "ORD-1094",
"status": "PENDING_SCAN",
"authChannel": "handle_qr",
"qrCodeUrl": "https://api.handle.ng/v1/qr/ORD-1094.png",
"qrData": "handle://pay?ref=ORD-1094&amt=1500000",
"expiresAt": "2026-09-22T08:45:00Z"
}
}
Request Body
Response
curl -X POST https://api.handle.ng/v1/charges/dispatch \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{
"reference": "ORD-1092",
"authChannel": "handle_push",
"description": "Nike Air Max at SneakerHub"
}'
const res = await fetch('https://api.handle.ng/v1/charges/dispatch', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.HANDLE_SECRET_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
reference: 'ORD-1092',
authChannel: 'handle_push', // or 'handle_qr'
description: 'Nike Air Max at SneakerHub',
}),
});
const { data } = await res.json();
if (data.status === 'SUCCESS') {
// Case 2: Instant Auto-Debit paid immediately
console.log('Payment successful via Auto-Debit:', data.paidAt);
} else if (data.status === 'PENDING_AUTHORIZATION') {
// Case 1: Biometric Push prompt sent to customer phone
console.log('Customer will approve on Handle app with FaceID:', data.expiresAt);
}
import requests
import os
url = "https://api.handle.ng/v1/charges/dispatch"
headers = {
"Authorization": f"Bearer {os.getenv('HANDLE_SECRET_KEY')}",
"Content-Type": "application/json"
}
payload = {
"reference": "ORD-1092",
"authChannel": "handle_push",
"description": "Nike Air Max at SneakerHub"
}
response = requests.post(url, json=payload, headers=headers).json()
data = response.get("data", {})
if data.get("status") == "SUCCESS":
print("Auto-Debit completed instantly:", data.get("paidAt"))
elif data.get("status") == "PENDING_AUTHORIZATION":
print("Biometric push sent, waiting for customer approval...")
{
"status": "success",
"message": "Authorization prompt dispatched to customer's phone",
"data": {
"reference": "ORD-1092",
"status": "PENDING_AUTHORIZATION",
"authChannel": "handle_push",
"promptType": "biometric_push",
"expiresAt": "2026-09-22T08:35:00Z"
}
}
{
"status": "success",
"message": "Charge completed instantly via pre-authorized Auto-Debit",
"data": {
"reference": "ORD-1093",
"status": "SUCCESS",
"authChannel": "handle_push",
"promptType": "instant_auto_debit",
"amount": 1500000,
"fee": 30000,
"netAmount": 1470000,
"paidAt": "2026-09-22T08:30:12Z"
}
}
{
"status": "success",
"message": "Dynamic QR code generated successfully",
"data": {
"reference": "ORD-1094",
"status": "PENDING_SCAN",
"authChannel": "handle_qr",
"qrCodeUrl": "https://api.handle.ng/v1/qr/ORD-1094.png",
"qrData": "handle://pay?ref=ORD-1094&amt=1500000",
"expiresAt": "2026-09-22T08:45:00Z"
}
}