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

# Customers

> Learn how to create and manage customer accounts, handle KYC tiers and understand the difference between customer and merchant authentication.

Customers are the end-users who hold wallets through your merchant integration. When you create a customer account, TagPay provisions a wallet for them with a unique account number. Customers authenticate independently from your merchant account — they have their own login credentials and session tokens.

***

## Creating a customer account

Create a customer account by calling `POST /customer`. This is an unauthenticated endpoint, meaning your customers can self-register through your application's frontend, or you can call it server-side on their behalf.

```bash theme={null}
POST https://api.tagpay.ng/v1/customer
Content-Type: application/json
```

```json theme={null}
{
  "firstName": "Amaka",
  "lastName": "Ihejirika",
  "email": "amaka@example.com",
  "password": "securepassword",
  "phoneNumber": "08011223344",
  "address": "12 Marina Street, Lagos"
}
```

| Field         | Required | Description                 |
| ------------- | -------- | --------------------------- |
| `firstName`   | Yes      | Customer's first name       |
| `lastName`    | Yes      | Customer's last name        |
| `email`       | Yes      | Customer's email address    |
| `password`    | Yes      | Minimum 6 characters        |
| `phoneNumber` | Yes      | Customer's phone number     |
| `address`     | No       | Customer's physical address |

After account creation, the customer receives a **6-digit verification code** to confirm their email address before they can log in.

### Verifying the account

```bash theme={null}
POST https://api.tagpay.ng/v1/customer/verification
Content-Type: application/json
```

```json theme={null}
{
  "verificationCode": "482910"
}
```

***

## Customer authentication vs merchant authentication

TagPay uses two separate authentication systems:

|                    | Merchant                                                      | Customer                                            |
| ------------------ | ------------------------------------------------------------- | --------------------------------------------------- |
| **Who uses it**    | You (the integrating business)                                | Your end-users                                      |
| **Credentials**    | Email + password → access token (JWT) from `POST /auth/login` | Email + password → JWT from `POST /customer/login`  |
| **Login endpoint** | `POST /auth/login`                                            | `POST /customer/login`                              |
| **Scope**          | Merchant operations, wallet management, data access           | Wallet self-service, transfers, transaction history |

A customer's JWT token is passed in the `Authorization: Bearer` header for customer-authenticated requests.

### Customer login

```bash theme={null}
POST https://api.tagpay.ng/v1/customer/login
Content-Type: application/json
```

```json theme={null}
{
  "email": "amaka@example.com",
  "password": "securepassword"
}
```

<Note>
  Customers can be associated with multiple merchants. Use `POST /customer/merchants/switch` to switch a customer's active merchant context.
</Note>

***

## Customer tiers (KYC levels)

Every customer wallet is assigned a KYC tier that determines their transaction limits. There are three tiers:

| Tier     | KYC requirement         | Typical limits       |
| -------- | ----------------------- | -------------------- |
| `TIER_1` | Basic registration only | Lowest daily limit   |
| `TIER_2` | BVN or NIN verified     | Mid-tier daily limit |
| `TIER_3` | BVN and NIN verified    | Highest daily limit  |

The exact limit values are configured per merchant. Contact your account manager or check `GET /merchant/limits` for your tier limits.

### Upgrading a customer's tier

To upgrade a customer's tier, provide their BVN and/or NIN via the merchant-authenticated upgrade endpoint:

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

```json theme={null}
{
  "customerId": "cust_abc123",
  "tier": "TIER_2",
  "bvn": "12345678901"
}
```

You can also update a customer's BVN or NIN individually:

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

```json theme={null}
{
  "customerId": "cust_abc123",
  "bvn": "12345678901"
}
```

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

```json theme={null}
{
  "customerId": "cust_abc123",
  "nin": "98765432100"
}
```

***

## Customer profile management

### Retrieving a customer profile (merchant)

Look up a customer by their ID as the merchant:

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

Look up a customer by phone number:

```bash theme={null}
GET https://api.tagpay.ng/v1/customer/phone?phoneNumber=08011223344
Authorization: Bearer <your-access-token>
```

### Retrieving a profile (customer)

A logged-in customer can retrieve their own profile:

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

### Updating a customer profile

As the merchant:

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

```json theme={null}
{
  "firstName": "Amaka",
  "lastName": "Ihejirika",
  "address": "5 Victoria Island, Lagos",
  "metadata": { "internalRef": "USR-001" }
}
```

As the customer (with optional photo upload):

```bash theme={null}
PATCH https://api.tagpay.ng/v1/customer/profile
Authorization: Bearer <customer_token>
Content-Type: multipart/form-data
```

***

## Listing and exporting customers

Retrieve a paginated list of all customers under your merchant account:

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

Supported `searchBy` values: `PHONE_NUMBER`, `ACCOUNT_NUMBER`, `ACCOUNT_NAME`.

Export your full customer list as a CSV file:

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

***

## Related pages

<CardGroup cols={2}>
  <Card title="KYC verification guide" icon="id-card" href="/guides/kyc-verification">
    Verify customer identity with BVN and NIN
  </Card>

  <Card title="Wallets" icon="wallet" href="/concepts/wallets">
    Understand how customer wallets work
  </Card>

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

  <Card title="Transactions" icon="receipt" href="/concepts/transactions">
    View and download customer transaction history
  </Card>
</CardGroup>