Partner integration guide

1 · The Partner API

Base URL https://smartremit.ai/api/partner/v1. Authenticate every request with your API key (issued in the dashboard, shown once):

Authorization: Bearer <your-api-key>

Errors are JSON: { "error": "…" }. 503 means live FX is temporarily unavailable (or another transfer for the same sender is in progress) and nothing was minted — retry later (a POST /transactions retry may reuse the same Idempotency-Key; see Idempotency).

# Mint a transfer (idempotent — safe to retry with the same key)
curl -X POST $BASE/transactions \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: 5f0c8a3e-2b7d-4e61-9a4f-0d3b8c1e7a52" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_source": 200,
    "source_currency": "USD",
    "sender":      { "phone": "15551230000", "name": "Maria Lopez", "kyc_status": "verified" },
    "beneficiary": { "name": "Anita Sharma", "phone": "919876543210",
                     "payout_method": "bank", "payout_destination": "123456789012|HDFC0001234" }
  }'

Compliance screening (sanctions) runs on every mint regardless of KYC mode — a watchlist hit returns 422 and the attempt is recorded as blocked. (In today's demonstration it runs against a built-in reference rule set, not yet a live commercial AML feed.) A later request with the same Idempotency-Key returns that blocked transaction with 200 — see Idempotency. A payout_destination that is a masked display value (for example ****1234 or account on file) is refused with 422 before the Idempotency-Key is bound. Idempotency-Key values beginning draft:, b2binvoice:, sched: or test: are reserved and refused with 400. A payer can never change the beneficiary account of a transaction created through this API: every transaction is bound to its Idempotency-Key before it is created, and that binding locks the account. A transaction still awaiting_payment and unpaid 7 days after it was created expires: its status becomes cancelled and it can no longer be paid.

Names — beneficiary.name, sender.name and the name of a stored beneficiary — must be 1–80 characters with no brackets ([ ] { } < >) and no control or line-break characters. payout_method must be one of bank, upi or usdc (default bank), and an inline payout_destination is at most 64 printable characters. destination_country is optional and defaults to IN; when present it must be one of US, CA, GB, AE, SG, AU, NZ, IN, HK, MX — any other value is refused with 400 (it is never coerced to India). Each is refused with 400 before the Idempotency-Key is bound, so a corrected retry with the same key succeeds. Transactions created through this API are never added to the customer's saved recipients in chat.sender.name is optional today but strongly recommended: a transaction created without it is held for manual review (it is created with compliance_status flagged, and confirming it returns in_review until compliance staff release it). sender.name will become required in a future version.

curl "$BASE/settlements?from=2026-09-01&to=2026-09-08&limit=100" \
  -H "Authorization: Bearer $KEY"

{
  "settlements": [
    { "reference": "Qm9…", "status": "delivered", "compliance_status": "cleared",
      "refund_status": "none", "amount_source": 200, "source_currency": "USD",
      "fee_source": 1.99, "total_charge_source": 201.99, "fx_rate": 85.2,
      "amount_destination": 17040, "destination_currency": "INR",
      "destination_country": "IN", "payout_rail": "bank",
      "provider_ref": "simrail-Qm9…", "funding_ref": null, "refund_ref": null,
      "created_at": "2026-09-02T10:00:00.000Z", "paid_at": "2026-09-02T10:01:12.345Z",
      "delivered_at": "2026-09-02T10:01:20.000Z", "refunded_at": null }
  ],
  "next_cursor": null,
  "totals": { "count": 1,
              "amount_source_minor_by_currency": { "USD": 20000 },
              "amount_destination_minor_by_currency": { "INR": 1704000 } },
  "window": { "from": "2026-09-01T00:00:00.000Z", "to": "2026-09-08T00:00:00.000Z" }
}

# The same page as CSV
curl -OJ "$BASE/settlements?from=2026-09-01&to=2026-09-08&format=csv" \
  -H "Authorization: Bearer $KEY"

2 · Rates (compete for routed flow)

Push the wholesale conversion rate you offer per corridor with PUT /rates. When your fresh rate beats the platform mid-market rate (and your settlement rail is configured), SmartRemit routes eligible platform transfers to you for settlement. Pushing a rate does not change the pricing of your own /quote or /transactions — those stay at platform mid-market.

# Push your USD→INR rate (fresh for 30 minutes)
curl -X PUT https://smartremit.ai/api/partner/v1/rates \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "source_currency": "USD", "destination_currency": "INR",
        "effective_rate": 86.4, "ttl_seconds": 1800 }'

# → 200
{ "source_currency": "USD", "destination_currency": "INR",
  "effective_rate": 86.4, "expires_at": "…", "pushed_at": "…" }

GET /rates returns your sheet: { "rates": [ { source_currency, destination_currency, effective_rate, expires_at, fresh, margin_bps } ] } — fresh tells you whether the pushed rate is still competing; margin_bps is your standing platform-configured fallback margin.

3 · Settlement instructions (us → you)

