What it actually takes to ship Raast as an aggregator

The problem isn’t calling an API

1. Identity and onboarding — link or create a Raast merchant, then persist the aggregator merchant token your payment calls will need forever after.
2. Pay-in product choice — RTP Now vs RTP Later vs Dynamic QR vs Static QR, each with different UX and expiry semantics.
3. Payouts — same stack, different amount unit, different mental model for status.
4. Asynchronous truth — customers approve inside banking apps; your system learns the outcome from webhooks, not from the create response alone.
5. Verification — HMAC over the raw body, idempotent event handling, reconciliation that survives retries.

Environments and the auth header that isn’t Bearer

const headers = {
  'Content-Type': 'application/json',
  'X-SFPY-AGGREGATOR-SECRET-KEY': process.env.SAFEPAY_SECRET_KEY!,
};

const baseUrl =
  process.env.SAFEPAY_ENV === 'production'
    ? 'https://api.getsafepay.com/raastwire'
    : 'https://dev.api.getsafepay.com/raastwire';

const aggregatorId = process.env.SAFEPAY_AGGREGATOR_ID!;

Merchant onboarding is where state management starts

const createMerchantResponse = await fetch(
  `${baseUrl}/v1/aggregators/${aggregatorId}/merchants`,
  {
    method: 'POST',
    headers,
    body: JSON.stringify({
      merchant_external_id: 'sec_0c3de397-441f-471f-bcd7-b6d948e1c307',
      iban: 'PK62ABPA0010000222380013',
      name: 'Acme Foods Saddar',
      enabled: true,
      raast_merchant_id: raastMerchantId,
      rate_card: {
        ratecard_kind: 'RateCardKind_fixed',
        fixed_rate: 3000, // paisa
        tax_region: 'PK',
        tax_rate: 0.1,
      },
    }),
  },
);

if (!createMerchantResponse.ok) {
  const errorBody = await createMerchantResponse.json();
  throw new Error(
    `Safepay Raast error: ${createMerchantResponse.status} ${errorBody.message}`,
  );
}

const merchantPayload = await createMerchantResponse.json();
// Persist this. Payments and QR will not invent it for you.
const aggregatorMerchantIdentifier = merchantPayload.data.token;

Choosing a pay-in shape

RTP Now: the checkout-shaped path

// Amount is in paisa (PKR minor units). 94000 = PKR 940.00
const rtpResponse = await fetch(
  `${baseUrl}/v1/aggregators/${aggregatorId}/payments`,
  {
    method: 'POST',
    headers,
    body: JSON.stringify({
      request_id: crypto.randomUUID(),
      amount: 94000,
      aggregator_merchant_identifier: aggregatorMerchantIdentifier,
      order_id: 'ORDER-RAAST-001',
      type: 'RTP_NOW',
      expiry_in_minutes: 45,
      debitor_iban: 'PK89SCBL0000001234651601',
      // Or: debitor_raast_id / debitor_vault_token
    }),
  },
);

if (!rtpResponse.ok) {
  const errorPayload = await rtpResponse.json();
  throw new Error(
    `RTP request failed: ${rtpResponse.status} ${errorPayload.message}`,
  );
}

const paymentPayload = await rtpResponse.json();
// Treat create success as “request accepted,” not “money settled.”

Dynamic QR: when you know the amount, not the payer

const qrResponse = await fetch(
  `${baseUrl}/v1/aggregators/${aggregatorId}/qrs`,
  {
    method: 'POST',
    headers,
    body: JSON.stringify({
      type: 'DYNAMIC',
      aggregator_merchant_identifier: aggregatorMerchantIdentifier,
      order_id: 'ORDER-4921',
      request_id: crypto.randomUUID(),
      amount: 7500, // paisa; omit to let the payer choose
      expiry_in_minutes: 180,
    }),
  },
);

if (!qrResponse.ok) {
  const errorPayload = await qrResponse.json();
  throw new Error(
    `Dynamic QR failed: ${qrResponse.status} ${errorPayload.message}`,
  );
}

