Simiz Provider Protocol

{
  "protocol_version": "1",
  "type": "health.check",
  "nonce": "<hex>",
  "timestamp": 1752489600
}

{
  "type": "health.ack",
  "nonce": "<same nonce echoed back>"
}

{
  "protocol_version": "1",
  "type": "payment.execute",
  "idempotency_key": "pexec_9f2c...",
  "amount": "1500.00",
  "currency": "XAF",
  "network": "MTN_MOMO",
  "country": "CM",
  "payee": { "msisdn": "+237670000000" },
  "transaction_ref": "TX-2026-000123",
  "timestamp": 1752489600
}

{
  "type": "payment.ack",
  "idempotency_key": "pexec_9f2c...",
  "status": "ACCEPTED"
}

curl -H "Authorization: Bearer $SIMIZ_PROVIDER_API_KEY" \
  "https://api.simiz.io/v1/provider/orders?status=pending&limit=10"

const SIMIZ_API_URL = process.env.SIMIZ_API_URL ?? 'https://api.simiz.io';
const SIMIZ_PROVIDER_API_KEY = process.env.SIMIZ_PROVIDER_API_KEY;

async function pullOnce() {
  const res = await fetch(`${SIMIZ_API_URL}/v1/provider/orders?status=pending&limit=50`, {
    headers: { authorization: `Bearer ${SIMIZ_PROVIDER_API_KEY}` },
  });
  if (!res.ok) throw new Error(`pull failed: ${res.status} ${await res.text()}`);

  const { orders } = await res.json();
  for (const order of orders) {
    const payload = order.payload;
    const idempotencyKey = order.idempotency_key;
    const accepted =
      payload.type === 'payment.execute'
        ? await executePaymentIdempotently(payload)
        : payload.type === 'payout.execute'
          ? await executePayoutIdempotently(payload)
          : false;

    const ack = {
      type: payload.type === 'payout.execute' ? 'payout.ack' : 'payment.ack',
      idempotency_key: idempotencyKey,
      status: accepted ? 'ACCEPTED' : 'REJECTED',
      ...(!accepted ? { reason: 'Unsupported or duplicate order' } : {}),
    };

    const ackRes = await fetch(`${SIMIZ_API_URL}/v1/provider/orders/${idempotencyKey}/ack`, {
      method: 'POST',
      headers: {
        authorization: `Bearer ${SIMIZ_PROVIDER_API_KEY}`,
        'content-type': 'application/json',
      },
      body: JSON.stringify(ack),
    });
    if (!ackRes.ok) throw new Error(`ack failed ${idempotencyKey}: ${ackRes.status}`);
  }
}

setInterval(() => pullOnce().catch((err) => console.error(err)), 5000);

{
  "protocol_version": "1",
  "type": "payout.execute",
  "idempotency_key": "pexo_9f2c...",
  "amount": "25000.00",
  "currency": "XAF",
  "network": "MTN_MOMO",
  "country": "CM",
  "payee": { "msisdn": "+237670000000" },
  "transaction_ref": "PO-2026-000123",
  "timestamp": 1752489600
}

{
  "type": "payout.ack",
  "idempotency_key": "pexo_9f2c...",
  "status": "ACCEPTED"
}

{
  "protocol_version": "1",
  "idempotency_key": "evt_9f2c...",
  "transaction_ref": "TX-2026-000123",
  "amount": "1500.00",
  "currency": "XAF",
  "status": "COMPLETED",
  "network": "ORANGE_MONEY",
  "settled_at": "2026-07-13T10:00:00Z"
}

GET /v1/provider/agent/assist/protocol-v1-schema

// Generated by Simiz — Protocol v1. Adapt to YOUR data, then deploy ON YOUR SIDE (Simiz hosts nothing).
import crypto from 'node:crypto';

const SIMIZ_SIGNING_SECRET = process.env.SIMIZ_SIGNING_SECRET; // your Simiz secret
const SIMIZ_WEBHOOK_URL = process.env.SIMIZ_WEBHOOK_URL; // your Simiz webhook endpoint

// settlement = your raw settlement record.
export async function sendSettlementToSimiz(settlement) {
  // TODO: map your fields → Protocol v1 payload (amounts in MAJOR units, e.g. "1500.00").
  const payload = {
    protocol_version: '1',
    idempotency_key: settlement.id, // TODO: unique/stable key per settlement
    transaction_ref: settlement.transactionRef, // TODO: your transaction reference
    amount: String(settlement.amount), // TODO: decimal string in major units
    currency: settlement.currency, // TODO: 3-letter ISO-4217 code (e.g. "XAF")
    status: settlement.status, // TODO: PENDING|COMPLETED|FAILED|CANCELLED|REFUNDED
    network: settlement.network, // TODO: ORANGE_MONEY|MTN_MOMO|WAVE|MOOV_MONEY
    settled_at: settlement.settledAt, // TODO: ISO-8601 with offset (e.g. "2026-07-13T10:00:00Z")
  };

  // Sign the EXACT string sent (sha256 hex) — do not serialize again elsewhere.
  const body = JSON.stringify(payload);
  const signature = crypto.createHmac('sha256', SIMIZ_SIGNING_SECRET).update(body).digest('hex');

  const res = await fetch(SIMIZ_WEBHOOK_URL, {
    method: 'POST',
    headers: {
      'content-type': 'application/json',
      'x-simiz-signature': signature,
    },
    body,
  });
  if (!res.ok) throw new Error(`Simiz webhook rejected: ${res.status} ${await res.text()}`);
  return res;
}

