Instant payment API

Redress, fund recovery, and instant payment system integration endpoints used in Trust Layer deployments.

The instant payment API is the technical interface behind Proto's Trust Layer: the redress, fund recovery, and instant payment system (IPS) integration used in anti-scam centre and financial-regulator deployments. It connects three systems – citizen-facing case intake, cross-institution fund tracing and freezing (via FNA's Money Trails engine), and the national instant payment operator's own risk and settlement rails.

These endpoints are provisioned as part of a Trust Layer deployment – an anti-scam centre, central bank, or instant payment system integration – rather than the standard self-serve workspace API documented elsewhere in this section. Contact your Proto deployment team to enable access for your institution.

This reference is drawn from the technical specification set out in Redress and fund recovery in digital public infrastructure (Proto and FNA, July 2026), together with real payload examples from live FNA integrations. Field names, latency targets, and rate limits vary by deployment – confirm against your own integration agreement before building against them.

Redress system

Citizen-facing case intake, routing, dispute resolution, and status notification.

Receive complaint

Receives a complaint from voice AI, SMS, or web, validates it, and generates a case ID.

URL

POST /v1/cases/intake

Latency: <2s (p99) · Rate limit: 1,000/min

Body

{
  "citizen_id_hash": "string",
  "scam_type": "string",
  "transaction_reference": "string",
  "amount": "number",
  "receiving_account_hint": "string",
  "confidence_metadata": {}
}

Returns

{
  "case_id": "string"
}

Get case status

Retrieves case status, the recovery trace summary, and the freeze timeline.

URL

GET /v1/cases/{case_id}

Latency: <500ms · Rate limit: unlimited (case owner), 100/min (analyst)

Returns

{
  "case_id": "string",
  "status": "string",
  "recovery_trace_summary": {},
  "freeze_status_timeline": [],
  "next_milestone": "string"
}

Route case

Routes a case to an analyst queue, institution, or the recovery engine, based on priority.

URL

POST /v1/cases/{case_id}/route

Latency: <1s

Body

{
  "routing_logic": "string",
  "target_institution_codes": [],
  "assigned_analyst_id": "string",
  "internal_notes": "string"
}

Initiate online dispute resolution

Initiates online dispute resolution (ODR) between the citizen and the receiving institution.

URL

POST /v1/cases/{case_id}/odr

Latency: <2s to open the case · 2-hour institutional SLA

Body

{
  "institution_code": "string",
  "dispute_amount": "number",
  "settlement_authority": "string",
  "dispute_timeline_hours": "number"
}

Classify case

Submits the final case classification: scam type, recovery outcome, and any institutional control failures.

URL

POST /v1/cases/{case_id}/classify

Latency: <5s

Body

{
  "final_scam_type": "string",
  "recovery_outcome": "string",
  "recovery_amount": "number",
  "primary_institution_code": "string",
  "institutional_control_failure": [],
  "repeat_victim": "boolean",
  "case_duration_hours": "number"
}

Notify citizen

Sends a case status update to the citizen by SMS, voice callback, or email, in their own language.

URL

POST /v1/cases/{case_id}/notify

Latency: <3s (SMS <30s, voice callback <5min) · Rate limit: 100k/min

Body

{
  "notification_type": "string",
  "delivery_channels": [],
  "message_variables": {}
}

Recovery system

Cross-institution fund tracing, mule-account detection, freezing, and victim fund return, built on FNA's Money Trails engine (see Redress and fund recovery in digital public infrastructure).

Initiate trace

Initiates a Money Trails graph analysis: a full cross-institutional trace of the reported transaction, reconstructing the payment chain to identify mule accounts.

URL

POST /v1/recovery/trace

Latency: <30s (p95) · Rate limit: 10,000/min

Body

{
  "case_id": "string",
  "originating_transaction_id": "string",
  "originating_amount": "number",
  "sender_institution_code": "string",
  "initial_receiver_account_hash": "string",
  "trace_depth": "number",
  "mule_detection_sensitivity": "string"
}

Returns

{
  "trace_id": "string"
}

Example – FNA Money Trails intake. FNA's own scam-report schema is richer than the illustrative field list above, since it reflects the live production contract used to escalate a case. It carries full victim KYC and a per-leg transaction breakdown rather than hashed identifiers:

