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

# Manage Wallets

> Retrieve, close, re-enable, and configure customer wallets.

## Get customer wallet by customer ID

`GET /wallet/customer`

Retrieves the wallet and transaction limit details for a single customer using their `customerId`.

### Request

<ParamField header="Authorization" type="string" required>
  Bearer token.
</ParamField>

<ParamField query="customerId" type="string" required>
  The unique customer ID (UUID) returned when the wallet was created.
</ParamField>

### Response

<ResponseField name="status" type="boolean">
  `true` on success.
</ResponseField>

<ResponseField name="wallet" type="object">
  The customer wallet object, including tier-based transaction limits.

  <Expandable title="wallet properties">
    <ResponseField name="id" type="string">
      Wallet ID.
    </ResponseField>

    <ResponseField name="accountNumber" type="string">
      10-digit virtual account number.
    </ResponseField>

    <ResponseField name="accountName" type="string">
      Account holder name.
    </ResponseField>

    <ResponseField name="availableBalance" type="number">
      Spendable wallet balance in kobo.
    </ResponseField>

    <ResponseField name="status" type="string">
      `ACTIVE` or `FROZEN`.
    </ResponseField>

    <ResponseField name="tier" type="string">
      Customer tier: `TIER_1`, `TIER_2`, or `TIER_3`.
    </ResponseField>

    <ResponseField name="dailyLimit" type="number">
      Tier-specific daily transaction limit configured on your merchant account.
    </ResponseField>

    <ResponseField name="minBalance" type="number">
      Tier-specific minimum balance requirement.
    </ResponseField>

    <ResponseField name="isNINVerified" type="boolean">
      Whether NIN verification has been completed.
    </ResponseField>

    <ResponseField name="isBVNVerificationRequired" type="boolean">
      Whether BVN verification is still pending for this wallet.
    </ResponseField>
  </Expandable>
</ResponseField>

### Examples

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.tagpay.ng/v1/wallet/customer?customerId=cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321" \
    -H "Authorization: Bearer <token>"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.tagpay.ng/v1/wallet/customer?customerId=cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
    { headers: { Authorization: "Bearer <token>" } }
  );
  const data = await response.json();
  ```
</CodeGroup>

```json Response theme={null}
{
  "status": true,
  "wallet": {
    "id": "wlt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "accountNumber": "0123456789",
    "accountName": "Amaka Okonkwo",
    "availableBalance": 15000,
    "status": "ACTIVE",
    "tier": "TIER_1",
    "dailyLimit": 50000,
    "minBalance": 0,
    "isNINVerified": false,
    "isBVNVerificationRequired": false
  }
}
```

***

## Get customer wallet by account number

`GET /wallet/customer/account`

Retrieves a customer wallet using a 10-digit virtual account number. The account must belong to a customer under your merchant account.

### Request

<ParamField header="Authorization" type="string" required>
  Bearer token.
</ParamField>

<ParamField query="accountNumber" type="string" required>
  Exactly 10-digit virtual account number.
</ParamField>

### Examples

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

```json Response theme={null}
{
  "status": true,
  "wallet": {
    "id": "wlt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "accountNumber": "0123456789",
    "accountName": "Amaka Okonkwo",
    "availableBalance": 15000,
    "status": "ACTIVE",
    "tier": "TIER_1",
    "dailyLimit": 50000,
    "minBalance": 0,
    "merchantId": "merch_abc123"
  }
}
```

***

## Get wallet info by account number

`GET /wallet/info`

Returns basic wallet information for any account number that belongs to your merchant (customer or merchant wallet). Unlike `/wallet/customer/account`, this endpoint returns a minimal object without customer-level details.

### Request

<ParamField header="Authorization" type="string" required>
  Bearer token.
</ParamField>

<ParamField query="accountNumber" type="string" required>
  Exactly 10-digit account number.
</ParamField>

### Response

<ResponseField name="status" type="boolean">
  `true` on success.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="data properties">
    <ResponseField name="id" type="string">
      Wallet ID.
    </ResponseField>

    <ResponseField name="status" type="string">
      `ACTIVE` or `FROZEN`.
    </ResponseField>

    <ResponseField name="email" type="string">
      Email associated with the wallet.
    </ResponseField>

    <ResponseField name="accountName" type="string">
      Account holder name.
    </ResponseField>

    <ResponseField name="availableBalance" type="number">
      Available balance in kobo.
    </ResponseField>

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

### Examples

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

```json Response theme={null}
{
  "status": true,
  "data": {
    "id": "wlt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "ACTIVE",
    "email": "amaka.okonkwo@example.com",
    "accountName": "Amaka Okonkwo",
    "availableBalance": 15000,
    "createdAt": "2024-05-01T10:30:00.000Z"
  }
}
```

***

## Close a wallet

`POST /wallet/close`

Freezes a customer wallet, preventing any further transactions. Provide a `reason` for audit purposes. The wallet remains frozen until you explicitly re-enable it with `POST /wallet/enable`.

### Request

<ParamField header="Authorization" type="string" required>
  Bearer token.
</ParamField>

<ParamField body="customerId" type="string" required>
  The customer ID whose wallet you want to close.
</ParamField>

<ParamField body="reason" type="string" required>
  Reason for closing the wallet. Stored for audit and shown if someone attempts to enable the wallet.
</ParamField>

### Response

<ResponseField name="status" type="boolean">
  `true` on success.
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message: `"Customer wallet successfully frozen."`
</ResponseField>

### Examples

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

```json Response theme={null}
{
  "status": true,
  "message": "Customer wallet successfully frozen."
}
```

***

## Enable a wallet

`POST /wallet/enable`

Re-activates a previously frozen wallet. If the wallet was frozen due to BVN/NIN verification failure and BVN verification is still pending, the request is rejected until verification is resolved.

<Warning>
  If the wallet was frozen because of a failed identity check (`reason: "Invalid NIN/BVN"`, `"BVN Lookup failed"`, etc.), you must complete BVN verification before re-enabling. Contact TagPay support to trigger re-verification.
</Warning>

### Request

<ParamField header="Authorization" type="string" required>
  Bearer token.
</ParamField>

<ParamField body="customerId" type="string" required>
  The customer ID whose wallet you want to activate.
</ParamField>

### Response

<ResponseField name="status" type="boolean">
  `true` on success.
</ResponseField>

<ResponseField name="message" type="string">
  Confirmation message: `"Customer wallet successfully activated."`
</ResponseField>

### Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.tagpay.ng/v1/wallet/enable \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "customerId": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321"
    }'
  ```
