> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tagpay.ng/llms.txt
> Use this file to discover all available pages before exploring further.

# Transaction Details

> Retrieve, approve, reverse, and remove individual transactions.

## Get transaction info

Retrieve a single transaction by its ID or reference. You must provide at least one of `transactionId` or `reference`.

```
GET https://api.tagpay.ng/v1/transaction/info
```

### Query parameters

<ParamField query="transactionId" type="string">
  The UUID of the transaction. Takes precedence over `reference` when both are provided.
</ParamField>

<ParamField query="reference" type="string">
  The unique reference string assigned to the transaction.
</ParamField>

<Note>
  You must supply either `transactionId` or `reference`. Requests that omit both will receive a `400` error.
</Note>

### Response

<ResponseField name="status" type="boolean">
  `true` when the request succeeded.
</ResponseField>

<ResponseField name="transaction" type="object">
  The matching transaction record.

  <Expandable title="Transaction object">
    <ResponseField name="id" type="string">
      Unique transaction identifier (UUID).
    </ResponseField>

    <ResponseField name="reference" type="string">
      Transaction reference string.
    </ResponseField>

    <ResponseField name="type" type="string">
      `CREDIT` or `DEBIT`.
    </ResponseField>

    <ResponseField name="status" type="string">
      `success`, `pending`, or `failed`.
    </ResponseField>

    <ResponseField name="amount" type="number">
      Transaction amount in kobo.
    </ResponseField>

    <ResponseField name="fee" type="number">
      Processing fee in kobo.
    </ResponseField>

    <ResponseField name="vat" type="number">
      VAT in kobo.
    </ResponseField>

    <ResponseField name="total" type="number">
      Total deducted amount including fee and VAT.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Currency code, e.g. `NGN`.
    </ResponseField>

    <ResponseField name="category" type="string">
      Transaction category.
    </ResponseField>

    <ResponseField name="description" type="string">
      Transaction description.
    </ResponseField>

    <ResponseField name="source" type="string">
      Source account or wallet.
    </ResponseField>

    <ResponseField name="destination" type="string">
      Destination account or wallet.
    </ResponseField>

    <ResponseField name="balance_before" type="number">
      Wallet balance before the transaction.
    </ResponseField>

    <ResponseField name="balance_after" type="number">
      Wallet balance after the transaction.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Arbitrary metadata attached to the transaction.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 creation timestamp.
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 last-updated timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL (by reference) theme={null}
  curl --request GET \
    --url "https://api.tagpay.ng/v1/transaction/info?reference=TXN-20240401-001" \
    --header "Authorization: Bearer <token>"
  ```

  ```bash cURL (by ID) theme={null}
  curl --request GET \
    --url "https://api.tagpay.ng/v1/transaction/info?transactionId=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
    --header "Authorization: Bearer <token>"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "status": true,
    "transaction": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "reference": "TXN-20240401-001",
      "type": "DEBIT",
      "status": "success",
      "amount": 500000,
      "fee": 1000,
      "vat": 75,
      "total": 501075,
      "currency": "NGN",
      "category": "BANK_TRANSFER",
      "description": "Transfer to Access Bank",
      "source": "wallet_001",
      "destination": "0123456789",
      "balance_before": 1000000,
      "balance_after": 498925,
      "metadata": {},
      "createdAt": "2024-04-01T10:30:00.000Z",
      "updatedAt": "2024-04-01T10:30:05.000Z"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "status": false,
    "message": "Record not found"
  }
  ```
</ResponseExample>

***

## Get batch transaction details

Retrieve the details of a single batch transaction by its reference.

```
GET https://api.tagpay.ng/v1/transaction/batch/:reference
```

### Path parameters

<ParamField path="reference" type="string" required>
  The reference of the batch transaction.
</ParamField>

### Response

<ResponseField name="status" type="boolean">
  `true` when the request succeeded.
</ResponseField>

<ResponseField name="data" type="object">
  The batch transaction record. Internal fields `mode` and `merchantId` are excluded.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url "https://api.tagpay.ng/v1/transaction/batch/BATCH-20240401-001" \
    --header "Authorization: Bearer <token>"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "status": true,
    "data": {
      "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "reference": "BATCH-20240401-001",
      "type": "DEBIT",
      "status": "success",
      "totalAmount": 5000000,
      "totalCount": 10,
      "category": "BATCH_BANK_TRANSFER",
      "createdAt": "2024-04-01T14:00:00.000Z",
      "updatedAt": "2024-04-01T14:05:30.000Z"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "status": false,
    "message": "Transaction cannot be found!"
  }
  ```
