MEMEH RTPO — API Reference

Implemented API reference

This page describes the public MEMEH RTPO HTTP surface for fintechs, payment facilitators, billers, and government services. Client endpoints use Authorization: Bearer <MEMEH_CORE_API_KEY>. JSON write requests require Content-Type: application/json.

The current API has no list-by-reference endpoint, HMAC headers, nonce header, or client OAuth flow. Integrators must use the returned request UUID for status and event lookup.

MEMEH RTPO API

Method	Path	Authentication	Purpose
GET	/health	None	Core liveness check.
POST	/api/v1/aliases/resolve	Bearer client key	Resolve payer/payee aliases and return masked participant/address choices.
POST	/api/v1/payment-requests	Bearer client key	Verify the selected opaque IDs, route, build, and dispatch a payment request.
GET	/api/v1/payment-requests/{id}	Bearer client key	Read the latest state of one request UUID.
GET	/api/v1/payment-requests/{id}/events	Bearer client key	Read the append-only event history for one request UUID.

Payer and payee resolution

POST /api/v1/aliases/resolve

{
  "payer_alias": "+23276123456",
  "payee_alias": "govpay@sandbox.sl",
  "amount": "250.00",
  "currency": "SLE",
  "reference": "TAX-2026-0001"
}

Browser-safe participant choices

HTTP 200

{
  "verified": true,
  "resolution_id": "cas-resolution-0001",
  "source": "CAS_V2",
  "expires_at": "2026-07-30T09:05:00Z",
  "payer": {
    "alias": "+23276123456",
    "alias_type": "MSISDN",
    "status": "ACTIVE",
    "finaddresses": [{
      "id": "fa_payer_bank",
      "label": "Example Bank",
      "masked": "Account ending 0319",
      "default": true,
      "servicer_id": "BANK1SLFR",
      "servicer_id_type": "BICFI",
      "status": "ACTIVE"
    }]
  },
  "payee": {
    "alias": "govpay@sandbox.sl",
    "alias_type": "EMAIL",
    "status": "ACTIVE",
    "finaddresses": [{
      "id": "fa_payee_govpay",
      "label": "GovPay Account",
      "masked": "Account ending 0999",
      "default": true,
      "servicer_id": "PAYEESLFR",
      "servicer_id_type": "BICFI",
      "status": "ACTIVE"
    }]
  }
}

Display active payer choices and retain only their opaque IDs. The merchant-approved payee option remains protected. Payment creation performs a fresh Central Addressing Service resolution and rejects stale or changed selections.

Create payment request

POST /api/v1/payment-requests

{
  "idempotency_key": "govpay-20260730-0001",
  "resolution_id": "cas-resolution-0001",
  "payer_finaddress_id": "fa_payer_bank",
  "payee_finaddress_id": "fa_payee_govpay",
  "payer_alias": "+23276123456",
  "payee_alias": "govpay@sandbox.sl",
  "merchant_id": "GOVPAY-SL",
  "amount": "250.00",
  "currency": "SLE",
  "reference": "TAX-2026-0001",
  "description": "Government service payment"
}

HTTP 202

{
  "request_id": "2a838d95-38cc-45cf-98fc-635fb1157ce1",
  "status": "DISPATCHED",
  "normalized_aliases": {
    "payer": "+23276123456",
    "payee": "govpay@sandbox.sl"
  },
  "inferred_types": {
    "payer": "MSISDN",
    "payee": "EMAIL"
  },
  "dispatch": {
    "status": "DISPATCHED",
    "http_status": 202
  }
}

Idempotency

Same key and same logical payload returns the original logical request. Same key with a different payload returns HTTP 409.

Dispatch semantics

DISPATCHED means the selected adapter accepted handoff. It is not a completed payment state.

Status and lifecycle events

Current status

GET /api/v1/payment-requests/{id}

{
  "request_id": "2a838d95-38cc-45cf-98fc-635fb1157ce1",
  "status": "ACSC",
  "amount": "250.00",
  "currency": "SLE",
  "reference": "TAX-2026-0001",
  "resolution_id": "cas-res-672",
  "participant": "PAYEE-BANK",
  "dispatch_http_status": 202,
  "dispatch_message": "accepted",
  "created_at": "2026-07-30T09:00:00Z",
  "updated_at": "2026-07-30T09:00:19Z"
}

Event history

GET /api/v1/payment-requests/{id}/events

{
  "events": [
    {
      "id": "evt-record-1",
      "request_id": "2a838d95-38cc-45cf-98fc-635fb1157ce1",
      "instruction_id": "inst-8a10",
      "event_type": "PARTICIPANT_STATUS",
      "status": "ACSC",
      "message": "RTP lifecycle status updated",
      "created_at": "2026-07-30T09:00:19Z"
    }
  ]
}

State	Meaning	Terminal
RECEIVED / ROUTABLE / DISPATCHED	Internal orchestration and handoff progression.	No
PDNG / RCVD	Provider processing or payer action remains outstanding.	No
ACSP	Accepted for processing; do not fulfil yet.	No
ACSC	Completed; fulfilment may proceed. A later confirmed return may supersede this state.	No*
RETURNED	A previously completed payment was confirmed returned.	Yes
RJCT / CANC / FAILED	Terminal negative outcome.	Yes

Error envelope

Core returns stable machine-readable codes without exposing internal exception details.

Example

{
  "error": {
    "code": "IDEMPOTENCY_CONFLICT",
    "message": "Idempotency key was already used with a different request"
  }
}

OpenAPI contract

Download the current Core API contract for client generation, contract testing, and review.

Download OpenAPI YAML Download Postman Collection Download Local Environment Open API explorer