API base URL: https://paylodeservices.com/api/v1
Use any future expiry date, any 3-digit CVV, and any cardholder name.
# Node.js npm install paylode-node # Python pip install paylode-python # PHP composer require paylode/paylode-php
const Paylode = require('paylode-node'); const client = new Paylode('sk_test_YOUR_SECRET_KEY'); const txn = await client.transaction.initialize({ email: '[email protected]', amount: 500000, // ₦5,000 in kobo callback_url: 'https://yoursite.com/payment/verify', metadata: { order_id: 'ORD-001' }, }); // Redirect customer to payment page res.redirect(txn.data.authorization_url);
from paylode import Paylode client = Paylode('sk_test_YOUR_SECRET_KEY') txn = client.transaction.initialize( email='[email protected]', amount=500000, # ₦5,000 in kobo callback_url='https://yoursite.com/payment/verify', metadata={'order_id': 'ORD-001'}, ) # Redirect customer redirect(txn['data']['authorization_url'])
require 'vendor/autoload.php'; use Paylode\Paylode; $client = new Paylode('sk_test_YOUR_SECRET_KEY'); $txn = $client->transaction->initialize([ 'email' => '[email protected]', 'amount' => 500000, 'callback_url' => 'https://yoursite.com/payment/verify', ]); header('Location: ' . $txn['data']['authorization_url']);
curl -X POST https://paylodeservices.com/api/v1/transactions/initialize \ -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected]", "amount": 500000, "callback_url": "https://yoursite.com/payment/verify", "metadata": { "order_id": "ORD-001" } }'
// GET /payment/verify?reference=TXN-xxxx const result = await client.transaction.verify(req.query.reference); if (result.data.status === 'SUCCESS') { const orderId = result.data.metadata.order_id; await fulfillOrder(orderId); res.redirect('/order/complete'); } else { res.redirect('/order/failed'); }
result = client.transaction.verify(reference) if result['data']['status'] == 'SUCCESS': order_id = result['data']['metadata']['order_id'] fulfill_order(order_id) return redirect('/order/complete') else: return redirect('/order/failed')
curl https://paylodeservices.com/api/v1/transactions/verify/TXN-xxxx \
-H "Authorization: Bearer sk_test_YOUR_SECRET_KEY"
app.post('/webhook/paylode', express.raw({ type: 'application/json' }), (req, res) => { const sig = req.headers['x-paylode-signature']; const secret = process.env.PAYLODE_WEBHOOK_SECRET; if (!Paylode.webhooks.verify(req.body, sig, secret)) { return res.sendStatus(401); } const event = JSON.parse(req.body); switch (event.event) { case 'payment.success': fulfillOrder(event.data.metadata.order_id); break; case 'payment.failed': notifyCustomer(event.data.customer.email); break; } res.sendStatus(200); } );
Payouts must be submitted with your secret API key (sk_test_… in sandbox, sk_live_… in live) in the Authorization: Bearer header, from a server IP you have registered. Login tokens (JWT) are not accepted for payouts, so there is no login or two-factor step. Wallet balance must be funded by a Paylode admin before batches can be submitted.
Step 1 — Use your secret API key
Generate your key on the dashboard under API Keys. It is shown once, so copy it when it appears. Send it as the bearer token on every payout request. For live payouts the request must come from a server IP on your allowlist.
-H "Authorization: Bearer <YOUR_SECRET_API_KEY>"
# sandbox → sk_test_… live → sk_live_… (allowlisted server IP only)
Step 2 — Look up bank codes and confirm the beneficiary
Both endpoints use your API key. Use the 6-digit bank code returned by the bank list — short codes such as 058 are not accepted. You can also send bank_name instead of bank_code when creating a batch.
# 1. List banks and their codes curl https://paylodeservices.com/api/v1/payouts/banks \ -H "Authorization: Bearer <YOUR_SECRET_KEY>" # Response { "status": true, "data": [ { "bank_code": "000013", "bank_name": "GTBank" }, ... ] } # 2. Confirm the account name before you send curl -X POST https://paylodeservices.com/api/v1/payouts/name-enquiry \ -H "Authorization: Bearer <YOUR_SECRET_KEY>" \ -H "Content-Type: application/json" \ -d '{ "account_number": "0123456789", "bank_code": "000013" }' # Response { "status": true, "data": { "account_name": "ADA OKONKWO", "session_id": "...", "bank_code": "000013", "bank_name": "GTBank" } }
Pass the returned account_name and session_id on each payout item as ne_account_name and ne_session_id so the payout reuses this lookup. Name enquiry is limited to 30 requests per minute per merchant; beyond that you get HTTP 429 with a Retry-After header. If the account cannot be resolved you get NE_FAILED (HTTP 400).
Live payouts are API-only and signed
In live mode, POST /payouts/batches is accepted only with your secret key (sk_live_) from a server IP you have registered under Payout Settings. Dashboard login tokens cannot create payouts. Each request also carries a signature made with your payout signing secret, so a leaked API key on its own cannot move money.
- Dashboard → Payout Settings → Payout request signing → Generate secret (confirm with your payout PIN). Copy or download it once; it cannot be shown again.
- Add three headers:
X-Paylode-Timestamp,X-Paylode-Nonce,X-Paylode-Signature. - Signature = hex HMAC-SHA256, keyed with the secret, of
timestamp.nonce.METHOD.path.sha256hex(body).amountis in kobo. - Check your code with
POST /request-signing/test(same headers and body; moves no money).
Signing starts in monitoring mode (wrong or missing signatures are recorded, not refused). Paylode support switches it to enforced once your integration is verified. Sandbox keys (sk_test_) are not signature-checked. Full guide with Node.js and Python code: payout-request-signing in the developer docs.
curl -X POST https://paylodeservices.com/api/v1/payouts/batches \
-H "Authorization: Bearer <YOUR_SECRET_KEY>" \
-H "X-Paylode-Timestamp: <UNIX_SECONDS>" \
-H "X-Paylode-Nonce: <RANDOM_16_TO_64_CHARS>" \
-H "X-Paylode-Signature: <HMAC_SHA256_HEX>" \
-H "Content-Type: application/json" \
-d '{
"description": "Vendor payment - June",
"items": [
{
"account_number": "0123456789",
"bank_code": "000013",
"amount": 500000,
"account_name": "Ada Okonkwo",
"narration": "Payment for services"
}
]
}'
# Response
{
"status": true,
"data": {
"batch_id": "...",
"batch_ref": "PAY-XXXXXX",
"total_amount": "5000.00",
"total_items": 1,
"status": "processing",
"wallet_balance_after": "45000.00"
}
}
curl -X POST https://paylodeservices.com/api/v1/payouts/batches \
-H "Authorization: Bearer <YOUR_SECRET_KEY>" \
-H "X-Paylode-Timestamp: <UNIX_SECONDS>" \
-H "X-Paylode-Nonce: <RANDOM_16_TO_64_CHARS>" \
-H "X-Paylode-Signature: <HMAC_SHA256_HEX>" \
-H "Content-Type: application/json" \
-d '{
"description": "Staff salaries - June 2026",
"items": [
{
"account_number": "0123456789",
"bank_code": "000013",
"amount": 20000000,
"account_name": "Emeka Obi",
"narration": "June salary"
},
{
"account_number": "9876543210",
"bank_code": "000015",
"amount": 18000000,
"account_name": "Fatima Musa",
"narration": "June salary"
},
{
"account_number": "5556667771",
"bank_code": "000014",
"amount": 15000000,
"account_name": "Chidi Nwosu",
"narration": "June salary"
}
]
}'
curl -X POST https://paylodeservices.com/api/v1/payouts/batches \
-H "Authorization: Bearer <YOUR_SECRET_KEY>" \
-H "X-Paylode-Timestamp: <UNIX_SECONDS>" \
-H "X-Paylode-Nonce: <RANDOM_16_TO_64_CHARS>" \
-H "X-Paylode-Signature: <HMAC_SHA256_HEX>" \
-H "Content-Type: application/json" \
-d '{
"description": "End of month settlement",
"scheduled_at": "2026-06-30T09:00:00.000Z",
"items": [
{
"account_number": "0123456789",
"bank_code": "000016",
"amount": 5000000,
"narration": "June settlement"
}
]
}'
# Returns status: "scheduled" (not processed yet)
# CSV format (account_number, bank_code, amount_naira, narration, account_name) 0123456789,000013,5000,June salary,Emeka Obi 9876543210,000015,4500,June salary,Fatima Musa 5556667771,000014,3800,Vendor payment,Chidi Nwosu # CSV upload is a dashboard feature and live dashboard payouts are switched off. # Convert each row to an item (amount in kobo) and send it to POST /payouts/batches as a signed API request.
Select a bank to populate the examples
Payout webhook events
Listen for these events on your webhook endpoint:
payout.failed — item failed (wrong account, bank error)
payout.batch.completed — all items in a batch processed
Encrypt each beneficiary account number on your side so it is never stored or logged by Paylode in readable form. Only the payment rail can read it, at the moment the payout is sent. Sealing works for payouts routed through Nomba or PalmPay. Plain 10-digit numbers keep working everywhere, and CSV bulk upload and saved beneficiaries always use plain numbers.
How the keys work
There is nothing to generate or store. Paylode publishes two public keys, the same for every merchant. Fetch them with your secret API key:
GET /api/v1/payouts/sealing-key?purpose=payout.account_number GET /api/v1/payouts/sealing-key?purpose=payout.account_record
Download both keys to files with one command each. The compliance key (payout.account_record) is fetched exactly like the account-number key, with the same API key:
curl -s -H "Authorization: Bearer <YOUR_SECRET_API_KEY>" \ "https://paylodeservices.com/api/v1/payouts/sealing-key?purpose=payout.account_number" \ -o paylode-account-number-key.json curl -s -H "Authorization: Bearer <YOUR_SECRET_API_KEY>" \ "https://paylodeservices.com/api/v1/payouts/sealing-key?purpose=payout.account_record" \ -o paylode-compliance-key.json
Each file holds kid, jwk (the public key) and fingerprint. Only the public half is ever published; Paylode compliance holds the private half offline. The example scripts below fetch and verify both keys for you.
Each response includes the key and its fingerprint (a 64-character SHA-256). Paylode gives you the correct fingerprints separately, in your onboarding email or from your account manager. Pin them in your code and compare on every fetch. If the fingerprint ever differs, do not send anything and contact Paylode, because the key may have been replaced by an attacker. The API also refuses any sealed request that does not carry the fingerprints you pinned.
The compliance copy is what lets Paylode complete mandatory regulatory reports (NFIU/CBN). It can only be opened offline by Paylode compliance staff. It must contain the same account number as account_number.
Create a payout batch with sealed numbers
curl -X POST https://paylodeservices.com/api/v1/payouts/batches \
-H "Authorization: Bearer <YOUR_SECRET_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"description": "Vendor payment",
"sealing_key_fingerprint": "<PINNED account_number FINGERPRINT>",
"record_key_fingerprint": "<PINNED account_record FINGERPRINT>",
"items": [
{
"account_number": "eyJhbGciOi...", # sealed with payout.account_number
"account_number_record": "eyJhbGciOi...", # sealed with payout.account_record
"bank_code": "058",
"amount": 500000,
"account_name": "Ada Okonkwo"
}
]
}'
Name enquiry (POST /payouts/name-enquiry) accepts a sealed account_number with sealing_key_fingerprint; it does not need the compliance copy. Batch responses, statuses and CSV exports show sealed numbers as SEALED.
'use strict';
// Seal a sensitive payout field to Paylode's sealing key (Node 18+, no dependencies).
// const { fetchKey, sealField } = require('./seal');
// const key = await fetchKey('https://api.paylodeservices.com', API_KEY, 'payout.account_number', PINNED_FINGERPRINT);
// body.accountNumber = sealField(key, '0123456789');
// Payout batches also need the compliance copy and BOTH pinned fingerprints, or the API refuses the request:
// const rec = await fetchKey(base, API_KEY, 'payout.account_record', PINNED_RECORD_FINGERPRINT);
// item.account_number = sealField(key, '0123456789'); item.account_number_record = sealField(rec, '0123456789');
// body.sealing_key_fingerprint = PINNED_FINGERPRINT; body.record_key_fingerprint = PINNED_RECORD_FINGERPRINT;
const crypto = require('crypto');
const b64u = (b) => Buffer.from(b).toString('base64url');
const fingerprintOf = (jwk) => crypto.createHash('sha256').update(JSON.stringify({ e: jwk.e, kty: jwk.kty, n: jwk.n })).digest('hex');
async function fetchKey(baseUrl, apiKey, purpose, pinnedFingerprint) {
const res = await fetch(`${baseUrl}/api/v1/payouts/sealing-key?purpose=${encodeURIComponent(purpose)}`, { headers: { Authorization: `Bearer ${apiKey}` } });
if (!res.ok) throw new Error(`sealing key request failed: ${res.status}`);
const k = (await res.json()).data;
if (fingerprintOf(k.jwk) !== k.fingerprint) throw new Error('key does not match its own fingerprint');
if (k.fingerprint !== pinnedFingerprint) throw new Error('sealing key fingerprint changed - do NOT send; contact Paylode');
return { kid: k.kid, purpose: k.purpose, publicKey: crypto.createPublicKey({ key: k.jwk, format: 'jwk' }) };
}
function sealField({ kid, purpose, publicKey }, plaintext) {
const header = b64u(JSON.stringify({ alg: 'RSA-OAEP-256', enc: 'A256GCM', kid, purpose }));
const cek = crypto.randomBytes(32), iv = crypto.randomBytes(12);
const c = crypto.createCipheriv('aes-256-gcm', cek, iv);
c.setAAD(Buffer.from(header, 'ascii'));
const ct = Buffer.concat([c.update(Buffer.from(String(plaintext), 'utf8')), c.final()]);
const ek = crypto.publicEncrypt({ key: publicKey, padding: crypto.constants.RSA_PKCS1_OAEP_PADDING, oaepHash: 'sha256' }, cek);
return [header, b64u(ek), b64u(iv), b64u(ct), b64u(c.getAuthTag())].join('.');
}
module.exports = { fetchKey, sealField, fingerprintOf };# Seal a sensitive payout field to Paylode's sealing key. pip install cryptography requests
# key = fetch_key("https://api.paylodeservices.com", API_KEY, "payout.account_number", PINNED_FINGERPRINT)
# body["accountNumber"] = seal_field(key, "0123456789")
# Payout batches also need the compliance copy and BOTH pinned fingerprints:
# rec = fetch_key(base, API_KEY, "payout.account_record", PINNED_RECORD_FINGERPRINT)
# item["account_number"] = seal_field(key, "0123456789"); item["account_number_record"] = seal_field(rec, "0123456789")
# body["sealing_key_fingerprint"] = PINNED_FINGERPRINT; body["record_key_fingerprint"] = PINNED_RECORD_FINGERPRINT
import base64
import hashlib
import json
import os
import requests
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import padding, rsa
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
def b64u(b: bytes) -> str:
return base64.urlsafe_b64encode(b).rstrip(b"=").decode()
def b64u_dec(s: str) -> bytes:
return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
def fingerprint_of(jwk: dict) -> str:
canon = json.dumps({"e": jwk["e"], "kty": jwk["kty"], "n": jwk["n"]}, separators=(",", ":"))
return hashlib.sha256(canon.encode()).hexdigest()
def fetch_key(base_url, api_key, purpose, pinned_fingerprint):
r = requests.get(
f"{base_url}/api/v1/payouts/sealing-key",
params={"purpose": purpose},
headers={"Authorization": f"Bearer {api_key}"},
timeout=10,
)
r.raise_for_status()
k = r.json()["data"]
if fingerprint_of(k["jwk"]) != k["fingerprint"]:
raise ValueError("key does not match its own fingerprint")
if k["fingerprint"] != pinned_fingerprint:
raise ValueError("sealing key fingerprint changed - do NOT send; contact Paylode")
n = int.from_bytes(b64u_dec(k["jwk"]["n"]), "big")
e = int.from_bytes(b64u_dec(k["jwk"]["e"]), "big")
return {"kid": k["kid"], "purpose": k["purpose"], "public_key": rsa.RSAPublicNumbers(e, n).public_key()}
def seal_field(key, plaintext: str) -> str:
header = b64u(json.dumps(
{"alg": "RSA-OAEP-256", "enc": "A256GCM", "kid": key["kid"], "purpose": key["purpose"]},
separators=(",", ":"),
).encode())
cek, iv = os.urandom(32), os.urandom(12)
ct_and_tag = AESGCM(cek).encrypt(iv, plaintext.encode(), header.encode("ascii")) # ciphertext || 16-byte tag
ct, tag = ct_and_tag[:-16], ct_and_tag[-16:]
ek = key["public_key"].encrypt(
cek, padding.OAEP(mgf=padding.MGF1(hashes.SHA256()), algorithm=hashes.SHA256(), label=None)
)
return ".".join([header, b64u(ek), b64u(iv), b64u(ct), b64u(tag)])<?php
// Seal a sensitive payout field to Paylode's sealing key. composer require phpseclib/phpseclib:^3
// PHP's built-in openssl_public_encrypt only does OAEP with SHA-1, so RSA-OAEP-SHA256 needs phpseclib.
// $key = fetchKey('https://api.paylodeservices.com', $apiKey, 'payout.account_number', $pinnedFingerprint);
// $body['accountNumber'] = sealField($key, '0123456789');
// Payout batches also need the compliance copy and BOTH pinned fingerprints:
// $rec = fetchKey($base, $apiKey, 'payout.account_record', $pinnedRecordFingerprint);
// $item['account_number'] = sealField($key, '0123456789'); $item['account_number_record'] = sealField($rec, '0123456789');
// $body['sealing_key_fingerprint'] = $pinnedFingerprint; $body['record_key_fingerprint'] = $pinnedRecordFingerprint;
use phpseclib3\Crypt\RSA;
use phpseclib3\Math\BigInteger;
function b64u(string $b): string { return rtrim(strtr(base64_encode($b), '+/', '-_'), '='); }
function b64uDec(string $s): string { return base64_decode(strtr($s, '-_', '+/')); }
function fingerprintOf(array $jwk): string {
return hash('sha256', json_encode(['e' => $jwk['e'], 'kty' => $jwk['kty'], 'n' => $jwk['n']], JSON_UNESCAPED_SLASHES));
}
function fetchKey(string $baseUrl, string $apiKey, string $purpose, string $pinned): array {
$ctx = stream_context_create(['http' => ['header' => "Authorization: Bearer $apiKey\r\n", 'timeout' => 10]]);
$res = file_get_contents("$baseUrl/api/v1/payouts/sealing-key?purpose=" . urlencode($purpose), false, $ctx);
if ($res === false) throw new Exception('sealing key request failed');
$k = json_decode($res, true)['data'];
if (fingerprintOf($k['jwk']) !== $k['fingerprint']) throw new Exception('key does not match its own fingerprint');
if ($k['fingerprint'] !== $pinned) throw new Exception('sealing key fingerprint changed - do NOT send; contact Paylode');
$pub = RSA::loadPublicKey(['n' => new BigInteger(b64uDec($k['jwk']['n']), 256), 'e' => new BigInteger(b64uDec($k['jwk']['e']), 256)])
->withPadding(RSA::ENCRYPTION_OAEP)->withHash('sha256')->withMGFHash('sha256');
return ['kid' => $k['kid'], 'purpose' => $k['purpose'], 'pub' => $pub];
}
function sealField(array $key, string $plaintext): string {
$header = b64u(json_encode(['alg' => 'RSA-OAEP-256', 'enc' => 'A256GCM', 'kid' => $key['kid'], 'purpose' => $key['purpose']]));
$cek = random_bytes(32);
$iv = random_bytes(12);
$ct = openssl_encrypt($plaintext, 'aes-256-gcm', $cek, OPENSSL_RAW_DATA, $iv, $tag, $header, 16);
return implode('.', [$header, b64u($key['pub']->encrypt($cek)), b64u($iv), b64u($ct), b64u($tag)]);
}Format: standard JWE compact serialization (RSA-OAEP-256 + A256GCM), so any JOSE library also works. Use a fresh seal for every value and every request.
Test now, verify later
Your test keys (sk_test_… / pk_test_…) work immediately — you can integrate and test every product below before your merchant KYC is approved. Live keys (sk_live_…) only start working once KYC is verified. Sandbox transactions never move real money.
Initialize with the bank_transfer channel. Paylode returns a one-time virtual account; the customer transfers to it and the payment auto-confirms. In sandbox the account and the inbound transfer are simulated — no real funds move.
Initialize a bank-transfer charge
curl -X POST https://paylodeservices.com/api/v1/transactions/initialize \ -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected]", "amount": 500000, "currency": "NGN", "channels": ["bank_transfer"] }' # Response → data.authorization_url (hosted page shows the virtual account number + amount) # data.product → "VIRTUAL_ACCOUNT"
Initialize with the ussd channel. Paylode returns a USSD string the customer dials on their phone to authorise. Sandbox simulates the dial/approve step.
curl -X POST https://paylodeservices.com/api/v1/transactions/initialize \ -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected]", "amount": 500000, "currency": "NGN", "channels": ["ussd"] }' # Response → data.authorization_url (hosted page shows the *USSD code to dial) # data.product → "USSD"
Pass currency:"USD" with the card channel. Amount is in cents. The transaction is routed as an international card (CARD_INTL), billed and settled entirely in USD. Optionally pass card_scheme or card_bin so the right scheme rate applies.
curl -X POST https://paylodeservices.com/api/v1/transactions/initialize \ -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected]", "amount": 50000, "currency": "USD", "channels": ["card"], "card_scheme": "VISA" }' # amount 50000 = $500.00 (cents) · data.product → "CARD_INTL" (or CARD_INTL_VISA) # data.fee_preview.display → "$17.50" · settled in a separate USD batch
Successful charges are grouped into settlement batches (NGN and USD settled separately). Authenticate with a JWT (login first), then fetch your settlements. Sandbox simulates a T+1 cycle so you can see how payouts to your bank account are reported.
# 1) Get a token curl -X POST https://paylodeservices.com/api/v1/auth/login \ -H "Content-Type: application/json" \ -d '{"email":"[email protected]","password":"YOUR_PASSWORD"}' # 2) List settlement batches curl https://paylodeservices.com/api/v1/settlements \ -H "Authorization: Bearer <YOUR_JWT_TOKEN>" # 3) Your statement (per-currency summary) curl https://paylodeservices.com/api/v1/reports/merchant-statement \ -H "Authorization: Bearer <YOUR_JWT_TOKEN>"
Fees are deducted before settlement. NGN and USD are always reported side by side and never summed. The statement shows summary_by_currency so you can reconcile each balance separately.