> For the complete documentation index, see [llms.txt](https://documentation.proto.cx/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.proto.cx/docs/developers/apis/instant-payment-api.md).

# Instant payment API

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.

{% hint style="info" %}
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.
{% endhint %}

{% hint style="info" %}
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.
{% endhint %}

***

## 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.

{% code title="URL" overflow="wrap" %}

```
POST /v1/cases/intake
```

{% endcode %}

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

{% code title="Body" overflow="wrap" %}

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

{% endcode %}

{% code title="Returns" overflow="wrap" %}

```json
{
  "case_id": "string"
}
```

{% endcode %}

***

### Get case status

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

{% code title="URL" overflow="wrap" %}

```
GET /v1/cases/{case_id}
```

{% endcode %}

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

{% code title="Returns" overflow="wrap" %}

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

{% endcode %}

***

### Route case

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

{% code title="URL" overflow="wrap" %}

```
POST /v1/cases/{case_id}/route
```

{% endcode %}

**Latency:** <1s

{% code title="Body" overflow="wrap" %}

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

{% endcode %}

***

### Initiate online dispute resolution

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

{% code title="URL" overflow="wrap" %}

```
POST /v1/cases/{case_id}/odr
```

{% endcode %}

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

{% code title="Body" overflow="wrap" %}

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

{% endcode %}

***

### Classify case

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

{% code title="URL" overflow="wrap" %}

```
POST /v1/cases/{case_id}/classify
```

{% endcode %}

**Latency:** <5s

{% code title="Body" overflow="wrap" %}

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

{% endcode %}

***

### Notify citizen

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

{% code title="URL" overflow="wrap" %}

```
POST /v1/cases/{case_id}/notify
```

{% endcode %}

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

{% code title="Body" overflow="wrap" %}

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

{% endcode %}

***

## 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](#about-this-reference)).

### 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.

{% code title="URL" overflow="wrap" %}

```
POST /v1/recovery/trace
```

{% endcode %}

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

{% code title="Body" overflow="wrap" %}

```json
{
  "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"
}
```

{% endcode %}

{% code title="Returns" overflow="wrap" %}

```json
{
  "trace_id": "string"
}
```

{% endcode %}

{% hint style="info" %}
**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:

```json
{
  "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.
{% endhint %}

***

### Get trace results

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

{% code title="URL" overflow="wrap" %}

```
GET /v1/recovery/trace/{trace_id}
```

{% endcode %}

**Latency:** <500ms · **Rate limit:** unlimited

{% code title="Returns" overflow="wrap" %}

```json
{
  "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"
    }
  ]
}
```

{% endcode %}

***

### Initiate freeze

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

{% code title="URL" overflow="wrap" %}

```
POST /v1/recovery/freeze
```

{% endcode %}

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

{% code title="Body" overflow="wrap" %}

```json
{
  "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"
}
```

{% endcode %}

***

### Get freeze status

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

{% code title="URL" overflow="wrap" %}

```
GET /v1/recovery/freeze/{freeze_id}
```

{% endcode %}

**Latency:** <500ms · **Rate limit:** unlimited

{% code title="Returns" overflow="wrap" %}

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

{% endcode %}

***

### Extend freeze

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

{% code title="URL" overflow="wrap" %}

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

{% endcode %}

**Latency:** <5s

{% code title="Body" overflow="wrap" %}

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

{% endcode %}

***

### Release freeze

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

{% code title="URL" overflow="wrap" %}

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

{% endcode %}

**Latency:** <10s to issue the release order

{% code title="Body" overflow="wrap" %}

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

{% endcode %}

***

### Return funds

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

{% code title="URL" overflow="wrap" %}

```
POST /v1/recovery/fund-return
```

{% endcode %}

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

{% code title="Body" overflow="wrap" %}

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

{% endcode %}

***

### Get mule score

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

{% code title="URL" overflow="wrap" %}

```
POST /v1/recovery/mule-score
```

{% endcode %}

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

{% code title="Body" overflow="wrap" %}

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

{% endcode %}

***

### Generate legal document

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

{% code title="URL" overflow="wrap" %}

```
POST /v1/recovery/legal-document
```

{% endcode %}

**Latency:** <3s

{% code title="Body" overflow="wrap" %}

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

{% endcode %}

***

## 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.

{% code title="URL" overflow="wrap" %}

```
POST /v1/ips/transaction-metadata
```

{% endcode %}

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

{% code title="Body" overflow="wrap" %}

```json
{
  "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"
}
```

{% endcode %}

***

### 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.

{% code title="URL" overflow="wrap" %}

```
POST /v1/ips/fraud-risk-score
```

{% endcode %}

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

{% code title="Returns" overflow="wrap" %}

```json
{
  "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"
}
```

{% endcode %}

***

### 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.

{% code title="URL" overflow="wrap" %}

```
GET /v1/ips/verify-account
```

{% endcode %}

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

{% code title="Query" overflow="wrap" %}

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

{% endcode %}

***

### Get transaction status

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

{% code title="URL" overflow="wrap" %}

```
GET /v1/ips/transaction-status
```

{% endcode %}

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

{% code title="Returns" overflow="wrap" %}

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

{% endcode %}

***

### Register participant

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

{% code title="URL" overflow="wrap" %}

```
POST /v1/ips/participant-register
```

{% endcode %}

**Latency:** <10s, typically during a setup meeting

{% code title="Body" overflow="wrap" %}

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

{% endcode %}

***

### Report incident

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

{% code title="URL" overflow="wrap" %}

```
POST /v1/ips/incident-report
```

{% endcode %}

**Latency:** <2s to acknowledge

{% code title="Body" overflow="wrap" %}

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

{% endcode %}

***

## 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.