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

# Transactions

> Understand transaction types, states, batch operations, references, limits, reversals, and how to download transaction history in TagPay.

Every movement of funds in TagPay is recorded as a transaction. Whether you credit a customer wallet, process a bank transfer, or run a batch payout, each operation produces a transaction record with a unique reference, a type, and a state that reflects its progress.

***

## Transaction types

| Type                  | Description                                                                  |
| --------------------- | ---------------------------------------------------------------------------- |
| **Credit** (`CREDIT`) | Funds added to a wallet — e.g. an inbound bank transfer or a merchant credit |
| **Debit** (`DEBIT`)   | Funds removed from a wallet — e.g. a bank transfer or a merchant debit       |
| **Bank transfer**     | A debit that sends funds to an external Nigerian bank account via NIP        |
| **Wallet transfer**   | A transfer from one TagPay wallet to another, settled instantly              |

When querying transaction lists, filter by type using `type=CREDIT`, `type=DEBIT`, or `type=ALL` (default).

***

## Transaction states

A transaction moves through states as it is processed:

| State                   | Meaning                                                        |
| ----------------------- | -------------------------------------------------------------- |
| **Pending**             | The transaction has been created but not yet processed.        |
| **Approved**            | The transaction has been authorised and queued for settlement. |
| **Completed / Success** | Funds have settled and the transaction is final.               |
| **Failed**              | The transaction could not be processed. No funds moved.        |
| **Reversed**            | The transaction was successfully reversed after completion.    |

<Note>
  Not all transaction types go through every state. Wallet-to-wallet transfers typically settle immediately and skip the pending/approved flow.
</Note>

### Pending transactions

Transactions that require explicit approval queue up as pending. Retrieve them with:

```bash theme={null}
GET https://api.tagpay.ng/v1/transaction/pending
Authorization: Bearer <your-access-token>
```

### Approving a pending transaction

```bash theme={null}
POST https://api.tagpay.ng/v1/transaction/approve
Authorization: Bearer <your-access-token>
Content-Type: application/json
```

```json theme={null}
{
  "transactionId": "txn_abc123"
}
```

### Removing a pending transaction

Discard a pending transaction that should not be processed:

```bash theme={null}
DELETE https://api.tagpay.ng/v1/transaction/:transactionId
Authorization: Bearer <your-access-token>
```

***

## Transaction references

Every transaction is identified by a **reference** — a unique string that you provide or that TagPay generates. References let you:

* Look up a specific transaction by its reference
* Safely retry a request without double-processing (idempotency)
* Correlate TagPay records with your own internal order or payment IDs

<Warning>
  Always supply your own reference when creating transactions. References must be at least 10 characters. Using the same reference for two different transactions will cause the second request to be rejected.
</Warning>

### Looking up a transaction by reference

```bash theme={null}
GET https://api.tagpay.ng/v1/transaction/info?reference=ref_20260401_001
Authorization: Bearer <your-access-token>
```

Or via the merchant-scoped endpoint:

```bash theme={null}
GET https://api.tagpay.ng/v1/merchant/transaction/:reference
Authorization: Bearer <your-access-token>
```

***

## Batch transactions

Batch operations group multiple credits or debits into a single API call, each identified by a shared `batchReference`. This is efficient for payroll runs, bulk disbursements, and mass collections.

### Creating a batch credit

```bash theme={null}
POST https://api.tagpay.ng/v1/wallet/batch-credit-customer-wallet
Authorization: Bearer <your-access-token>
Content-Type: application/json
```

```json theme={null}
{
  "batchReference": "batch_payroll_20260401",
  "transactions": [
    {
      "customerId": "cust_001",
      "amount": 50000,
      "reference": "ref_payroll_001_20260401"
    },
    {
      "customerId": "cust_002",
      "amount": 75000,
      "reference": "ref_payroll_002_20260401"
    }
  ]
}
```

| Field                       | Required | Description                                          |
| --------------------------- | -------- | ---------------------------------------------------- |
| `batchReference`            | Yes      | Unique identifier for the batch (min. 10 characters) |
| `transactions[].customerId` | Yes      | ID of the customer wallet to credit                  |
| `transactions[].amount`     | Yes      | Amount in kobo (must be greater than 0)              |
| `transactions[].reference`  | No       | Per-transaction reference (min. 10 characters)       |

### Retrieving batch status

```bash theme={null}
GET https://api.tagpay.ng/v1/transaction/batch
Authorization: Bearer <your-access-token>
```

Retrieve the details of a specific batch by its reference:

```bash theme={null}
GET https://api.tagpay.ng/v1/transaction/batch/:reference
Authorization: Bearer <your-access-token>
```

### Uploading batches via CSV

For very large disbursements, upload a CSV file directly:

