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

# Initiate a tag-to-tag payment

`POST /v1/transactions`

## Request

- Base URL: `https://idaas.yourflexpay.com/api`
- URL: `https://idaas.yourflexpay.com/api/v1/transactions`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/reflexpay/apis/idaas-identity-as-a-service-api/docs/v1/transactions/post.ts> (a function with typed inputs; its response is checked against the schema)

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

- ApiResponseTransactionResponse
  - `success` boolean
  - `message` string
  - `errorCode` string
  - `data` TransactionResponse: Full details of a cross-application tag-to-tag payment transaction
    - `id` string, uuid: Unique transaction ID
    - `reference` string: Human-readable unique reference for the transaction
    - `senderTag` string: Sender tag handle
    - `senderAppName` string: Name of the sender's application
    - `senderAppId` string, uuid: UUID of the sender's application
    - `receiverTag` string: Receiver tag handle
    - `receiverAppName` string: Name of the receiver's application
    - `receiverAppId` string, uuid: UUID of the receiver's application
    - `amount` number: Payment amount (DECIMAL 19,4)
    - `currency` string: ISO 4217 currency code
    - `status` 'AWAITING_ACCEPTANCE' | 'COMPLETED' | 'REJECTED' | 'EXPIRED': Transaction lifecycle status
    - `narration` string: Human-readable payment note
    - `expiresAt` string, date-time: ISO-8601 timestamp after which the transaction auto-expires if not accepted
    - `acceptedAt` string, date-time: ISO-8601 timestamp when the transaction was accepted (null until COMPLETED)
    - `rejectedAt` string, date-time: ISO-8601 timestamp when the transaction was rejected (null unless REJECTED)
    - `rejectionReason` string: Rejection reason supplied by the receiving application (null unless REJECTED)
    - `createdAt` string, date-time: ISO-8601 creation timestamp
    - `updatedAt` string, date-time: ISO-8601 last-update timestamp
    - `webhooks` TransactionWebhookResponse[]: Outbound webhook delivery records (RECEIVER and/or SENDER). Included in single-transaction GET; omitted in list responses.
      - `id` string, uuid: Unique webhook record ID
      - `transactionId` string, uuid: UUID of the parent transaction
      - `transactionReference` string: Transaction reference
      - `applicationId` string, uuid: UUID of the target application (receiver or sender)
      - `applicationName` string: Name of the target application
      - `direction` 'RECEIVER' | 'SENDER': Which side this webhook notifies
      - `targetUrl` string: HTTP endpoint that was (or will be) called
      - `eventType` 'TRANSACTION_INITIATED' | 'TRANSACTION_COMPLETED' | 'TRANSACTION_REJECTED' | 'TRANSACTION_EXPIRED': Event name included in the webhook body
      - `status` 'PENDING' | 'DELIVERED' | 'FAILED': Current delivery status
      - `attempts` integer: Total number of HTTP delivery attempts made (max 3)
      - `lastError` string: HTTP status code or exception message from the most recent attempt
      - `lastAttemptAt` string, date-time: ISO-8601 timestamp of the most recent delivery attempt
      - `deliveredAt` string, date-time: ISO-8601 timestamp when delivery was confirmed (HTTP 2xx). Null until delivered.
      - `createdAt` string, date-time: ISO-8601 creation timestamp (when the webhook was first queued)
      - `updatedAt` string, date-time: ISO-8601 last-update timestamp
  - `errors` string[]
  - `timestamp` string, date-time

## 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

## Changes

- **2026-04-17** `db1f954badfb`: 5 info
  - added the optional property `errorCode` to the response with the `201` status
  - added the optional property `errorCode` to the response with the `400` status
  - added the optional property `errorCode` to the response with the `401` status
  - added the optional property `errorCode` to the response with the `403` status
  - …1 more

[Operation history](https://skmtc.dev/reflexpay/apis/idaas-identity-as-a-service-api/changes/v1/transactions/post.md)

---

[API](https://skmtc.dev/reflexpay/apis/idaas-identity-as-a-service-api.md) - [All operations](https://skmtc.dev/reflexpay/apis/idaas-identity-as-a-service-api/llms.txt) - [OpenAPI document](https://skmtc.dev/reflexpay/apis/idaas-identity-as-a-service-api/revisions/db1f954badfb?raw)