---
title: "Initiate a tag-to-tag payment"
method: POST
path: "/v1/transactions"
tags: ["Transactions"]
---

# Initiate a tag-to-tag payment

`POST /v1/transactions`

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.**

## Headers

- `Idempotency-Key` string

## Request body

- InitiateTransactionRequest — Request body for initiating a cross-application tag-to-tag payment
  - `senderTag` string, required — The sender's tag handle (must belong to the calling application)
  - `receiverTag` string, required — The recipient's tag handle (can belong to any application)
  - `amount` number, required — Positive payment amount with up to 4 decimal places
  - `currency` string — ISO 4217 currency code (defaults to NGN)
  - `narration` string — Optional human-readable payment note
  - `callbackUrl` string — Optional HTTPS URL that IDaaS will POST the final transaction status to once accepted or rejected
  - `idempotencyKey` string — Client-supplied idempotency key (UUID v4 recommended). Duplicate calls within 24 hours return the original response.

## Response `201`

Transaction initiated successfully

## Other responses

- `400` — Validation error (invalid tags, zero amount, etc.)
- `401` — Missing or invalid bearer token
- `403` — Sender tag does not belong to the calling application
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/reflexpay/apis/idaas-identity-as-a-service-api.md) · [All operations](https://skmtc.net/reflexpay/apis/idaas-identity-as-a-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/reflexpay/idaas-identity-as-a-service-api/versions/db1f954badfb/schema)