</CodeGroup>

```json Response theme={null}
{
  "status": true,
  "message": "Customer wallet successfully activated."
}
```

***

## Set transaction PIN

`PUT /wallet/transaction-pin`

Sets or updates the 4-digit transaction PIN for a customer wallet. The PIN is required by certain debit flows.

### Request

<ParamField header="Authorization" type="string" required>
  Bearer token.
</ParamField>

<ParamField body="customerId" type="string" required>
  The customer ID whose PIN you are setting.
</ParamField>

<ParamField body="pin" type="string" required>
  The new 4-digit PIN. Minimum 4 characters.
</ParamField>

### Response

<ResponseField name="status" type="boolean">
  `true` on success.
</ResponseField>

<ResponseField name="message" type="string">
  `"Wallet transaction PIN successfully set."`
</ResponseField>

### Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X PUT https://api.tagpay.ng/v1/wallet/transaction-pin \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "customerId": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
      "pin": "1234"
    }'
  ```
</CodeGroup>

```json Response theme={null}
{
  "status": true,
  "message": "Wallet transaction PIN successfully set."
}
```

***

## Enable post-no-credit mode

`POST /wallet/enable-post-no-credit`

Enables post-no-credit (PNC) mode on a customer wallet. When PNC is active, any credits to that wallet — including from batch operations — are silently rejected with an error. Use this to block a wallet from receiving funds without fully freezing it.

<Note>
  This endpoint requires `MainMerchant` or `Admin` role. Standard API keys cannot call this endpoint.
</Note>

### Request

<ParamField header="Authorization" type="string" required>
  Bearer token with elevated permissions.
</ParamField>

<ParamField body="customerId" type="string" required>
  UUID of the customer. Must be a valid UUID format.
</ParamField>

<ParamField body="reason" type="string">
  Optional reason for enabling PNC mode.
</ParamField>

### Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.tagpay.ng/v1/wallet/enable-post-no-credit \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "customerId": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
      "reason": "Credit block per customer request"
    }'
  ```
</CodeGroup>

```json Response theme={null}
{
  "status": true,
  "message": "Post no credit successfully enabled."
}
```

***

## Disable post-no-credit mode

`POST /wallet/disable-post-no-credit`

Removes the post-no-credit restriction from a customer wallet, allowing the wallet to receive credits again.

<Note>
  Requires `MainMerchant` or `Admin` role.
</Note>

### Request

<ParamField header="Authorization" type="string" required>
  Bearer token with elevated permissions.
</ParamField>

<ParamField body="customerId" type="string" required>
  UUID of the customer.
</ParamField>

<ParamField body="reason" type="string">
  Optional reason for disabling PNC mode.
</ParamField>

### Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.tagpay.ng/v1/wallet/disable-post-no-credit \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "customerId": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321"
    }'
  ```
</CodeGroup>

```json Response theme={null}
{
  "status": true,
  "message": "Post no credit successfully disabled."
}
```

***

## Error responses

| HTTP Status | Description                                                                           |
| ----------- | ------------------------------------------------------------------------------------- |
| `400`       | Customer not found or does not belong to your merchant account                        |
| `400`       | Wallet frozen due to verification failure — BVN verification required before enabling |
| `400`       | Account number must be exactly 10 digits                                              |
| `401`       | Missing or invalid authentication token                                               |
| `403`       | Insufficient permissions for the requested operation                                  |