</ResponseExample>

***

## Approve a pending transaction

Approve a pending transaction that is at or above your user's configured approval limit. You cannot approve a transaction you initiated unless you are the merchant account owner.

```
POST https://api.tagpay.ng/v1/transaction/approve
```

### Request body

<ParamField body="transactionId" type="string" required>
  The UUID of the pending transaction to approve.
</ParamField>

### Response

<ResponseField name="status" type="boolean">
  `true` when the approval succeeded.
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message: `"Transaction successfully approved."`.
</ResponseField>

<Warning>
  This action is irreversible once the underlying transfer has been processed. Ensure you have verified the transaction details before approving.
</Warning>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url "https://api.tagpay.ng/v1/transaction/approve" \
    --header "Authorization: Bearer <token>" \
    --header "Content-Type: application/json" \
    --data '{
      "transactionId": "c3d4e5f6-a7b8-9012-cdef-123456789012"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "status": true,
    "message": "Transaction successfully approved."
  }
  ```

  ```json 400 theme={null}
  {
    "status": false,
    "message": "You are not authorized to approve this transaction."
  }
  ```

  ```json 400 theme={null}
  {
    "status": false,
    "message": "Transaction has already been processed."
  }
  ```

  ```json 400 theme={null}
  {
    "status": false,
    "message": "You cannot approve transaction you initiated."
  }
  ```
</ResponseExample>

***

## Reverse a transaction

Reverse a completed transaction and credit the originating wallet. This endpoint is restricted to admin users only.

```
POST https://api.tagpay.ng/v1/transaction/reverse
```

<Warning>
  This endpoint requires admin-level access. Merchant tokens will receive a `403 Forbidden` response. Only transactions in a `pending` state can be reversed.
</Warning>

### Request body

<ParamField body="reference" type="string">
  The reference string of the transaction to reverse. Provide either this or `transactionId`.
</ParamField>

<ParamField body="transactionId" type="string">
  The UUID of the transaction to reverse. Takes precedence when both fields are present.
</ParamField>

### Response

<ResponseField name="status" type="boolean">
  `true` when the reversal succeeded.
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message: `"Transaction successfully reversed"`.
</ResponseField>

The reversal creates a corresponding `CREDIT` transaction with reference prefixed `r-` (e.g. `r-TXN-20240401-001`) and marks the original transaction as `failed`.

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url "https://api.tagpay.ng/v1/transaction/reverse" \
    --header "Authorization: Bearer <admin-token>" \
    --header "Content-Type: application/json" \
    --data '{
      "reference": "TXN-20240401-001"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "status": true,
    "message": "Transaction successfully reversed"
  }
  ```

  ```json 400 theme={null}
  {
    "status": false,
    "message": "You can only reverse transaction in pending state"
  }
  ```

  ```json 400 theme={null}
  {
    "status": false,
    "message": "Transaction not found"
  }
  ```
</ResponseExample>

***

## Remove a pending transaction

Cancel and remove a pending transaction. The transaction status is set to `CANCELLED`.

```
DELETE https://api.tagpay.ng/v1/transaction/:transactionId
```

### Path parameters

<ParamField path="transactionId" type="string" required>
  The UUID of the pending transaction to cancel.
</ParamField>

### Response

<ResponseField name="status" type="boolean">
  `true` when the cancellation succeeded.
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message: `"Transaction successfully declined."`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url "https://api.tagpay.ng/v1/transaction/c3d4e5f6-a7b8-9012-cdef-123456789012" \
    --header "Authorization: Bearer <token>"
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "status": true,
    "message": "Transaction successfully declined."
  }
  ```

  ```json 400 theme={null}
  {
    "status": false,
    "message": "There is a problem retrieving transactions"
  }
  ```
</ResponseExample>