Direct integration, A to Z.

curl -X POST https://api.merashub.com/v1/payment_intents \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: order_42" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50,
    "currency": "DJF",
    "provider": "cac",                       // cac | waafi | sabapay | eab | santimpay  (card → waafi + waafi_mode:"card")
    "customer_msisdn": "77000000",           // wallet rails only
    "return_url": "https://yoursite.example/orders/42/return",
    "description": "Order #42"
  }'

// provider: "cac"  →  collect the OTP on your page
{ "id": "pi_01H...", "status": "requires_action",
  "next_action": { "type": "collect_otp", "otp_length": 6 } }

// provider "waafi" + metadata.waafi_mode "hpp"  →  wallet on Waafi's page
{ "id": "pi_01H...", "status": "requires_action",
  "next_action": { "type": "redirect",
                   "redirect_url": "https://hpp.waafipay.com/pay/AB12..." } }

// provider "waafi" + metadata.waafi_mode "card"  →  Visa/MC on Waafi's page
{ "id": "pi_01H...", "status": "requires_action",
  "next_action": { "type": "redirect",
                   "redirect_url": "https://hpp.waafipay.com/pay/CD34..." } }

// provider "santimpay" (Ethiopia/ETB)  →  redirect to SantimPay's page
{ "id": "pi_01H...", "status": "requires_action",
  "next_action": { "type": "redirect",
                   "redirect_url": "https://checkout.santimpay.com/..." } }

// provider "sabapay" + metadata.auth_mode "APP"  →  approve in the app
{ "id": "pi_01H...", "status": "requires_action",
  "next_action": { "type": "push_approval" } }

// 1) create — provider "cac", bare MSISDN
const create = await fetch('https://api.merashub.com/v1/payment_intents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.MERAS_SECRET_KEY,
    'Idempotency-Key': 'order_42',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 50, currency: 'DJF',
    provider: 'cac',
    customer_msisdn: '77000000',   // bare local number
    description: 'Order #42',
  }),
});
const intent = await create.json();
// intent.next_action.type === 'collect_otp'  → show an OTP input to the customer

// 2) confirm — once the customer types the SMS code
const confirm = await fetch(
  'https://api.merashub.com/v1/payment_intents/' + intent.id + '/confirm',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + process.env.MERAS_SECRET_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ otp: '123456' }),   // sandbox: 123456 succeeds
  },
);
const result = await confirm.json();
if (result.status === 'succeeded') fulfilOrder(intent.id);
// wrong code → 400 "otp invalid": the request is consumed, start a new intent.

// 1) create — provider "waafi". No MSISDN/PIN needed from you.
const create = await fetch('https://api.merashub.com/v1/payment_intents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.MERAS_SECRET_KEY,
    'Idempotency-Key': 'order_42',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 50, currency: 'DJF',
    provider: 'waafi',
    metadata: { waafi_mode: 'hpp' },   // ← REQUIRED for the hosted-page flow
    return_url: 'https://yoursite.example/orders/42/return',
    description: 'Order #42',
  }),
});
const intent = await create.json();

// 2) redirect — send the customer to Waafi's hosted page.
//    They enter their phone + PIN THERE, not in your app.
if (intent.next_action?.type === 'redirect') {
  res.redirect(303, intent.next_action.redirect_url);
}

// 3) return — Waafi sends the customer back to return_url when done.
//    Don't trust the return alone; verify the real status:
app.get('/orders/42/return', async (req, res) => {
  const r = await fetch(
    'https://api.merashub.com/v1/payment_intents/' + intentId,
    { headers: { 'Authorization': 'Bearer ' + process.env.MERAS_SECRET_KEY } },
  );
  const fresh = await r.json();
  res.render(fresh.status === 'succeeded' ? 'thank-you' : 'try-again');
});

// APP push — customer approves in SabaMobile; you poll / await webhook.
await createIntent({ provider: 'sabapay', amount: 50, currency: 'DJF',
                     customer_msisdn: '77000000',
                     metadata: { auth_mode: 'APP' } });
// next_action.type === 'push_approval'  → poll GET /payment_intents/{id}

// OTP — SMS code, then confirm (same as CAC).
const i = await createIntent({ provider: 'sabapay', amount: 50, currency: 'DJF',
                               customer_msisdn: '77000000',
                               metadata: { auth_mode: 'OTP' } });
// next_action.type === 'collect_otp'
await confirmIntent(i.id, { otp: '123456' });

curl https://api.merashub.com/v1/payment_intents/pi_01H... \
  -H "Authorization: Bearer sk_test_..."
# poll every 2s → requires_action → … → succeeded | canceled

// Headers on every delivery:
//   MerasPay-Event-Id:   evt_...
//   MerasPay-Event-Type: payment_intent.succeeded
//   MerasPay-Signature:  t=<unix>,v1=<hex>   — HMAC-SHA256 over "{t}.{event_id}.{body}"
app.post('/webhooks/meras', express.raw({ type: '*/*' }), (req, res) => {
  const header  = req.headers['meraspay-signature'] || '';   // keys are lowercased
  const eventId = req.headers['meraspay-event-id'] || '';
  const parts = Object.fromEntries(header.split(',').map((kv) => kv.split('=')));

  const signed = parts.t + '.' + eventId + '.' + req.body;   // body = raw bytes
  const expected = crypto
    .createHmac('sha256', process.env.MERAS_WEBHOOK_SECRET)
    .update(signed)
    .digest('hex');
  if (!parts.v1 ||
      !crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))) {
    return res.status(400).end();
  }

  const event = JSON.parse(req.body);            // { id, type, data, ... }
  if (event.type === 'payment_intent.succeeded') fulfilOrder(event.data.id);
  res.json({ received: true });                  // 2xx within 5s or we retry
});