When a transfer is paid (pay page or /confirm), SmartRemit POSTs a signed instruction to your configured settlement endpoint — with automatic retries and exponential backoff until your rail acks 2xx. Every instruction carries a timestamped signature in the x-smartremit-signature header — verify it (see Signatures below).

POST <your settlementUrl>
x-smartremit-signature: t=1790000000,v1=5d2e…   # recommended — verify this
x-signature: 3f1a…                              # deprecated — HMAC-SHA256 of the raw body

{
  "reference": "tr_abc123",          // OUR transfer id — echo it in callbacks
  "partner_id": "acme",
  "corridor": { "source": "US", "destination": "IN" },
  "payout":   { "rail": "bank", "destination": "123456789012|HDFC0001234" },
  "recipient":{ "name": "Anita Sharma", "phone": "919876543210" },
  "amount": {
    "source": 200, "currency": "USD",
    "destination": 16600, "destination_currency": "INR",
    "fx_rate": 83                     // locked at quote time
  }
}

Respond 2xx with an optional { "providerRef": "…" } — stored write-once against the transfer. Use reference to deduplicate: the instruction is at-least-once.

Ack deadline: 15 seconds. We wait at most 15s for your 2xx; a slower response is treated as a failure and the SAME instruction (same reference) is retried with exponential backoff. Persist and ack first, then process asynchronously — and dedupe on reference, so a retry after a slow ack can never pay out twice.

Endpoint requirements. Your settlementUrl must be a public https:// host on port 443 (no IP literals, no internal or single-label names, no credentials in the URL). We follow at most two redirects, only 307/308 to the same origin — never a 301/302/303, which would turn the signed POST into a GET. Your ack must be 64 KB or less, uncompressed (we send Accept-Encoding: identity and never decompress), and providerRef is at most 128 characters of A–Z a–z 0–9 . _ : -. An endpoint that fails these checks is refused before the instruction is sent: the instruction is retried with backoff and then raises an ops alert, so fix the endpoint in Admin → Partners → Payment and the retries pick it up.

"compliance": {
  "version": 1,
  "originator": {                     // null when routed or unavailable
    "entity_type": "individual",      // or "business" (name = the business)
    "name": "Ravi Kumar", "country": "US", "phone": "15551230000",
    "id_type": "passport", "id_last4": "1234"
  },
  "beneficiary": { "entity_type": "individual", "name": "Anita Sharma",
                   "relationship": "parent", "country": "IN" },
  "purpose": "family_support",
  "purpose_code": null,
  "kyc": { "status": "verified", "tier": "T1", "verified_at": "2026-09-01T12:00:00.000Z" },
  "screening": { "status": "cleared", "reasons": [],
                 "screened_at": "2026-09-23T10:00:00.000Z",
                 "list_source": "…", "list_version": "…", "decision": "clear" },
  "edd_required": false
}

signed = t + "." + rawBody            // the exact bytes received
expected = hex(HMAC_SHA256(secret, signed))
valid = |now - t| <= 300 seconds
        AND some v1 in the header equals expected (constant-time compare)

4 · Status webhooks (you → us)

Report lifecycle status to POST /api/payment-webhook/<provider>, signed with your webhookSecret using the timestamped signature (fail-closed: unsigned, mis-signed or out-of-window callbacks are rejected with 401).

POST /api/payment-webhook/acme-rail
x-smartremit-signature: t=1790000000,v1=9c44…   # HMAC-SHA256(webhookSecret, t + "." + rawBody)

{ "reference": "tr_abc123", "status": "paid_out",
  "amount": { "destination": 16600, "destination_currency": "INR" } }

Amount on paid_out: echo the amount.destination and destination_currency from our instruction. If they differ from what we instructed (to the minor unit), the transfer is not delivered: it is held for our ops team, who resolve it with you, and we answer { "ok": true, "held": true } so you stop retrying. A paid_out without an amount is accepted for now but is deprecated.

No rail yet? Point your integration at the hosted reference rail (providerType: simulator) — it verifies your signatures, acks a providerRef, and calls the public webhook back ~12s later, running the exact production loop end to end. To exercise the failure path, pay to a bank account that is all zeros (for India: account 000000000000, IFSC HDFC0001234): the reference rail acks, then reports failed with reason account_unreachable.

5 · Your WhatsApp number & KYC mode

Bring your own Meta WhatsApp Business number: configure the phone-number id, access token, verify token, and app secret in the dashboard, then point Meta's webhook at your dedicated callback URL (shown on your partner page). Inbound messages on your number route to your tenant — replies, OTPs, and delivery notifications leave from your number under your brand.

KYC: run it yourself (delegated mode — you attest verification) or use SmartRemit's built-in tiered KYC. Sanctions screening is not delegable — it always runs on our side and cannot be switched off.

Hi {{1}}, you've received {{2}} from the sender with phone number {{3}}. It's on its way to your {{4}}.

{{1}} recipient name       sample: Priya
{{2}} amount delivered     sample: ₹4,750
{{3}} sender phone, masked sample: ••••4567
{{4}} payout label         sample: bank account