MEMEH — Fintech Integration

Fintech integration

Implement the MEMEH request boundary correctly: sign every request, protect against replay, and handle retries safely with idempotency.

Signed requests Safe retries Callback lifecycle

Request model

Minimal payload required to initiate a payment journey. Field rules and optional attributes are documented in API Reference.

JSON

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

Field expectations

• reference must be unique per business operation.
• amount should be a string decimal with 2dp.
• payer/payee_alias must be resolvable by the alias service.

Operational tip

Log the request reference, idempotency key, and any correlation IDs to trace callbacks end-to-end.

Required headers

Headers are enforced at the boundary. Missing or invalid values will be rejected before orchestration.

Header	Purpose	Example	Reject if missing
X-Client-ID	Identifies the calling client (issued during onboarding).	TENKIPAY	Yes
X-Signature	HMAC signature proving integrity + authorization.	replace-with-real-signature	Yes
X-Timestamp	Time-bounded validity (anti-replay).	2026-03-21T10:00:00Z	Yes
X-Nonce	Unique per request (anti-replay).	uat-nonce-001	Yes
X-Idempotency-Key	Safe retries without duplicate execution.	uat-idempotency-001	Yes

Copy/paste list

Headers

X-Client-ID
X-Signature
X-Timestamp
X-Nonce
X-Idempotency-Key

Retry rules (non-negotiable)

• Retry with the same idempotency key.
• Generate a new nonce for each retry.
• Update the timestamp for retries and keep within allowed skew.

Responsibilities

What fintech integrators must implement to meet security and operational expectations.

Security & correctness

• Sign every request correctly.
• Use unique nonces and valid timestamps.
• Use idempotency keys for safe retries.
• Validate payloads client-side before sending.

Observability

• Log outbound requests and responses internally.
• Persist reference + idempotency key for traceability.
• Correlate callbacks to original requests.
• Alert on signature and replay failures.

Common errors

Typical failure modes during integration and what they usually mean.

INVALID_SIGNATURE

Canonicalization or shared secret mismatch. Confirm signing input rules and secret configuration.

IDEMPOTENCY_CONFLICT

Same idempotency key reused with a different payload. Keep the key stable per operation.

UNKNOWN_ALIAS

Alias resolution failed. Confirm alias format, registration, and environment (sandbox vs prod).

Onboarding path

The operational sequence required before production enablement.

1

Access approval

The organization is reviewed in the enablement portal and assigned the approved environment and scope.

2

Credential issuance

Client credentials are issued and scoped to allowed capabilities.

3

Sandbox integration

Implement signing, idempotency, and callbacks; validate end-to-end flows.

4

UAT execution

Run readiness testing with agreed scenarios and operational checks.

5

Production enablement

Access is enabled after approvals and final readiness gates.