5-Minute Quickstart Guide

This guide walks you through integrating Pay with Handle using our Headless REST API.

Step 1: Obtain Your API Keys

Log in to the Handle Merchant Dashboard.
Copy your Secret Key (sk_test_... for development, sk_live_... for production).

Never expose your Secret Key (sk_live_... or sk_test_...) in client-side code (browsers, mobile apps). Always make API calls from your secure backend server.

Step 2: Resolve Customer Handle

When the customer enters @ayodeji at checkout, make a request from your backend to resolve their profile:

curl -X POST https://api.handle.ng/v1/charges/resolve-handle \
  -H "Authorization: Bearer sk_test_sample_key_123" \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "ayodeji",
    "amount": 1500000,
    "reference": "ORD-1092"
  }'

const response = 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, // ₦15,000 in Kobo
    reference: 'ORD-1092',
  }),
});

const data = await response.json();
console.log(data);

import requests
import os

url = "https://api.handle.ng/v1/charges/resolve-handle"
headers = {
    "Authorization": f"Bearer {os.getenv('HANDLE_SECRET_KEY')}",
    "Content-Type": "application/json"
}
payload = {
    "handle": "ayodeji",
    "amount": 1500000,
    "reference": "ORD-1092"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Step 3: Dispatch Payment Authorization

Display the customer’s linked active banks and dispatch the push prompt:

curl -X POST https://api.handle.ng/v1/charges/dispatch \
  -H "Authorization: Bearer sk_test_sample_key_123" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "ORD-1092",
    "bankId": "bnk_gtb_01",
    "authChannel": "handle_push",
    "description": "Nike Air Max at SneakerHub"
  }'

const dispatchRes = 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',
    bankId: 'bnk_gtb_01',
    authChannel: 'handle_push',
    description: 'Nike Air Max at SneakerHub',
  }),
});

const result = await dispatchRes.json();

Step 4: Listen for Webhooks

Configure your server endpoint to receive real-time payment confirmations:

Express.js (Node.js)

app.post('/handle/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-handle-signature'];
  // Verify HMAC-SHA512 signature
  const event = JSON.parse(req.body);

  if (event.event === 'charge.success') {
    const { reference, amount, customer } = event.data;
    console.log(`✅ Order ${reference} for ₦${amount / 100} paid by ${customer.handle}`);
    // Fulfill customer order
  }

  res.status(200).send({ received: true });
});

Getting Started

Webhooks & Events

In-Store & SoftPOS

Reference

Quickstart

5-Minute Quickstart Guide

Step 1: Obtain Your API Keys

Step 2: Resolve Customer Handle

Step 3: Dispatch Payment Authorization

Step 4: Listen for Webhooks

​5-Minute Quickstart Guide

​Step 1: Obtain Your API Keys

​Step 2: Resolve Customer Handle

​Step 3: Dispatch Payment Authorization

​Step 4: Listen for Webhooks

5-Minute Quickstart Guide

Step 1: Obtain Your API Keys

Step 2: Resolve Customer Handle

Step 3: Dispatch Payment Authorization

Step 4: Listen for Webhooks