{
  "inputType": "AI Assistant",
  "reportingType": "First Party",
  "victimIdNo": "1199080123456789",
  "victimIdType": "National ID",
  "victimName": "Claudine Uwase",
  "victimNationality": "Rwanda",
  "victimContact": "+250788123456",
  "victimAccountFiName": "MTN",
  "victimAccountHolder": "Claudine Uwase",
  "reportedLossCurrency": "USD",
  "reportedLossAmount": 150,
  "incidentType": "Telecommunication Scam",
  "incidentDateTimeFrom": "2026-08-05T06:40:00",
  "incidentDateTimeTo": "2026-08-05T06:45:00",
  "incidentDetails": "A caller claiming to be an MTN MoMo support agent obtained Claudine's mobile-money PIN. USD 150 was transferred from her wallet without authorization",
  "victimAccounts": [
    {
      "victimAccountNo": "RW00-MOMO-000-4471-8890"
    }
  ],
  "reportedReceivingAccounts": [],
  "transactions": [
    {
      "inputType": "AI Assistant",
      "transactionId": "TXN-88410021",
      "transactionDateTime": "2026-08-05T06:42:00",
      "transactionType": "Instant payment",
      "currency": "USD",
      "amount": 100,
      "victimName": "Claudine Uwase",
      "victimAccountFi": "MTN",
      "victimAccountNo": "RW00-MOMO-000-4471-8890",
      "receiverName": "Zulfiqar Husain",
      "receiverAccountFi": "EQB",
      "receiverAccountNo": "RW01-ACCT-113-9921-0034"
    },
    {
      "inputType": "AI Assistant",
      "transactionId": "TXN-88410088",
      "transactionDateTime": "2026-08-05T06:44:00",
      "transactionType": "Instant payment",
      "currency": "USD",
      "amount": 50,
      "victimName": "Claudine Uwase",
      "victimAccountFi": "MTN",
      "victimAccountNo": "RW00-MOMO-000-4471-8890",
      "receiverName": "Zulfiqar Husain",
      "receiverAccountFi": "EQB",
      "receiverAccountNo": "RW01-ACCT-113-9921-0034"
    }
  ]
}

reportingType distinguishes victim self-reports ("First Party") from other reporter classes. inputType is carried at both report and transaction level, so a case built up from more than one source stays auditable. reportedReceivingAccounts is populated when a citizen names a suspect account with no matching transaction ID. Valid values for the enum-like fields (reportingType, incidentType, victimIdType, transactionType) beyond those shown here should be confirmed against FNA's own schema documentation before this becomes the canonical example.

Get trace results

Retrieves the detailed trace results: the account chain, risk scores, and intervention recommendations, ranked by urgency and recovery potential.

URL

GET /v1/recovery/trace/{trace_id}

Latency: <500ms · Rate limit: unlimited

Returns

{
  "trace_id": "string",
  "status": "string",
  "account_chain": [
    {
      "account_hash": "string",
      "institution_code": "string",
      "balance": "number",
      "risk_score": "number",
      "risk_factors": [],
      "withdrawal_method": "string"
    }
  ],
  "intervention_recommendations": [
    {
      "rank": "number",
      "account_hash": "string",
      "funds_present": "boolean",
      "recommended_action": "string",
      "time_to_recovery_risk": "string"
    }
  ]
}

Initiate freeze

Initiates an account freeze at the receiving institution – a time-limited administrative hold or a legal order.

URL

POST /v1/recovery/freeze

Latency: <30s to issue the order · institution acknowledgement <5min · Rate limit: 1,000/min

Body

{
  "case_id": "string",
  "trace_id": "string",
  "account_hash": "string",
  "institution_code": "string",
  "freeze_amount": "number",
  "freeze_type": "string",
  "freeze_duration_hours": "number",
  "legal_justification": "string",
  "freeze_authorization_token": "string"
}

Get freeze status

Retrieves freeze status, remaining duration, and the receiving institution's compliance.

URL

GET /v1/recovery/freeze/{freeze_id}

Latency: <500ms · Rate limit: unlimited

Returns

{
  "freeze_id": "string",
  "freeze_status": "string",
  "freeze_expiry_timestamp": "string",
  "hours_remaining": "number",
  "funds_frozen_amount": "number",
  "institution_compliance": {},
  "legal_order_status": "string"
}

Extend freeze

Extends a freeze's duration. Requires a legal order or renewed administrative authority.

URL

POST /v1/recovery/freeze/{freeze_id}/extend

Latency: <5s

Body

{
  "extension_hours": "number",
  "extension_justification": "string",
  "legal_order_reference": "string"
}

Release freeze

Releases a freeze – on expiry, court order, or a non-fraud determination.

URL

POST /v1/recovery/freeze/{freeze_id}/release

Latency: <10s to issue the release order

Body

{
  "release_reason": "string",
  "release_authority": "string",
  "release_authorization_token": "string"
}

Return funds

Initiates the return of recovered funds to the verified victim, from a frozen account or the victim fund pool.

URL

