SANDBOX ← Back to site
Developer Sandbox

Test your integration with no real money

Use the credentials below to build and test your Paylode integration. Sandbox transactions are completely isolated — no real payments are processed.

These are shared test credentials. Do not use them in production. Your live keys are available in your merchant dashboard after KYC approval. Never commit API keys to source code — use environment variables.
Sandbox Credentials
Secret Key (sk_test)
sk_test_YOUR_SECRET_KEY
Public Key (pk_test)
pk_test_YOUR_PUBLIC_KEY
Webhook Secret
YOUR_WEBHOOK_SECRET
Dashboard Login
[email protected]
Password: your account password

API base URL: https://paylodeservices.com/api/v1

Test Card Numbers

Use any future expiry date, any 3-digit CVV, and any cardholder name.

Card Number Result Use case
4084 0841 1111 1111 ✓ Success Payment completes immediately
4084 0841 1111 1112 ✗ Declined Insufficient funds / card declined
4084 0841 1111 1113 ✗ Failed Generic card failure
4084 0800 0000 0409 ● OTP Triggers OTP screen (enter any 6 digits)
How to integrate
1
Install the SDK
Choose your language. All SDKs work identically — swap sk_test for sk_live when going live.
# Node.js
npm install paylode-node

# Python
pip install paylode-python

# PHP
composer require paylode/paylode-php
2
Initialize a payment
Create a transaction and redirect your customer to the authorization URL.
Node.js
Python
PHP
cURL
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" }
  }'
3
Verify the payment server-side
When the customer returns to your callback URL, always verify server-side. Never trust the frontend.
Node.js
Python
cURL
// 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"
4
Handle webhooks
Webhooks are the reliable way to track payment status in real time. Always verify the signature.
Node.js (Express)
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);
  }
);
5
Go live
Replace your test key with your live key. That's it — no other code changes needed. Complete KYC onboarding to get your live keys.
Webhook Events
EventWhen it fires
payment.successPayment completed successfully
payment.failedPayment was declined or failed
refund.processedA refund was issued to the customer
chargeback.raisedCustomer raised a chargeback with their bank
Payout Test Scenarios

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.

  1. Dashboard → Payout Settings → Payout request signing → Generate secret (confirm with your payout PIN). Copy or download it once; it cannot be shown again.
  2. Add three headers: X-Paylode-Timestamp, X-Paylode-Nonce, X-Paylode-Signature.
  3. Signature = hex HMAC-SHA256, keyed with the secret, of timestamp.nonce.METHOD.path.sha256hex(body). amount is in kobo.
  4. 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.

ScenarioHow to triggerExpected result
Single payout POST /payouts/batches — 1 item processing status returned
Batch payout POST /payouts/batches — multiple items Batch created, wallet debited, all items queued
Scheduled payout Add scheduled_at (future ISO date) scheduled status, not yet processed
Insufficient balance Amount exceeds wallet balance INSUFFICIENT_BALANCE error 400
Invalid account account_number not 10 digits Validation error 400
Bank list GET /payouts/banks (API key) List of bank_code / bank_name
Name enquiry POST /payouts/name-enquiry (API key) account_name + session_id returned; 31st call in a minute → 429
CSV bulk upload POST /payouts/batches/upload (multipart) Batch created from CSV file (dashboard only; not available for live payouts)
Single Payout
Batch Payout
Scheduled
CSV Format
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

Bank codeBank nameType
Loading...

Payout webhook events

Listen for these events on your webhook endpoint:

payout.completed  — item successfully sent to beneficiary
payout.failed  — item failed (wrong account, bank error)
payout.batch.completed  — all items in a batch processed
Sealed Account Numbers (optional)

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.

Key (purpose)Seal thisSend asPinned fingerprint field
payout.account_numberThe beneficiary account numberitems[].account_numbersealing_key_fingerprint
payout.account_recordThe same account number again (compliance copy)items[].account_number_recordrecord_key_fingerprint

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.

Node.js
Python
PHP
'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.

Error codeWhat to do
SEALING_FINGERPRINT_REQUIREDSend sealing_key_fingerprint (the pinned account_number key fingerprint).
SEALING_FINGERPRINT_MISMATCHYour pinned fingerprint does not match the current key. Do not send; contact Paylode.
RECORD_FINGERPRINT_REQUIRED / RECORD_FINGERPRINT_MISMATCHSame, for record_key_fingerprint and the compliance key.
RECORD_MISSINGEvery sealed item needs account_number_record sealed with the compliance key.
SEALED_KEY_STALEThe key was rotated. Fetch the key again, check the fingerprint, and re-seal.
SEALED_RAIL_UNSUPPORTEDThe payout route for this merchant is not Nomba/PalmPay. Use plain account numbers or ask Paylode to change your route.
SEALING_UNAVAILABLE / COMPLIANCE_KEY_UNAVAILABLETemporary. Nothing was created; retry shortly.
SEALING_DISABLEDSealing is not enabled for this environment. Use plain account numbers.

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.

Bank Transfer (Virtual Accounts)

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"
ScenarioHow to triggerExpected result
Successful transferOpen authorization_url → "I've sent the money"success + payment.success webhook
Virtual account expiryWait past the on-screen timerSession expires, no charge
VerifyGET /transactions/verify/<reference>Returns final status — always verify server-side
USSD

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"
ScenarioHow to triggerExpected result
ApprovedOpen authorization_url → "Simulate approval"success + payment.success
Timed outDo not approve within the windowfailed — session expired
International Cards (USD)

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
FieldNotes
amountIn cents ($1 = 100). NGN amounts are in kobo.
card_schemeOptional: VISA | MASTERCARD | AMEX | DINERS (rate applied if admin configured one, else flat CARD_INTL).
card_binOptional: first 6 digits — scheme auto-detected if card_scheme omitted.
Test cardUse the test cards above; charge succeeds/declines the same way, reported in USD.
Settlements

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.