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

# Wallets

> Learn how TagPay wallets work, including wallet states, balances, transaction PIN, post-no-credit mode, and supported transfer types.

A wallet is a virtual account that holds funds for one of your customers. When you create a wallet for a customer, TagPay provisions a unique 10-digit account number for it. Your customers can receive funds, make payments, and transfer money — all through that account number.

Your merchant account also has its own wallet, which you use to hold settlement funds and fund operations in sandbox mode.

***

## Wallet account numbers

Every wallet is identified by a unique 10-digit account number. This number works like a conventional Nigerian bank account number — other parties can send funds directly to it via NIP (bank transfer). You can look up any wallet by its account number using `GET /wallet/info`.

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

***

## Wallet states

A wallet can be in one of three states:

| State       | Description                                                                                    |
| ----------- | ---------------------------------------------------------------------------------------------- |
| **Active**  | The wallet is open and can send and receive funds normally.                                    |
| **Closed**  | The wallet is permanently shut. No credits or debits are permitted.                            |
| **Blocked** | The wallet is temporarily suspended. Transactions are rejected until the wallet is re-enabled. |

### Closing a wallet

To permanently close a wallet, call `POST /wallet/close`. This action is irreversible.

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

```json theme={null}
{
  "customerId": "cust_abc123",
  "reason": "Customer requested account closure"
}
```

### Blocking and unblocking a wallet

Temporarily block a wallet with `POST /wallet/close` (passing a `reason`) or re-enable it with `POST /wallet/enable`.

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

```json theme={null}
{
  "customerId": "cust_abc123",
  "reason": "Compliance hold lifted"
}
```

***

## Creating a wallet

Create a wallet for a customer by calling `POST /wallet`. You must supply the customer's personal details, date of birth, phone number, and at least one KYC identifier (BVN or NIN).

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

```json theme={null}
{
  "firstName": "Ngozi",
  "lastName": "Eze",
  "phoneNumber": "08034567890",
  "dateOfBirth": "1990-05-15",
  "email": "ngozi@example.com",
  "bvn": "12345678901",
  "tier": "TIER_1",
  "currency": "NGN"
}
```

<Note>
  You must provide either a `bvn` or `nin` (or both). Wallets cannot be created without at least one KYC identifier.
</Note>

| Field         | Required    | Description                                                      |
| ------------- | ----------- | ---------------------------------------------------------------- |
| `firstName`   | Yes         | Customer's first name                                            |
| `lastName`    | Yes         | Customer's last name                                             |
| `phoneNumber` | Yes         | Customer's phone number                                          |
| `dateOfBirth` | Yes         | Date of birth in `YYYY-MM-DD` format                             |
| `email`       | No          | Customer's email address                                         |
| `bvn`         | Conditional | 11-digit Bank Verification Number                                |
| `nin`         | Conditional | 11-digit National Identification Number                          |
| `tier`        | No          | Wallet tier: `TIER_1`, `TIER_2`, or `TIER_3` (default: `TIER_1`) |
| `currency`    | No          | Currency code — only `NGN` is supported                          |
| `customerId`  | No          | Your own identifier for the customer                             |
| `metadata`    | No          | Arbitrary key-value data attached to the wallet                  |

### Bulk wallet creation

To create wallets for multiple customers in one request, upload a CSV file to `POST /wallet/bulk-create-customers`. The CSV must contain one row per customer with the same fields as the single-wallet endpoint.

***

## Wallet balances

A wallet has two balance figures:

| Balance                                 | Description                                                   |
| --------------------------------------- | ------------------------------------------------------------- |
| **Wallet balance** (`availableBalance`) | Funds available for the customer to spend right now.          |
| **Booked balance** (`bookedBalance`)    | Total funds in the wallet, including amounts not yet cleared. |

For day-to-day operations, use `availableBalance` to determine how much a customer can spend.

***

## Post-no-credit mode

Post-no-credit mode allows a wallet to be **debited but not credited**. Use this to enforce collection-only behaviour on specific wallets — for example, loan repayment accounts that should never receive inbound transfers.

Enable or disable post-no-credit mode per wallet. Only main merchants and admins can toggle this setting.

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

```json theme={null}
{
  "customerId": "cust_abc123",
  "reason": "Loan repayment wallet"
}
```

To restore normal credit behaviour:

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

```json theme={null}
{
  "customerId": "cust_abc123"
}
```

***

## Crediting and debiting wallets

Use the wallet endpoints to directly credit or debit a customer's wallet from your merchant account.

### Credit a wallet

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

```json theme={null}
{
  "customerId": "cust_abc123",
  "amount": 5000,
  "reference": "ref_20260101_001",
  "metadata": { "orderId": "ORD-987" }
}
```

### Debit a wallet

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

```json theme={null}
{
  "customerId": "cust_abc123",
  "amount": 2000,
  "reference": "ref_20260101_002",
  "metadata": { "orderId": "ORD-988" }
}
```

<Note>
  The `reference` field must be at least 10 characters. Use a unique value for every transaction to allow safe retries and prevent duplicates.
</Note>

### Batch operations

To credit or debit multiple wallets in a single request, use the batch endpoints:

| Endpoint                                           | Description                             |
| -------------------------------------------------- | --------------------------------------- |
| `POST /wallet/batch-credit-customer-wallet`        | Credit multiple wallets by `customerId` |
| `POST /wallet/batch-debit-customer-wallet`         | Debit multiple wallets by `customerId`  |
| `POST /wallet/batch-credit-customer-via-wallet-id` | Credit multiple wallets by wallet ID    |
| `POST /wallet/batch-debit-customer-via-wallet-id`  | Debit multiple wallets by wallet ID     |

Each batch request takes a `batchReference` (minimum 10 characters) and an array of `transactions`:

```json theme={null}
{
  "batchReference": "batch_payroll_20260401",
  "transactions": [
    { "customerId": "cust_001", "amount": 10000, "reference": "ref_001_20260401" },
    { "customerId": "cust_002", "amount": 15000, "reference": "ref_002_20260401" }
  ]
}
```

***

## Wallet-to-wallet vs bank transfers

TagPay supports two types of outbound transfers from a customer wallet:

| Transfer type       | Description                                                 | Endpoint                                                      |
| ------------------- | ----------------------------------------------------------- | ------------------------------------------------------------- |
| **Wallet transfer** | Instant transfer to another TagPay wallet by account number | Customer-initiated via `/customer/transfer/phone` or bulk CSV |
| **Bank transfer**   | NIP transfer to any Nigerian bank account                   | Customer-initiated via `POST /customer/transfer/bank`         |

Both transfer types require the customer to be authenticated and, where a PIN is set, to supply their transaction PIN.

***

## Listing wallets

Retrieve all wallets under your merchant account:

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

Filter by `accountNumber`, `phoneNumber`, or a search term. Up to 500 account numbers can be looked up in a single bulk request via `GET /wallet/customer/accounts`.

***

## Related pages

<CardGroup cols={2}>
  <Card title="Wallet management guide" icon="layer-group" href="/guides/wallet-management">
    Step-by-step guide to creating and managing wallets
  </Card>

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

  <Card title="Customers" icon="users" href="/concepts/customers">
    Understand customer accounts and KYC tiers
  </Card>

  <Card title="Transactions" icon="receipt" href="/concepts/transactions">
    Understand transaction states, types, and reversals
  </Card>
</CardGroup>