---
title: "Reject a pending transaction"
method: POST
path: "/v1/transactions/{reference}/reject"
tags: ["Transactions"]
---

# Reject a pending transaction

`POST /v1/transactions/{reference}/reject`

## Request

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

The **receiving application** calls this to reject an `AWAITING_ACCEPTANCE` transaction.

No ledger movement occurs on rejection – nothing was debited at initiation.
Transaction status moves to `REJECTED`.
Sender is notified via webhook callback URL with the rejection reason.

## Path parameters

- `reference` string, required

## Request body

- RejectTransactionRequest
  - `reason` string

## Response `200`

Transaction rejected

- 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

- `403`: Calling application is not the receiver
- `404`: Transaction not found
- `409`: Transaction is not in AWAITING_ACCEPTANCE state

## Changes

- **2026-04-17** `db1f954badfb`: 4 info
  - added the optional property `errorCode` to the response with the `200` status
  - added the optional property `errorCode` to the response with the `403` status
  - added the optional property `errorCode` to the response with the `404` status
  - added the optional property `errorCode` to the response with the `409` status

[Operation history](https://skmtc.dev/reflexpay/apis/idaas-identity-as-a-service-api/changes/v1/transactions/:reference/reject/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)