# 1 — Expose local server
ngrok http 3000

# 2 — Register the tunnel URL as your webhook
curl -X POST https://sandbox.nexapay.net/v2/webhooks \
  -H "Authorization: Bearer npay_test_sec_..." \
  -d '{"url":"https://abc123.ngrok.io/webhooks/nexapay","events":["payin.success","payin.failed"]}'

# 3 — Run a test charge
curl -X POST https://sandbox.nexapay.net/v2/payments/charge \
  -H "Authorization: Bearer npay_test_sec_..." \
  -d '{"phone_number":"260970000001","amount":50000,"currency":"ZMW","network":"MTN","reference":"TEST-001"}'

const headers = {
  'Authorization': `Bearer ${process.env.NEXAPAY_SK}`,
  'Content-Type':  'application/json'
};
const res = await fetch('https://api.nexapay.net/v2/...', { headers });

<script src="https://js.nexapay.net/v2/checkout.js"></script>
<button onclick="pay()">Pay Now</button>
<script>
function pay() {
  NexaPayCheckout.create({
    public_key: 'npay_live_pub_...',
    amount:     5000,    // in smallest unit
    currency:  'ZMW',   // ZMW | ZiG | USD | BWP | NAD
    reference: 'ORDER-001',
    customer: { name: 'Jane Banda', email: 'jane@example.com' },
    onSuccess: (d) => console.log(d.transaction_id),
    onClose:   () => console.log('closed')
  }).open();
}
</script>

NexaPayCheckout.create({
  public_key:  'npay_live_pub_...',
  amount:      120000,
  currency:    'ZMW',
  reference:   'ORD-001',
  description: 'Annual Premium Plan',
  logo:        'https://myapp.com/logo.png',
  color:       '#1a6b3a',         // overrides the default brand blue
  countries: ['ZM'],              // only show Zambia tab
  phone:       '260971234567',  // pre-fill phone
  onSuccess:   txn => {
    // txn.transaction_id, txn.status — for UI only
    document.querySelector('#status').textContent = 'Payment received — confirming…';
  },
  onClose:     () => console.log('User closed checkout'),
  onError:     err => console.error('SDK error', err)
}).open();

{
  "status": "success",
  "data": {
    "id":          "pl_01J9XKABCDEF",
    "url":         "https://pay.nexapay.net/l/abc123",
    "qr_url":      "https://api.nexapay.net/v2/payment-links/pl_01J9XK.../qr",
    "title":       "School Fees Term 3",
    "currency":    "ZMW",
    "type":        "fixed",
    "amount":      120000,
    "status":      "active",
    "usage_count": 0,
    "max_uses": null,
    "expires_at":  null,
    "created_at":  "2025-09-01T10:22:00Z"
  }
}

// List all payment links (paginated)
const list = await (await fetch(
  'https://api.nexapay.net/v2/payment-links?status=active&page=1&limit=20',
  { headers: { Authorization: `Bearer ${SK}` } }
)).json();