POST /v1/recovery/fund-return

Latency: <30min to initiate · delivery <24h

Body

{
  "case_id": "string",
  "freeze_id": "string",
  "victim_account_identifier": "string",
  "victim_institution_code": "string",
  "return_amount": "number",
  "return_method": "string",
  "return_narrative": "string"
}

Get mule score

Generates a composite mule-detection risk score for an account. Called internally by Money Trails, or on its own.

URL

POST /v1/recovery/mule-score

Latency: <2s (p99) · Rate limit: 100k/min

Body

{
  "account_hash": "string",
  "institution_code": "string",
  "include_peer_network": "boolean",
  "peer_network_depth": "number"
}

Generate legal document

Generates standardised legal documentation – a freeze order, police hold, regulatory directive, or reimbursement warrant – ready for signature.

URL

POST /v1/recovery/legal-document

Latency: <3s

Body

{
  "case_id": "string",
  "document_type": "string",
  "jurisdiction": "string",
  "account_hash": "string",
  "institution_code": "string",
  "freeze_amount": "number",
  "freeze_duration_days": "number",
  "template_language": "string"
}

Instant payment system

The operator-facing side of the integration: real-time transaction enrichment, fraud scoring fed back into the IPS's own risk engine, Confirmation of Payee-style account verification, and participant onboarding.

Submit transaction metadata

The IPS operator submits transaction metadata in real time, for enrichment, risk scoring, and pre-emptive intervention. Fire-and-forget – must not block settlement.

URL

POST /v1/ips/transaction-metadata

Latency: <500ms, must not block settlement · Rate limit: no limit

Body

{
  "transaction_id": "string",
  "transaction_timestamp": "string",
  "amount": "number",
  "sender_institution_code": "string",
  "receiver_institution_code": "string",
  "high_value_flag": "boolean",
  "geographic_anomaly_detected": "boolean",
  "time_of_day_anomaly_detected": "boolean",
  "transaction_narrative": "string"
}

Get fraud risk score

Returns the fraud risk score for a transaction to the IPS's own risk engine, enabling pre-settlement overlays, delayed settlement, or additional verification.

URL

POST /v1/ips/fraud-risk-score

Latency: <5s post-transaction · Rate limit: no limit

Returns

{
  "transaction_id": "string",
  "fraud_risk_score": "number",
  "fraud_risk_category": "string",
  "scoring_timestamp": "string",
  "score_reason": "string",
  "recommended_ips_action": "string",
  "overlay_message_template_id": "string"
}

Verify account

Verifies account existence and the holder's name against the centralised IPS directory (Confirmation of Payee). Supports pre-payment or post-complaint verification.

URL

GET /v1/ips/verify-account

Latency: <1s (p99) · Rate limit: 1M/min

Query

{
  "receiver_account_identifier": "string",
  "receiver_institution_code": "string",
  "receiver_account_holder_name_candidate": "string",
  "query_context": "string"
}

Get transaction status

Queries the real-time settlement status of a transaction within the IPS, to determine whether a reversal is still possible.

URL

GET /v1/ips/transaction-status

Latency: <500ms (p99) · Rate limit: unlimited

Returns

{
  "transaction_id": "string",
  "status": "string",
  "status_timestamp": "string",
  "clearing_timestamp": "string",
  "hours_until_irreversible": "number",
  "sender_received_credit": "boolean",
  "receiver_received_credit": "boolean"
}

Register participant

Onboards a financial institution to the Trust Layer: exchanges credentials, establishes mutual TLS certificates, and configures API access.

URL

POST /v1/ips/participant-register

Latency: <10s, typically during a setup meeting

Body

{
  "institution_code": "string",
  "institution_name": "string",
  "contact_email": "string",
  "certificate_signing_request": "string",
  "apis_to_enable": [],
  "data_retention_days": "number"
}

Report incident

Reports an operational incident affecting the Trust Layer – an outage or a fraud spike.

URL

POST /v1/ips/incident-report

Latency: <2s to acknowledge

Body

{
  "incident_type": "string",
  "severity": "string",
  "affected_institutions": [],
  "estimated_impact_percentage": "number",
  "description": "string",
  "estimated_resolution_time_minutes": "number"
}

About this reference

This page consolidates "Instrument Five: Instant Payment APIs" from Redress and fund recovery in digital public infrastructure (Proto and FNA, July 2026) with a real FNA Money Trails intake example. It sits alongside the equivalent generic spec set out in Citizen support and redress in digital public infrastructure (Proto, January 2026), which frames the same three systems – redress, recovery, and IPS integration – as a tiered pathway for development and philanthropy partners rather than as an API contract.

PreviousVoice API

NextLocal languages