const qrPayload = await qrResponse.json();
// Render data.code (EMVCo string) with any QR library

The amount unit bug that keeps shipping

• Pay-ins (/payments, /qrs): amount is paisa — an integer minor unit. 94000 means PKR 940.00.
• Payouts (/payout): amount is a PKR string. "200" means PKR 200.

Payouts: same stack, different status story

// Payout amount is a PKR string (not paisa). "200" = PKR 200.
const payoutResponse = await fetch(
  `${baseUrl}/v1/aggregators/${aggregatorId}/payout`,
  {
    method: 'POST',
    headers,
    body: JSON.stringify({
      request_id: crypto.randomUUID(),
      amount: '200',
      creditor_iban: 'PK25ALFH0216001008658216',
    }),
  },
);

if (!payoutResponse.ok) {
  const error = await payoutResponse.json();
  throw new Error(`Payout failed: ${payoutResponse.status} ${error.message}`);
}

Webhooks are the source of truth

import crypto from 'node:crypto';

export function verifySafepayWebhook(opts: {
  secretBase64: string;
  rawBody: Buffer | string;
  signatureHeader: string; // X-SFPY-SIGNATURE, e.g. sha256=...
  timestampHeader: string; // X-SFPY-TIMESTAMP, RFC 3339
  toleranceMs?: number; // default 5 minutes
}): boolean {
  const toleranceMs = opts.toleranceMs ?? 5 * 60 * 1000;
  const ts = Date.parse(opts.timestampHeader);
  if (Number.isNaN(ts) || Math.abs(Date.now() - ts) > toleranceMs) {
    return false;
  }

  const secret = Buffer.from(opts.secretBase64, 'base64');
  const body =
    typeof opts.rawBody === 'string' ? Buffer.from(opts.rawBody) : opts.rawBody;
  const mac = crypto.createHmac('sha256', secret);
  mac.update(opts.timestampHeader);
  mac.update('.');
  mac.update(body);
  const expected = `sha256=${mac.digest('hex')}`;

  const a = Buffer.from(expected);
  const b = Buffer.from(opts.signatureHeader);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

1. Read the raw body plus X-SFPY-TIMESTAMP, X-SFPY-SIGNATURE, and X-SFPY-EVENT-ID.
2. Reject stale timestamps (default ±5 minutes).
3. Verify HMAC with a timing-safe compare.
4. Upsert by X-SFPY-EVENT-ID so retries are idempotent.
5. Return 2xx quickly; do heavy work async.
6. Invalid signatures → 4xx so you do not invite retry storms on bad traffic.

Where integrations stall (and how to unstick them)

An end-to-end verification bar

1. Create and persist a merchant token.
2. Initiate one pay-in (RTP Now or Dynamic QR) with a known order_id.
3. Complete or simulate customer approval in the documented sandbox flow.
4. Receive and verify a webhook; confirm your upsert key is the event id.
5. Reconcile your ledger row against Safepay’s payment object.
6. Send a small payout; confirm status arrives on payment.* as PAYOUT.
7. Intentionally break verify (wrong secret or mutated body) and confirm you return 4xx without marking paid.

Ops checklist

• Secrets only in vault; rotation runbook tested
• Sandbox end-to-end: merchant → RTP or QR → webhook → reconcile
• Amount units reviewed in code review (paisa vs PKR string)
• Webhook verify uses raw body; no JSON re-stringify
• Payout listeners on payment.*, not payout.*
• Idempotent request_id policy documented for client teams
• Reconciliation matches Safepay settlement views
• Alerts on verify failures and elevated Safepay 4xx

Getting started

1. Request aggregator access and store your secret key.
2. Create and link merchants; persist data.token.
3. Ship one pay-in path plus webhook verify before you add a second product surface.
4. Add payouts once settlement and event handling are solid.
5. Harden ops: rotation, reconciliation, alerts.

• Introduction
• Raast integration journey
• API reference
• Legacy docs