// baseUrl handler — verify X-Simiz-Signature over `${timestamp}.${rawBody}` FIRST (401/403 if invalid).
const event = JSON.parse(rawBody);

if (event.type === 'health.check') {
  return { type: 'health.ack', nonce: event.nonce }; // echo the nonce, respond HTTP 200
}

if (event.type === 'payment.execute') {
  // Duplicate idempotency_key? Ack it again, do NOT execute twice.
  enqueueExecutionOnYourRail(event); // async — your licensed rail does the money movement
  // Later: push a SettlementEvent to your Simiz webhook with this same idempotency_key.
  return { type: 'payment.ack', idempotency_key: event.idempotency_key, status: 'ACCEPTED' };
}

if (event.type === 'payout.execute') {
  enqueuePayoutOnYourRail(event); // async — payout-capable rails only
  return { type: 'payout.ack', idempotency_key: event.idempotency_key, status: 'ACCEPTED' };
}

// ... handle other v1 events here

You are implementing a provider endpoint for Simiz Provider Protocol v1.

Goal:
- Implement one HTTPS `baseUrl` handler on the provider side for signed Simiz -> provider calls.
- Emit signed provider -> Simiz `SettlementEvent` payloads from your rail after execution.
- Simiz orchestrates only; the provider executes payments on its licensed rails and hosts this code.

Direction 1: Simiz -> provider `baseUrl`
- Verify `X-Simiz-Signature` before JSON parsing.
- Signature scheme: HMAC-SHA256 hex over `{X-Simiz-Timestamp}.{rawBody}` using the same rail webhook secret `whsec_...`.
- `X-Simiz-Event: health.check` payload:
  { "protocol_version": "1", "type": "health.check", "nonce": "<hex>", "timestamp": 1752489600 }
- Reply HTTP 200:
  { "type": "health.ack", "nonce": "<same nonce echoed back>" }
- `X-Simiz-Event: payment.execute` payload schema:
  {
    "protocol_version": "1",
    "type": "payment.execute",
    "idempotency_key": "pexec_9f2c...",
    "amount": "1500.00",
    "currency": "XAF",
    "network": "MTN_MOMO",
    "country": "CM",
    "payee": { "msisdn": "+237670000000" },
    "transaction_ref": "TX-2026-000123",
    "timestamp": 1752489600
  }
- `payee` must contain exactly one of `msisdn` or `ref`.
- Reply HTTP 200 synchronously:
  { "type": "payment.ack", "idempotency_key": "<same key>", "status": "ACCEPTED" }
- To refuse, use `"status": "REJECTED"` and optional `"reason"`.
- The ack only means accepted for async execution, not paid.
- Deduplicate by `idempotency_key`; retries use the same key. Do not execute twice.
- Later, push a `SettlementEvent` to Simiz with the same `idempotency_key` or matching `transaction_ref`.
- Optional payout rail support uses the same envelope with `X-Simiz-Event: payout.execute`:
  {
    "protocol_version": "1",
    "type": "payout.execute",
    "idempotency_key": "pexo_9f2c...",
    "amount": "25000.00",
    "currency": "XAF",
    "network": "MTN_MOMO",
    "country": "CM",
    "payee": { "msisdn": "+237670000000" },
    "transaction_ref": "PO-2026-000123",
    "timestamp": 1752489600
  }
- Reply HTTP 200:
  { "type": "payout.ack", "idempotency_key": "<same key>", "status": "ACCEPTED" }
- Reject with `"status": "REJECTED"` and optional `"reason"` when the payout cannot be accepted.
- If using Pull API instead of a webhook `baseUrl`, poll `/v1/provider/orders`, execute each returned payload, then POST the matching `payment.ack` or `payout.ack` to `/v1/provider/orders/:idempotencyKey/ack`.

Direction 2: provider -> Simiz `SettlementEvent`
- Send exactly these 8 fields:
  {
    "protocol_version": "1",
    "idempotency_key": "evt_9f2c...",
    "transaction_ref": "TX-2026-000123",
    "amount": "1500.00",
    "currency": "XAF",
    "status": "COMPLETED",
    "network": "ORANGE_MONEY",
    "settled_at": "2026-07-13T10:00:00Z"
  }
- Field rules:
  - `protocol_version`: literal `"1"`
  - `idempotency_key`: non-empty stable idempotency key
  - `transaction_ref`: non-empty provider transaction reference
  - `amount`: decimal string in major units, never cents
  - `currency`: 3-letter ISO-4217 code
  - `status`: PENDING, COMPLETED, FAILED, CANCELLED, or REFUNDED
  - `network`: ORANGE_MONEY, MTN_MOMO, WAVE, or MOOV_MONEY
  - `settled_at`: ISO-8601 datetime with offset
- Sign the exact JSON body bytes you send. Do not re-serialize after signing.
- Post with `content-type: application/json` and `x-simiz-signature`.

Implementation guardrails:
- Use the raw body for signature verification.
- Use the rail `whsec_...` key for Webhook transport calls (`health.check`, `payment.execute`, `payout.execute`). Use your provider webhook/channel signing secret for settlement events sent back to Simiz.
- Reject invalid signatures with 401 or 403.
- Echo nonce and idempotency keys exactly.
- Preserve idempotency across order, ack, execution, and settlement.
- Return explicit errors for unsupported corridors or blocked payees; never silently accept.