Sign in

v3

latestOpenAPI 3.0.1Proprietaryraw.githubusercontent.com2026-04-174552109.9 KB
Transactions

Initiate a tag-to-tag payment

Creates a new cross-application payment from a tag owned by the calling application to any tag on any application. The transaction starts in AWAITING_ACCEPTANCE state.

The receiving application is notified via webhook and must call POST /v1/transactions/{reference}/accept or .../reject.

Idempotency: Supply a unique Idempotency-Key header; duplicate calls within 24 hours return the original response without creating a new transaction.

Rate limited to 60 requests per minute per application.

post/v1/transactions

Headers

Idempotency-Keystring

Optional idempotency key (UUID or any unique string, max 128 chars). Duplicate calls with the same key within 24 hours return the original response.

Request body

senderTagstring required

The sender's tag handle (must belong to the calling application)

receiverTagstring required

The recipient's tag handle (can belong to any application)

amountnumber required

Positive payment amount with up to 4 decimal places

currencystring

ISO 4217 currency code (defaults to NGN)

narrationstring

Optional human-readable payment note

callbackUrlstring

Optional HTTPS URL that IDaaS will POST the final transaction status to once accepted or rejected

idempotencyKeystring

Client-supplied idempotency key (UUID v4 recommended). Duplicate calls within 24 hours return the original response.

Example request

{
  "senderTag": "@alice",
  "receiverTag": "@bob",
  "amount": 1500,
  "currency": "NGN",
  "narration": "School fees payment",
  "callbackUrl": "https://my-app.example.com/webhooks/transactions",
  "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000"
}

Response

Transaction initiated successfully