```bash theme={null}
POST https://api.tagpay.ng/v1/wallet/upload-bulk-credit-customer
Authorization: Bearer <your-access-token>
Content-Type: multipart/form-data
```

After upload, process the batch:

```bash theme={null}
POST https://api.tagpay.ng/v1/wallet/process-bulk-credit-customer
Authorization: Bearer <your-access-token>
Content-Type: application/json
```

```json theme={null}
{
  "batchReference": "batch_payroll_20260401"
}
```

Check the status of an uploaded batch:

```bash theme={null}
GET https://api.tagpay.ng/v1/wallet/bulk-credit-customer-status
Authorization: Bearer <your-access-token>
```

***

## Transaction limits

Transaction limits control the maximum amount a customer can transact in a given period. Limits are applied at the **customer tier level** (`TIER_1`, `TIER_2`, `TIER_3`) and are configured per merchant.

If a transaction exceeds a customer's tier limit, it is rejected at the point of creation. To allow higher volumes, upgrade the customer's KYC tier. See [Customers](/concepts/customers) for details on tier upgrades.

Retrieve your merchant's current limit settings:

```bash theme={null}
GET https://api.tagpay.ng/v1/merchant/limits
Authorization: Bearer <your-access-token>
```

Check how much of each limit has been consumed today:

```bash theme={null}
GET https://api.tagpay.ng/v1/merchant/limits/usage
Authorization: Bearer <your-access-token>
```

***

## Reversals

A reversal returns funds to the originating wallet after a transaction has completed. Reversals are appropriate when a transaction was processed in error or a customer dispute requires a refund.

<Warning>
  Not all transaction types are reversible. Reversals must be authorised by an administrator or a merchant with reversal permissions enabled.
</Warning>

### Reversing a batch transaction

```bash theme={null}
POST https://api.tagpay.ng/v1/wallet/reverse-batch-transaction
Authorization: Bearer <your-access-token>
Content-Type: application/json
```

```json theme={null}
{
  "batchReference": "batch_payroll_20260401",
  "description": "Incorrect payment amounts — reversing full batch"
}
```

### Viewing your reversal history

```bash theme={null}
GET https://api.tagpay.ng/v1/merchant/reversals
Authorization: Bearer <your-access-token>
```

Retrieve a specific reversal record:

```bash theme={null}
GET https://api.tagpay.ng/v1/merchant/reversals/:id
Authorization: Bearer <your-access-token>
```

Review reversal statistics (totals by status):

```bash theme={null}
GET https://api.tagpay.ng/v1/merchant/reversals/stats
Authorization: Bearer <your-access-token>
```

### Configuring reversal settings

Control which reversal scenarios are permitted for your merchant:

```bash theme={null}
GET https://api.tagpay.ng/v1/merchant/reversal-config
PUT  https://api.tagpay.ng/v1/merchant/reversal-config
Authorization: Bearer <your-access-token>
```

***

## Downloading transaction history

### Merchant transactions (CSV)

Export all transactions for your merchant account as a CSV file:

```bash theme={null}
GET https://api.tagpay.ng/v1/transaction/download/merchant
Authorization: Bearer <your-access-token>
```

Apply filters using query parameters: `type`, `category`, `startDate`, `endDate`, `status`.

### Customer transactions (CSV)

Export the full transaction history for a specific customer:

```bash theme={null}
GET https://api.tagpay.ng/v1/transaction/download/customer?customerId=cust_abc123
Authorization: Bearer <your-access-token>
```

### Batch transactions (CSV)

Export your batch transaction list:

```bash theme={null}
GET https://api.tagpay.ng/v1/transaction/batch/export
Authorization: Bearer <your-access-token>
```

### Pending transactions (CSV)

Export the current pending transaction queue:

```bash theme={null}
GET https://api.tagpay.ng/v1/transaction/pending/export
Authorization: Bearer <your-access-token>
```

***

## Viewing customer transactions

As a merchant, retrieve the transaction history for any customer under your account:

```bash theme={null}
GET https://api.tagpay.ng/v1/transaction/customer?customerId=cust_abc123&type=ALL&page=1&perPage=20
Authorization: Bearer <your-access-token>
```

Customers can also view their own transactions when authenticated:

```bash theme={null}
GET https://api.tagpay.ng/v1/customer/transactions
Authorization: Bearer <customer_token>
```

***

## Related pages

<CardGroup cols={2}>
  <Card title="Wallets" icon="wallet" href="/concepts/wallets">
    Credit, debit, and manage customer wallet balances
  </Card>

  <Card title="Funds transfer" icon="arrow-right-arrow-left" href="/guides/funds-transfer">
    Send funds to banks and between wallets
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/webhooks">
    Receive real-time notifications for transaction events
  </Card>

  <Card title="API reference" icon="code" href="/api/transactions/list">
    Full endpoint reference for transaction operations
  </Card>
</CardGroup>