MEMEH — API Reference

API reference

Contracts for Fintech ↔ MEMEH and MEMEH ↔ Bank Adapters. Bank-side status updates map to RTP pain.014.001.10 (GrpSts/TxSts + optional StsRsnInf).

v1 Signed requests Async lifecycle RTP aligned

Identifiers

request_id identifies the fintech-facing request.
instruction_id identifies bank-side instruction delivery.
rtp_id maps to RTP EndToEndId/UETR correlation.

Delivery model

Fintech requests are accepted synchronously, then progress asynchronously via RTP status updates.

Source of truth

OpenAPI defines canonical schemas, enums, and error codes for your deployment.

RTP status model (pain.014)

Bank/adapter updates drive lifecycle using TxSts/GrpSts. Use status reasons for negative outcomes.

TxSts / GrpSts	Business label	Meaning
RCVD	RECEIVED	RTP received/acknowledged; awaiting approval or rejection.
RJCT	REJECTED	RTP rejected; request will not proceed.
CANC	CANCELLED	RTP cancelled; request terminated.
ACSP	PAID	RTP paid; completion confirmed.

Status reason codes (Prtry)

LTXD

Insufficient funds / limit exceeded

ORXP

Original RTP expired

ORPD

Original RTP already paid

DCBP

Declined by payer

TXTO

Payer timeout / delivery failure

TNFN

Transaction ID not found

INVC

Invalid currency / amount

DTID

Duplicate transaction ID

RQNF

Request not found

ORCD

Original RTP already cancelled

ORDC

Original RTP already declined

ICRQ

Invalid cancel request

IDRQ

Invalid decline request

Notes

• For RJCT, include StsRsnInf/Rsn/Prtry and optional additional info.
• The spec describes AddtlInfo; examples show AddtlInf.
• Some sections show ASCP; business flows use ACSP.

Common headers

Applied to signed boundaries. Bank adapter contracts may use the same header set unless your deployment defines bank-specific names.

Header	Purpose
X-Client-ID	Client identity (issued during onboarding).
X-Signature	HMAC signature over canonical request.
X-Timestamp	ISO 8601 UTC timestamp (skew enforced).
X-Nonce	Unique per delivery (anti-replay).
X-Idempotency-Key	Stable per operation (safe retries).

Full security rules →

Fintech API

Endpoints used by fintech clients to initiate requests and query lifecycle state.

POST /api/v1/payment-requests

Create a payment request (Fintech → MEMEH).

Signed request. Returns request_id immediately; lifecycle progresses asynchronously via RTP status updates.

Caller: Fintech client

Request (JSON)

{
  "payer_alias": "2320001",
  "payee_alias": "2329991",
  "amount": "100.00",
  "currency": "SLE",
  "description": "Payment",
  "reference": "TXN-123"
}

Response (JSON)

{
  "request_id": "req_01J3Z9B3C4M9S8ZK2A6KQ9W0YQ",
  "reference": "TXN-123",
  "rtp_id": "ef73139a-2efb-4279-aa27-5d9b350121cb",
  "status": "accepted",
  "received_at": "2026-03-26T10:00:00Z"
}

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

Fetch current lifecycle state (Fintech → MEMEH).

Use when you need the latest state outside notifications. Status_code aligns to pain.014 TxSts.

Caller: Fintech client

Response (JSON)

{
  "request_id": "req_01J3Z9B3C4M9S8ZK2A6KQ9W0YQ",
  "reference": "TXN-123",
  "rtp_id": "ef73139a-2efb-4279-aa27-5d9b350121cb",
  "status": "RECEIVED",
  "status_code": "RCVD",
  "reason_code": null,
  "additional_info": null,
  "updated_at": "2026-03-26T10:00:12Z"
}

GET /api/v1/payment-requests?reference={reference}

Lookup by reference (Fintech → MEMEH).

Useful for reconciliation and support.

Caller: Fintech client

Response (JSON)

{
  "items": [
    {
      "request_id": "req_01J3Z9B3C4M9S8ZK2A6KQ9W0YQ",
      "reference": "TXN-123",
      "rtp_id": "ef73139a-2efb-4279-aa27-5d9b350121cb",
      "status": "PAID",
      "status_code": "ACSP",
      "reason_code": null
    }
  ]
}

Fintech integration guide →

Bank adapter API

Contracts between MEMEH and bank adapters: inbound instructions (MEMEH → bank) and RTP status updates (bank → MEMEH).

POST /api/v1/bank-instructions

Inbound instruction (MEMEH → Bank Adapter).

Adapter must validate signature + structure. Must be idempotent on instruction_id (or idempotency key). Carry rtp_id downstream for rail execution.

Caller: MEMEH platform

Request (JSON)

