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

# Wallet Management

> Create and manage customer wallets — fund them, debit them, and control their lifecycle.

Wallets are the core of TagPay's customer financial accounts. Each wallet is tied to a customer identity and holds funds in NGN. This guide walks you through the complete wallet lifecycle: creation, funding, debiting, and closure.

## Prerequisites

All wallet endpoints require a valid merchant Bearer token in the `Authorization` header:

```text theme={null}
Authorization: Bearer <your-token>
```

***

## Create a wallet

Use `POST /wallet` to create a wallet for a new customer. You must supply at least one government-issued identifier — either a BVN or NIN.

<Steps>
  <Step title="Gather customer details">
    Collect the customer's name, phone number, date of birth, and at least one of BVN or NIN. The `customerId` field is optional — if omitted, TagPay generates one.
  </Step>

  <Step title="Submit the creation request">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.tagpay.ng/v1/wallet \
        -H "Authorization: Bearer <your-token>" \
        -H "Content-Type: application/json" \
        -d '{
          "firstName": "Amara",
          "lastName": "Okafor",
          "phoneNumber": "08012345678",
          "dateOfBirth": "1990-06-15",
          "bvn": "12345678901",
          "email": "amara.okafor@example.com",
          "currency": "NGN",
          "tier": "TIER_1"
        }'
      ```

      ```json Response theme={null}
      {
        "success": true,
        "data": {
          "customerId": "cus_abc123",
          "accountNumber": "1234567890",
          "firstName": "Amara",
          "lastName": "Okafor",
          "balance": 0,
          "currency": "NGN",
          "tier": "TIER_1",
          "status": "active"
        }
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

### Request fields

| Field         | Type   | Required | Description                                           |
| ------------- | ------ | -------- | ----------------------------------------------------- |
| `firstName`   | string | Yes      | Customer's first name                                 |
| `lastName`    | string | Yes      | Customer's last name                                  |
| `phoneNumber` | string | Yes      | Nigerian phone number                                 |
| `dateOfBirth` | string | Yes      | ISO date string (YYYY-MM-DD)                          |
| `bvn`         | string | Yes\*    | 11-digit BVN (\*required if NIN not provided)         |
| `nin`         | string | Yes\*    | 11-digit NIN (\*required if BVN not provided)         |
| `email`       | string | No       | Customer email address                                |
| `customerId`  | string | No       | Your internal customer ID                             |
| `currency`    | string | No       | Defaults to `NGN`                                     |
| `tier`        | string | No       | `TIER_1`, `TIER_2`, or `TIER_3`. Defaults to `TIER_1` |
| `address`     | string | No       | Customer's address                                    |
| `metadata`    | object | No       | Arbitrary key-value pairs                             |

<Warning>
  You must provide either `bvn` or `nin` (or both). Requests without at least one identifier will be rejected.
</Warning>

***

## Bulk wallet creation via CSV

To create wallets for many customers at once, upload a CSV file to `POST /wallet/bulk-create-customers`. The file must be sent as `multipart/form-data` with the field name `customers`.

```bash cURL theme={null}
curl -X POST https://api.tagpay.ng/v1/wallet/bulk-create-customers \
  -H "Authorization: Bearer <your-token>" \
  -F "customers=@/path/to/customers.csv"
```

Each CSV row should contain the same fields as the single-wallet creation request. TagPay processes the file asynchronously and creates wallets in the background.

<Tip>
  The maximum recommended batch size is 500 customers per CSV upload. Split larger datasets across multiple files.
</Tip>

***

## Check wallet balance

Use `GET /wallet/balance` to fetch your merchant settlement balance, or `GET /wallet/customer` to retrieve a specific customer's wallet.

<CodeGroup>
  ```bash Merchant balance theme={null}
  curl -X GET https://api.tagpay.ng/v1/wallet/balance \
    -H "Authorization: Bearer <your-token>"
  ```

  ```bash Customer wallet theme={null}
  curl -X GET "https://api.tagpay.ng/v1/wallet/customer?customerId=cus_abc123" \
    -H "Authorization: Bearer <your-token>"
  ```

  ```bash By account number theme={null}
  curl -X GET "https://api.tagpay.ng/v1/wallet/customer/account?accountNumber=1234567890" \
    -H "Authorization: Bearer <your-token>"
  ```
</CodeGroup>

To look up a wallet by account number and get detailed info:

```bash cURL theme={null}
curl -X GET "https://api.tagpay.ng/v1/wallet/info?accountNumber=1234567890" \
  -H "Authorization: Bearer <your-token>"
```

***

## Credit a wallet

Use `POST /wallet/credit` to add funds to a customer's wallet from your merchant settlement balance.

```bash cURL theme={null}
curl -X POST https://api.tagpay.ng/v1/wallet/credit \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_abc123",
    "amount": 5000,
    "reference": "TXN-2026-001-CREDIT",
    "metadata": {
      "description": "Salary disbursement"
    }
  }'
```

| Field        | Type   | Required | Description                                      |
| ------------ | ------ | -------- | ------------------------------------------------ |
| `customerId` | string | Yes      | The customer to credit                           |
| `amount`     | number | Yes      | Amount in kobo (smallest unit)                   |
| `reference`  | string | No       | Your unique transaction reference (min 10 chars) |
| `metadata`   | object | No       | Arbitrary key-value pairs                        |

***

## Debit a wallet

Use `POST /wallet/debit` to withdraw funds from a customer's wallet back to your merchant settlement balance.

```bash cURL theme={null}
curl -X POST https://api.tagpay.ng/v1/wallet/debit \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_abc123",
    "amount": 1000,
    "reference": "TXN-2026-001-DEBIT"
  }'
```

The request body accepts the same fields as the credit endpoint.

***

## Batch credit and debit

To credit or debit multiple wallets in a single API call, use the batch endpoints.

### Batch credit (by customer ID)

```bash cURL theme={null}
curl -X POST https://api.tagpay.ng/v1/wallet/batch-credit-customer-wallet \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "batchReference": "BATCH-2026-04-001",
    "transactions": [
      { "customerId": "cus_abc123", "amount": 5000, "reference": "REF-001-CREDIT" },
      { "customerId": "cus_def456", "amount": 3000, "reference": "REF-002-CREDIT" }
    ]
  }'
```

### Batch debit (by customer ID)

```bash cURL theme={null}
curl -X POST https://api.tagpay.ng/v1/wallet/batch-debit-customer-wallet \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "batchReference": "BATCH-2026-04-002",
    "transactions": [
      { "customerId": "cus_abc123", "amount": 1000, "reference": "REF-001-DEBIT" }
    ]
  }'
```

You can also target wallets by wallet ID instead of customer ID:

* `POST /wallet/batch-credit-customer-via-wallet-id`
* `POST /wallet/batch-debit-customer-via-wallet-id`

The body structure is the same, but uses `walletId` in each transaction object instead of `customerId`.

### Batch reference requirements

* `batchReference` must be at least 10 characters
* Each `reference` within `transactions` must also be at least 10 characters

<Note>
  To reverse a batch transaction, call `POST /wallet/reverse-batch-transaction` with the `batchReference` and a `description` explaining the reason for reversal.
</Note>

***

## Enable or disable a wallet

You can temporarily disable a customer's wallet (for example, when suspicious activity is detected) and re-enable it when ready.

<CodeGroup>
  ```bash Disable wallet theme={null}
  curl -X POST https://api.tagpay.ng/v1/wallet/close \
    -H "Authorization: Bearer <your-token>" \
    -H "Content-Type: application/json" \
    -d '{
      "customerId": "cus_abc123",
      "reason": "Suspicious activity detected"
    }'
  ```

  ```bash Enable wallet theme={null}
  curl -X POST https://api.tagpay.ng/v1/wallet/enable \
    -H "Authorization: Bearer <your-token>" \
    -H "Content-Type: application/json" \
    -d '{
      "customerId": "cus_abc123",
      "reason": "Account review complete"
    }'
  ```
</CodeGroup>

| Field        | Type   | Required | Description                                  |
| ------------ | ------ | -------- | -------------------------------------------- |
| `customerId` | string | Yes      | The customer whose wallet to close or enable |
| `reason`     | string | Yes      | The reason for the action                    |

<Warning>
  Disabling a wallet prevents all credits and debits on that wallet. Customers with disabled wallets cannot send or receive funds.
</Warning>

***

## List all wallets

Retrieve a paginated list of all customer wallets under your merchant account:

```bash cURL theme={null}
curl -X GET "https://api.tagpay.ng/v1/wallet?page=1&perPage=20&search=amara" \
  -H "Authorization: Bearer <your-token>"
```

| Query param     | Type   | Description                       |
| --------------- | ------ | --------------------------------- |
| `page`          | number | Page number (default: 1)          |
| `perPage`       | number | Results per page (default: 20)    |
| `search`        | string | Search by name or identifier      |
| `accountNumber` | string | Filter by 10-digit account number |
| `phoneNumber`   | string | Filter by phone number            |