MEMEH RTPO — Fintech Developer Guide

Fintech developer integration model

This is the primary API guide for fintech developers and other approved request-submitter developers. A business, biller, government service, payment platform, or fintech integrates once with MEMEH RTPO. It resolves payer and payee aliases, submits the selected financial-address options, and observes status. It does not construct ISO 20022 messages, connect directly to IPS, or decide the final payment outcome.

1. Resolve

Send the payer and payee aliases with the amount, currency, and reference.

2. Select

Show the payer the eligible masked account or wallet choices returned by the Central Addressing Service.

3. Request

Submit the resolution ID and selected payer/payee option IDs with the payment intent.

4. Observe

Poll current status and event history until a terminal lifecycle result is recorded.

Executable starter kit

Run the complete journey in Postman

Import the collection and environment, select MEMEH RTPO Local, then run the folders in numeric order. The scripts capture the resolution, selected address IDs, and request ID automatically. Replace the local credential and test identities before using another environment.

Postman collection Local environment

The local environment contains development-only sample values. Never export or share an environment containing production credentials.

Server-side reference implementations

Starter code and RTP simulator

Use a framework sample to connect your checkout backend to MEMEH RTPO, or run the Next.js simulator to inspect the complete customer journey. Every sample follows the same resolve, select, request, status, and event sequence shown below.

Complete starter suite SHA-256 checksums

Next.js RTP simulator

A runnable GovPay checkout simulation with payer and payee resolution, masked financial-address selection, request creation, and lifecycle polling. Its route handlers keep the MEMEH RTPO API key on the server.

Download simulator

Framework	Runtime	Package
Express.js	Node.js 20+	Download sample
Go Fiber	Go 1.23+	Download sample
Laravel	PHP 8.2+ / Laravel 11+	Download sample
ASP.NET Core	.NET 8+	Download sample
FastAPI	Python 3.11+	Download sample
Java Servlet	Java 21 / Jakarta Servlet 6	Download sample

These packages are reference starters, not independently versioned client libraries. Review validation, authentication, observability, resilience, and deployment controls against your organization’s standards before production use. Never expose the MEMEH RTPO API key in browser code.

Flow 1: resolve payer and payee

Send POST /api/v1/aliases/resolve. MEMEH RTPO asks the Central Addressing Service to resolve both aliases and returns browser-safe, masked choices. The full financial addresses remain inside trusted services.

Request body

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

HTTP 200 response

{
  "verified": true,
  "resolution_id": "cas-resolution-10452",
  "source": "CAS_V2",
  "expires_at": "2026-08-05T10:35: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"
      }
    ]
  }
}

Payer choice

Display each active payer.finaddresses option so the payer can choose their bank, mobile money operator, fintech, account, or wallet.

Payee choice

Use the merchant-approved or default active payee.finaddresses option. Do not allow the payer to redirect the destination.

Flow 2: create the Request-to-Pay

Send POST /api/v1/payment-requests with the resolution ID and selected payer/payee option IDs from Flow 1, Authorization: Bearer <MEMEH_CORE_API_KEY> and Content-Type: application/json.

Request body

{
  "idempotency_key": "invoice-10452-attempt-1",
  "resolution_id": "cas-resolution-10452",
  "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": "INVOICE-10452",
  "description": "Government service payment"
}

HTTP 202 response

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

MEMEH RTPO performs a fresh trusted resolution and rejects stale or changed selections. HTTP 202 and DISPATCHED mean the participant adapter accepted the handoff. They do not mean that the payer approved or that payment completed.

Status and event history

GET /api/v1/payment-requests/{request_id} returns the latest known state.

Status response

{
  "request_id": "2a838d95-38cc-45cf-98fc-635fb1157ce1",
  "status": "ACSP",
  "amount": "250.00",
  "currency": "SLE",
  "reference": "INVOICE-10452",
  "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:08Z"
}

Polling rule

Use the request_id returned by creation. The current API does not expose a list-by-reference endpoint.

Event history

GET /api/v1/payment-requests/{request_id}/events returns the append-only lifecycle trail for support and reconciliation.

Completion rule

ACSP means accepted for processing. Only ACSC is successful payment completion. A later confirmed return is RETURNED; RJCT, CANC, and FAILED remain terminal negative outcomes.

Integration responsibilities

Request submitter	MEMEH RTPO Platform	Participating provider
Authenticate, present active payer choices, protect the payee destination, submit opaque selection IDs, generate unique references and idempotency keys, store request IDs, poll safely, and fulfil only after ACSC.	Resolve both aliases through the Central Addressing Service, verify selected options, enforce merchant/payee and route rules, dispatch the canonical instruction, correlate events, and expose status history.	Own customer approval, RTP initiation, ISO 20022 and IPS interaction, linked payment processing, authoritative lifecycle outcomes, and timely status publication.

Error handling

HTTP	Code	Client action
400	INVALID_JSON / INVALID_ID	Correct the JSON or UUID; do not retry unchanged.
401	UNAUTHORIZED	Supply the environment-specific bearer API key.
404	ALIAS_NOT_FOUND / NOT_FOUND	Verify the alias or request identifier.
409	IDEMPOTENCY_CONFLICT	Do not reuse one idempotency key for a different logical request.
413 / 415 / 429	REQUEST_TOO_LARGE / UNSUPPORTED_MEDIA_TYPE / RATE_LIMITED	Fix request size or content type, or back off.
422	VALIDATION_FAILED / NO_ROUTE / MERCHANT_PAYEE_MISMATCH	Correct business data or contact enablement support.
503	CAS_UNAVAILABLE / ADAPTER_UNAVAILABLE	Retry with the same idempotency key after backoff.

Enablement path

1. Apply.
Describe the organization, use case, volumes, technical owner, payee relationship, and requested environment.
2. Receive controlled access.
After approval, accept the signed invitation, change the temporary password, and retrieve the sandbox material assigned to the account.
3. Integrate.
Implement the required resolve-select-request sequence, bearer authentication, idempotent retry, status polling, safe logging, and reconciliation.
4. Certify.
Run UAT across happy, negative, duplicate, timeout, unavailable-dependency, and lifecycle-order scenarios before production approval.