Skip to main content

API Reference

The Kora Remittance API is organized around REST. It accepts JSON request bodies, returns JSON responses, and uses standard HTTP status codes. The full machine-readable spec is available as remittance.yaml (OpenAPI 3.1).

Base URL​

https://api.korastratum.com/api/v1/remittance      # production
https://sandbox.korastratum.com/api/v1/remittance  # sandbox

Authentication​

HeaderValueUsed by
AuthorizationBearer kora_… (API key) or Bearer <session-jwt>Server calls / end-user calls
X-Tenant-IDTenant UUIDAll calls
X-Partner-API-KeyPartner keyPOST /auth/partner-token only

See Authentication for the full model.

Quotes​

Create a quote — POST /quotes​

Locks the FX rate and fees for a corridor for a short window.

// request
{ "sendAmount": "100.00", "sendCurrency": "USD", "receiveCurrency": "PHP", "destinationCountry": "PH" }

// 201
{ "quoteId": "3c8a1f7e-…", "exchangeRate": "56.0000", "receiveAmount": "5600.00",
  "receiveCurrency": "PHP", "feeTotal": "1.50", "expiresAt": "2026-08-10T14:15:00Z" }

Transfers​

Create a transfer — POST /transfers​

Creates a transfer against a quote. The sender comes from the session token. Gated by KYC and screening — an unverified sender returns 422.

// request
{ "quoteId": "3c8a1f7e-…", "recipientId": "9f2c6d10-…",
  "transferReason": "family_support", "sourceOfFunds": "salary", "relationshipToRecipient": "family" }

// 201
{ "id": "3c8a1f7e-…", "reference": "TXN-8ZK3QP", "status": "created",
  "sendAmount": "100.00", "sendCurrency": "USD", "receiveAmount": "5600.00", "receiveCurrency": "PHP" }

List transfers (history) — GET /transfers​

Returns the authenticated user's transfers, most recent first. The user id comes from the token — a caller only ever sees their own transfers. Paginated with page (default 1) and pageSize (default 20, max 100).

// 200
{ "transfers": [ { "id": "…", "reference": "TXN-8ZK3QP", "status": "completed",
    "sendAmount": "100.00", "receiveAmount": "5600.00", "recipientName": "Maria S.",
    "createdAt": "2026-08-10T14:10:02Z" } ],
  "totalCount": 42, "page": 1, "pageSize": 20 }

Get a transfer — GET /transfers/{id}​

Retrieve one transfer by UUID, including its status-history events for rendering a timeline.

Statuses: created · funded · processing · completed · failed · refunded.

Corridors​

List supported corridors — GET /corridors​

Returns the corridors available to the tenant, with supported currencies and destination countries.

// 200
{ "corridors": [ { "sendCurrency": "USD", "receiveCurrency": "PHP", "destinationCountry": "PH", "enabled": true } ] }

Handoff​

Partner-initiated SSO. Full guide: Partner Handoff.

Mint a handoff token — POST /auth/partner-token​

Server-to-server with X-Partner-API-Key. Returns a one-time, short-lived token and a redirect URL.

// request
{ "partnerUserId": "usr_abc123", "phone": "+15551234567", "email": "user@example.com",
  "returnUrl": "https://app.yourbrand.com/wallet" }

// 200
{ "token": "<one-time-jwt>", "redirectUrl": "https://app.yourbrand.com/handoff?t=<jwt>", "expiresIn": 120 }

Exchange a handoff token — POST /auth/exchange-token​

Exchanges a one-time handoff token for an end-user session. No other credential required.

// request
{ "token": "<one-time-jwt>" }

// 200
{ "token": "<session-jwt>", "refreshToken": "…", "expiresIn": 3600 }

Webhooks​

Transfer lifecycle events are delivered to your endpoint as signed HTTP POSTs. See Webhooks for the payload, headers, and HMAC-SHA256 verification.

Errors​

Errors return a JSON body { "error": "…", "code": "…" } with a standard HTTP status: 400 invalid request, 401 bad credentials, 404 not found, 422 compliance/KYC not satisfied.