{
  "instruction_id": "ins_01J3Z9C9YB8FQH1T0WQ0P2J6QK",
  "request_id": "req_01J3Z9B3C4M9S8ZK2A6KQ9W0YQ",
  "rtp_id": "ef73139a-2efb-4279-aa27-5d9b350121cb",
  "payer_alias": "2320001",
  "payee_alias": "2329991",
  "amount": "100.00",
  "currency": "SLE",
  "description": "Payment",
  "reference": "TXN-123",
  "routing": {
    "payee_bank_code": "BANK001",
    "rail": "SLIPS"
  }
}

Response (JSON)

{
  "instruction_id": "ins_01J3Z9C9YB8FQH1T0WQ0P2J6QK",
  "accepted": true,
  "received_at": "2026-03-26T10:00:05Z"
}

POST /api/v1/bank-callbacks

RTP status update (Bank Adapter → MEMEH) — pain.014 mapping.

Post pain.014.001.10 status updates. Use TxSts/GrpSts as source of truth. For RJCT include StsRsnInf with Rsn/Prtry and AddtlInfo/AddtlInf.

Caller: Bank adapter

Request (JSON)

{
  "Document": {
    "@xmlns": "urn:iso:std:iso:20022:tech:xsd:pain.014.001.10",
    "CdtrPmtActvtnReqStsRpt": {
      "GrpHdr": {
        "MsgId": "419711302703779712806",
        "CreDtTm": "2022-07-07T03:42:00.232",
        "InitgPty": {
          "Id": { "OrgId": { "AnyBIC": "BIC" } }
        }
      },
      "OrgnlGrpInfAndSts": {
        "OrgnlMsgId": "AWINETAAXXX2024071501460161500000",
        "OrgnlMsgNmId": "pain.013.001.10",
        "OrgnlCreDtTm": "2022-07-07T03:41:49.232",
        "GrpSts": "RJCT"
      },
      "OrgnlPmtInfAndSts": {
        "OrgnlPmtInfId": "AWINETAAXXX2024071501460161500000",
        "TxInfAndSts": {
          "OrgnlInstrId": "AWINETAAXXX2024071501460164600000",
          "OrgnlEndToEndId": "ef73139a-2efb-4279-aa27-5d9b350121cb",
          "OrgnlUETR": "ef73139a-2efb-4279-aa27-5d9b350121cb",
          "TxSts": "RJCT",
          "StsRsnInf": {
            "Rsn": { "Prtry": "DCBP" },
            "AddtlInf": "Declined by payer"
          }
        }
      }
    }
  }
}

Response (JSON)

{
  "accepted": true,
  "recorded_at": "2026-03-26T10:01:11Z",
  "rtp_id": "ef73139a-2efb-4279-aa27-5d9b350121cb",
  "tx_sts": "RJCT"
}

GET /api/v1/bank-instructions/{instruction_id}

Instruction lookup (optional; Bank Adapter ↔ MEMEH).

Use only if your implementation supports re-fetch on callback mismatch.

Caller: Bank adapter

Response (JSON)

{
  "instruction_id": "ins_01J3Z9C9YB8FQH1T0WQ0P2J6QK",
  "request_id": "req_01J3Z9B3C4M9S8ZK2A6KQ9W0YQ",
  "status": "sent",
  "attempts": 1,
  "last_attempt_at": "2026-03-26T10:00:05Z"
}

Partner notification (forwarded by MEMEH)

MEMEH forwards a simplified status update to the fintech/merchant app derived from TxSts.

Notification (JSON)

{
  "rtp_id": "ef73139a-2efb-4279-aa27-5d9b350121cb",
  "status": "PAID",
  "status_code": "ACSP",
  "reason_code": null,
  "additional_info": null,
  "message": "Payment confirmed (paid). You may fulfil/deliver.",
  "event_time": "2026-03-28T05:42:41Z"
}

Bank integration guide →

Standard error model

Use consistent error codes for monitoring, triage, and partner support.

Error (JSON)

{
  "error": {
    "code": "INVALID_SIGNATURE",
    "message": "Signature mismatch for canonical request.",
    "trace_id": "trc_01J3Z9D8Y2Q4G8M1QWZ8N2K9R0"
  }
}

Common codes

MISSING_HEADER

Required headers missing.

INVALID_SIGNATURE

Signature mismatch or canonicalization issue.

REPLAY_DETECTED

Nonce already used or timestamp invalid.

IDEMPOTENCY_CONFLICT

Idempotency key reused with a different payload.

OpenAPI

OpenAPI is the canonical source for request/response schemas and enumerations.

Open API docs

Launch interactive documentation (if enabled in your deployment).

Open API docs

Tip: Use OpenAPI as the source of truth for schema and enums.