// Update a link (change title or deactivate)
await fetch('https://api.nexapay.net/v2/payment-links/pl_01J9XK...', {
  method: 'PATCH',
  headers: { 'Authorization': `Bearer ${SK}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ status: 'inactive' })  // deactivate
});

// Get QR code PNG (returns binary, save as .png)
const qr = await fetch(
  'https://api.nexapay.net/v2/payment-links/pl_01J9XK.../qr',
  { headers: { Authorization: `Bearer ${SK}` } }
);

const bal = await (await fetch('https://api.nexapay.net/v2/balance', {
  headers: { 'Authorization': `Bearer ${SK}` }
})).json();
// Response: { data: { ZMW: 5000000, ZiG: 0, USD: 25000, BWP: 120000, NAD: 300000 } }

const payoutAmount = 100000;  // 1,000 ZMW
if (bal.data.ZMW < payoutAmount) {
  throw new Error('Insufficient ZMW balance for payout');
}

{
  "status": "success",
  "data": {
    "payout_id":      "pout_01J9XKABCDEF",
    "status":         "pending",   // pending → success | failed
    "phone_number":   "260971234567",
    "amount":         100000,
    "currency":       "ZMW",
    "network":        "MTN",
    "reference":      "POUT-ZM-001",
    "recipient_name": "John Phiri",
    "fee":            0,            // no payout fee on NexaPay
    "created_at":     "2025-09-01T11:00:00Z",
    "completed_at":   null
  }
}

const res = await fetch('https://api.nexapay.net/v2/payouts/batch', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${SK}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    payouts: [
      { phone_number: '260971234567', amount: 50000, currency: 'ZMW', network: 'MTN',    reference: 'BULK-001' },
      { phone_number: '260977654321', amount: 75000, currency: 'ZMW', network: 'AIRTEL', reference: 'BULK-002' },
      { phone_number: '263771234567', amount: 1000,  currency: 'USD', network: 'ECOCASH', reference: 'BULK-003' }
    ]
  })
});
// Returns: { batch_id: "btch_...", total: 3, queued: 3, rejected: 0 }

import crypto from 'node:crypto';
function verify(rawBody, sig, secret) {
  const expected = crypto.createHmac('sha256',secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected),Buffer.from(sig));
}
// Express — use express.raw() to get the raw body buffer
app.post('/webhooks/nexapay', express.raw({type:'application/json'}), (req,res) => {
  if (!verify(req.body,req.headers['x-nexapay-signature'],process.env.WH_SECRET))
    return res.sendStatus(401);
  const event = JSON.parse(req.body);
  if (event.type === 'payin.success') fulfillOrder(event.data);
  res.sendStatus(200); // Respond within 5 seconds
});

{
  "id":        "evt_01J9XKABCDEF",          // unique per delivery — use for dedup
  "type":      "payin.success",
  "created_at": "2025-09-01T11:05:32Z",
  "data": {
    "transaction_id": "txn_01J9XKABCDEF",
    "reference":      "ORD-001",
    "phone_number":   "260971234567",
    "amount":         50000,
    "currency":       "ZMW",
    "network":        "MTN",
    "fee":            1300,           // 2.6% of 50000
    "net":            48700,           // credited to your wallet
    "status":         "success",
    "payment_link_id": null,            // set if via a payment link
    "metadata": { "order_id": "ORD-001" },
    "completed_at":   "2025-09-01T11:05:30Z"
  }
}

// Register a new webhook
await fetch('https://api.nexapay.net/v2/webhooks', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${SK}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    url:    'https://myapp.com/webhooks/nexapay',
    events: ['payin.success', 'payin.failed', 'payout.success', 'payout.failed']
    // omit events to subscribe to all event types
  })
});
// Returns: { id: "wh_01J9...", secret: "whsec_...", url: "...", events: [...] }
// Store the returned secret — it is shown only once.

# Fire a synthetic payin.success to your endpoint
curl -X POST https://sandbox.nexapay.net/v2/webhooks/test \
  -H "Authorization: Bearer npay_test_sec_..." \
  -d '{"event_type":"payin.success","webhook_id":"wh_01J9...","overrides":{"amount":10000,"currency":"ZMW"}}'

const body = await res.json();
if (!res.ok) {
  switch (body.error_code) {
    case 'DUPLICATE_REFERENCE': throw new Error('Order already paid');
    case 'INVALID_PHONE':       throw new Error('Phone number format invalid');
    case 'INSUFFICIENT_BALANCE': throw new Error('Customer wallet low funds');
    case 'NETWORK_MISMATCH':    throw new Error('Network code wrong for this phone');
    default:                    throw new Error(body.message ?? 'Payment failed');
  }
}

async function fetchWithRetry(url, opts, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const res = await fetch(url, opts);
    if (res.status === 429 || res.status >= 500) {
      const retryAfter = res.headers.get('Retry-After');
      const wait = retryAfter
        ? parseInt(retryAfter) * 1000
        : (2 ** attempt) * 1000 + Math.random() * 200;  // jitter
      await new Promise(r => setTimeout(r, wait));
      continue;
    }
    return res;
  }
  throw new Error(`Failed after ${maxAttempts} attempts`);
}

/** Convert local or E.164 phone to NexaPay API format */
function toApiPhone(raw, countryCode) {
  const digits = raw.replace(/\D/g, '');  // strip non-digits
  if (digits.startsWith(countryCode)) return digits;
  if (digits.startsWith('0')) return countryCode + digits.slice(1);
  return countryCode + digits;
}
toApiPhone('0971 234 567', '260');  // → '260971234567'
toApiPhone('+263771234567', '263');  // → '263771234567'

POST /v2/payments/charge HTTP/1.1
Host: api.nexapay.net
Authorization: Bearer npay_live_sec_...
Content-Type: application/json
Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890

{
  "phone_number":  "260971234567",
  "amount":       50000,
  "currency":     "ZMW",
  "network":      "MTN",
  "reference":    "ORD-001",
  "description":  "Electricity top-up",
  "callback_url": "https://myapp.com/webhooks/nexapay",
  "metadata": { "user_id": "usr_888", "plan": "premium" }
}

GET /v2/payments?status=success&page=2&limit=50&from=2025-01-01&to=2025-09-30 HTTP/1.1
Authorization: Bearer npay_live_sec_...

import { randomUUID } from 'node:crypto';
// Derive a stable key from your order ID so retries reuse the same key
const idempotencyKey = `charge-${orderId}`;

await fetch('https://api.nexapay.net/v2/payments/charge', {
  method: 'POST',
  headers: {
    'Authorization':   `Bearer ${SK}`,
    'Content-Type':    'application/json',
    'Idempotency-Key': idempotencyKey       // safe to retry
  },
  body: JSON.stringify({ ... })
});

// Full refund — omit amount for the full transaction
const res = await fetch('https://api.nexapay.net/v2/refunds', {
  method:  'POST',
  headers: {
    'Authorization': `Bearer ${SK}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payment_id: 'pay_01HXYZ...',
    reason:     'customer_request',
    reference: 'REF-001'
  })
});
const refund = await res.json();
// { id: "rfd_01...", status: "processing", amount: 100000, currency: "ZMW" }

// Partial refund — ZMW 50 of a ZMW 200 payment
await fetch('https://api.nexapay.net/v2/refunds', {
  method:  'POST',
  headers: { 'Authorization': `Bearer ${SK}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    payment_id: 'pay_01HXYZ...',
    amount:     5000,  // ZMW 50.00 in smallest unit
    reason:     'partial_service',
    reference: 'REF-002'
  })
});

const res = await fetch(
  `https://api.nexapay.net/v2/refunds/${refundId}`,
  { headers: { 'Authorization': `Bearer ${SK}` } }
);
// { id, status: "completed"|"failed"|"processing", amount, created_at }

const res = await fetch(
  `https://api.nexapay.net/v2/payments/${paymentId}/refunds`,
  { headers: { 'Authorization': `Bearer ${SK}` } }
);
const { data } = await res.json();
// data: [{ id, status, amount, created_at }, ...]

const res = await fetch(
  `https://api.nexapay.net/v2/payouts/${payoutId}/reversal`,
  {
    method:  'POST',
    headers: { 'Authorization': `Bearer ${SK}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ reason: 'wrong_recipient' })
  }
);
// { id: "rev_01...", payout_id, status: "reversed", reversed_at }