Settling Value.
Connecting Economies.
Connect With Us
06 / DEVELOPERS

Institutional integration

One contract for exact money, state and evidence.

Karvo exposes tenant-scoped resources for customers, beneficiaries, payment intents, quotes, transfers, settlement obligations, reconciliation cases, webhooks and institutional credentials.

Payment intent / 01

Exact values. Immutable references. Safe replay.

These illustrative contract examples use UUID resource identifiers, OAuth bearer authorization and integer minor-unit strings. Creating an intent requires an existing beneficiary and immutable FX quote; the example does not execute a real rail.

Illustrative create requestKarvo reference
POST /v1/payment-intents
Authorization: Bearer <OAuth access token>
Idempotency-Key: 2d83d542-cd92-4d3f-9b67-63cd0c4f6ea8
Content-Type: application/json

{
  "beneficiary_id": "30000000-0000-0000-0000-000000000001",
  "fx_quote_id": "40000000-0000-0000-0000-000000000001",
  "source_amount": {
    "amount_minor": "2500000",
    "currency": "GHS"
  },
  "reference": "INV-8842"
}
Illustrative created responseKarvo reference
201 Created

{
  "id": "50000000-0000-0000-0000-000000000001",
  "beneficiary_id": "30000000-0000-0000-0000-000000000001",
  "fx_quote_id": "40000000-0000-0000-0000-000000000001",
  "source_amount": {
    "amount_minor": "2500000",
    "currency": "GHS"
  },
  "destination_amount": {
    "amount_minor": "292500000",
    "currency": "NGN"
  },
  "reference": "INV-8842",
  "state": "CREATED",
  "created_at": "2026-08-23T12:00:00Z",
  "provider_reference": null
}

Live availability / 02

The sandbox API, checked at request time.

This server-rendered check reads the backend health boundary without placing credentials, tokens or internal service addresses in the browser.

Live sandbox API

Checking availability

The server is checking the sandbox health boundary. No financial state is inferred from this check.

State model / 03

Integrate against facts—not a success boolean.

Karvo distinguishes customer-visible transfer state from provider attempt certainty, settlement state and reconciliation state.

StateMeaningExpected integration action
CREATEDThe payment intent and economic request exist.Persist the opaque Karvo resource ID.
AWAITING_CONFIRMATIONAn immutable quote is available and has not been accepted.Display exact destination amount, fees, rate and expiry.
AWAITING_APPROVALInstitutional policy requires one or more checker decisions.Wait for approval events; do not create a replacement transfer.
SUBMITTEDOne provider command has been accepted unambiguously.Track the transfer and deduplicate events by event ID.
UNKNOWN_PROVIDER_STATESubmission may have executed, but the response was ambiguous.Do not retry or fail over; await status and reconciliation evidence.
SETTLEDConfigured rail evidence satisfies settlement state.Continue until required reconciliation completes.
REQUIRES_REVIEWA discrepancy or ambiguous outcome needs controlled operations.Use the case and evidence references supplied by Karvo.
FINALFinality evidence, ledger postings and reconciliation policy are satisfied.Close the transaction operationally.

Integration modes / 04

API-first does not mean API-only.

Participant adapters map modern and legacy interfaces into the same canonical contracts and capability model.

01REST / JSON
02ISO 20022
03mTLS / VPN
04SFTP / batch
05Signed webhooks

Scoped authentication

OAuth access tokens bind an active institution principal to the exact API scopes and roles granted for the request.

Financial idempotency

Identical command replay returns the original economic result; changed semantics are rejected.

Signed events

Webhook payloads carry event identity and are signed over timestamp, event ID and raw body.

Correlation

Request, command, event, provider, ledger, settlement and reconciliation identities remain connected.

Explicit conflicts

State conflicts return 409; semantic or idempotency fingerprint mismatch returns 422.

Version discipline

Contracts are additive within v1; breaking semantics require a new API version.

Event reliability / 05

Durable events repair workflows; they do not redefine financial truth.

Each service commits its own state and outbox atomically. Consumers record event identity with their effect, making replay safe under at-least-once delivery.

01

Outbox

A state change and its publishable event commit in the same owned database transaction.

02

Ordered stream

Kafka partitions by tenant and aggregate identity so lifecycle events remain locally ordered and replayable.

03

Inbox

Every consumer deduplicates event IDs in the same transaction as its resulting state change.

04

Repair

Lost callbacks, delayed events and poison messages become observable queues, checkpoints or reconciliation cases.

Work with Karvo

Plan an institutional integration

Tell us where your institution sits in the transaction chain and which corridor or capability you are evaluating.

Start a conversation