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

# Bulk Operations

> Create wallets and credit or debit multiple customer wallets in a single request.

## Bulk create wallets via CSV

`POST /wallet/bulk-create-customers`

Creates multiple customer wallets by uploading a CSV file. Processing happens asynchronously — the API returns immediately with a `202`-style acknowledgement while wallets are created in the background.

<Note>
  Wallet creation for each row follows the same BVN/NIN verification rules as the single wallet creation endpoint. Rows that fail validation (missing required fields, duplicate phone/BVN, insufficient merchant balance) are silently skipped.
</Note>

### Request

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

<ParamField header="Content-Type" type="string" required>
  `multipart/form-data`
</ParamField>

<ParamField body="customers" type="file" required>
  A CSV file with customer data. The file field name must be `customers`. Maximum chunk size processed at a time is 5,000 rows.
</ParamField>

### CSV format

The CSV file must include a header row. Column names are case-sensitive.

| Column          | Required | Description                                            |
| --------------- | -------- | ------------------------------------------------------ |
| `first_name`    | Yes      | Customer's first name                                  |
| `last_name`     | Yes      | Customer's last name                                   |
| `phone_number`  | Yes      | Customer phone number                                  |
| `date_of_birth` | Yes      | Date of birth (`YYYY-MM-DD`)                           |
| `bvn`           | Yes      | 11-digit BVN (required for wallet creation)            |
| `nin`           | No       | 11-digit NIN (required for TIER\_2/TIER\_3)            |
| `email`         | No       | Email address                                          |
| `address`       | No       | Physical address                                       |
| `tier`          | No       | `TIER_1`, `TIER_2`, or `TIER_3` (defaults to `TIER_1`) |

```csv Example CSV theme={null}
first_name,last_name,phone_number,date_of_birth,bvn,nin,email,tier
Amaka,Okonkwo,08031234567,1990-05-14,12345678901,,amaka@example.com,TIER_1
Chidi,Eze,08029876543,1988-11-22,98765432109,11122233344,chidi@example.com,TIER_2
```

### Response

<ResponseField name="status" type="boolean">
  `true` — the file was accepted and background processing has started.
</ResponseField>

<ResponseField name="message" type="string">
  `"Wallet processing is in progress. Please check back soon"`
</ResponseField>

### Examples

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

```json Response (201 Created) theme={null}
{
  "status": true,
  "message": "Wallet processing is in progress. Please check back soon"
}
```

***

## Batch credit customer wallets

`POST /wallet/batch-credit-customer-wallet`

Credits multiple customer wallets in a single request using customer IDs. The merchant wallet is debited the total of all amounts plus applicable fees. Transactions that cannot be processed (insufficient balance, post-no-credit enabled, duplicate reference) are returned in the `rejected` array while valid ones proceed.

### Request

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

<ParamField body="transactions" type="array" required>
  Array of transaction objects. Each item must have `customerId` and `amount`. Entries with `amount <= 1` or missing `customerId` are filtered out automatically.

  <Expandable title="Transaction object">
    <ParamField body="customerId" type="string" required>
      UUID of the customer to credit.
    </ParamField>

    <ParamField body="amount" type="number" required>
      Amount in kobo. Must be greater than 1.
    </ParamField>

    <ParamField body="reference" type="string">
      Unique reference for this individual transaction. Minimum 10 characters. Auto-generated if omitted.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="batchReference" type="string">
  A reference for the entire batch. Minimum 10 characters. Auto-generated if omitted. Must be unique — duplicate batch references are rejected.
</ParamField>

### Response

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

<ResponseField name="message" type="string">
  `"Transaction successfully completed."` or a description of the result.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="data properties">
    <ResponseField name="batchReference" type="string">
      The batch reference for this operation.
    </ResponseField>

    <ResponseField name="accepted" type="array">
      Transactions that were processed successfully. Each object contains the original transaction fields plus `walletId`.
    </ResponseField>

    <ResponseField name="rejected" type="array">
      Transactions that could not be processed. Each object contains the original transaction fields plus a `reason` string.
    </ResponseField>
  </Expandable>
</ResponseField>

### Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.tagpay.ng/v1/wallet/batch-credit-customer-wallet \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "batchReference": "BATCH-CREDIT-20240501-001",
      "transactions": [
        {
          "customerId": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
          "amount": 500000,
          "reference": "TXN-CREDIT-001-20240501"
        },
        {
          "customerId": "cust_1a2b3c4d-e5f6-7890-abcd-ef0987654321",
          "amount": 250000,
          "reference": "TXN-CREDIT-002-20240501"
        }
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.tagpay.ng/v1/wallet/batch-credit-customer-wallet", {
    method: "POST",
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      batchReference: "BATCH-CREDIT-20240501-001",
      transactions: [
        {
          customerId: "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
          amount: 500000,
          reference: "TXN-CREDIT-001-20240501",
        },
        {
          customerId: "cust_1a2b3c4d-e5f6-7890-abcd-ef0987654321",
          amount: 250000,
          reference: "TXN-CREDIT-002-20240501",
        },
      ],
    }),
  });

  const data = await response.json();
  ```
</CodeGroup>

```json Response theme={null}
{
  "status": true,
  "message": "Transaction successfully completed.",
  "data": {
    "batchReference": "BATCH-CREDIT-20240501-001",
    "accepted": [
      {
        "customerId": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
        "amount": 500000,
        "reference": "TXN-CREDIT-001-20240501",
        "walletId": "wlt_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    ],
    "rejected": [
      {
        "customerId": "cust_1a2b3c4d-e5f6-7890-abcd-ef0987654321",
        "amount": 250000,
        "reference": "TXN-CREDIT-002-20240501",
        "reason": "Post no credit is enabled. Kindly contact support for help"
      }
    ]
  }
}
```

***

## Batch debit customer wallets

`POST /wallet/batch-debit-customer-wallet`

Debits multiple customer wallets using customer IDs. Requires `canDebitCustomer` to be enabled on your merchant account.

### Request

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

<ParamField body="transactions" type="array" required>
  Array of transaction objects. Each item requires `customerId` and `amount`.

  <Expandable title="Transaction object">
    <ParamField body="customerId" type="string" required>
      UUID of the customer to debit.
    </ParamField>

    <ParamField body="amount" type="number" required>
      Amount in kobo. Must be greater than 1.
    </ParamField>

    <ParamField body="reference" type="string">
      Unique reference for this transaction. Minimum 10 characters.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="batchReference" type="string">
  Reference for the batch. Minimum 10 characters.
</ParamField>

### Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.tagpay.ng/v1/wallet/batch-debit-customer-wallet \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "batchReference": "BATCH-DEBIT-20240501-001",
      "transactions": [
        {
          "customerId": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
          "amount": 100000,
          "reference": "TXN-DEBIT-001-20240501"
        }
      ]
    }'
  ```
</CodeGroup>

```json Response theme={null}
{
  "status": true,
  "message": "Transaction successfully completed.",
  "data": {
    "batchReference": "BATCH-DEBIT-20240501-001",
    "accepted": [
      {
        "customerId": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
        "amount": 100000,
        "reference": "TXN-DEBIT-001-20240501"
      }
    ],
    "rejected": []
  }
}
```

***

## Batch credit by wallet ID

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

Credits multiple customer wallets using wallet IDs (UUIDs) instead of customer IDs. Use this when you have wallet IDs stored directly from previous API responses.

### Request

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

<ParamField body="transactions" type="array" required>
  <Expandable title="Transaction object">
    <ParamField body="walletId" type="string" required>
      UUID of the wallet to credit.
    </ParamField>

    <ParamField body="amount" type="number" required>
      Amount in kobo. Must be greater than 1.
    </ParamField>

    <ParamField body="reference" type="string">
      Unique transaction reference. Minimum 10 characters.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="batchReference" type="string">
  Reference for the batch. Minimum 10 characters.
</ParamField>

### Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.tagpay.ng/v1/wallet/batch-credit-customer-via-wallet-id \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "batchReference": "BATCH-WID-CREDIT-001",
      "transactions": [
        {
          "walletId": "wlt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "amount": 300000,
          "reference": "TXN-WID-CREDIT-001-001"
        }
      ]
    }'
  ```
</CodeGroup>

***

## Batch debit by wallet ID

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

Debits multiple customer wallets using wallet IDs.

### Request

Same structure as [batch credit by wallet ID](#batch-credit-by-wallet-id), but debits the listed wallets.

<ParamField body="transactions" type="array" required>
  <Expandable title="Transaction object">
    <ParamField body="walletId" type="string" required>
      UUID of the wallet to debit.
    </ParamField>

    <ParamField body="amount" type="number" required>
      Amount in kobo. Must be greater than 1.
    </ParamField>

    <ParamField body="reference" type="string">
      Unique transaction reference. Minimum 10 characters.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="batchReference" type="string">
  Reference for the batch. Minimum 10 characters.
</ParamField>

### Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.tagpay.ng/v1/wallet/batch-debit-customer-via-wallet-id \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "batchReference": "BATCH-WID-DEBIT-001",
      "transactions": [
        {
          "walletId": "wlt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "amount": 150000,
          "reference": "TXN-WID-DEBIT-001-001"
        }
      ]
    }'
  ```
</CodeGroup>

***

## List bulk credit records

`GET /wallet/bulk-credit-customer-records`

Returns a list of all batch credit records created under your merchant account, including accepted and rejected transaction details.

### Request

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

### Examples

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

***

## Check batch credit status

`GET /wallet/bulk-credit-customer-status`

Returns the current processing status of a bulk credit batch. Use this to poll background jobs initiated by the upload-based bulk credit flow.

### Request

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

### Examples

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

***

## Cancel a batch

`DELETE /wallet/bulk-credit-customer/:batchId`

Cancels a pending bulk credit batch before it is processed. Once a batch has started processing, it cannot be cancelled.

### Request

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

<ParamField path="batchId" type="string" required>
  The ID of the batch to cancel.
</ParamField>

### Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE "https://api.tagpay.ng/v1/wallet/bulk-credit-customer/batch_abc123def456" \
    -H "Authorization: Bearer <token>"
  ```
</CodeGroup>

```json Response theme={null}
{
  "status": true,
  "message": "Batch successfully cancelled."
}
```

***

## Error responses

| HTTP Status | Description                                  |
| ----------- | -------------------------------------------- |
| `400`       | Batch reference already exists               |
| `400`       | Insufficient merchant wallet balance         |
| `400`       | Daily transaction limit exceeded             |
| `400`       | No valid transactions to process             |
| `400`       | CSV file missing or failed to upload         |
| `401`       | Missing or invalid authentication token      |
| `403`       | Customer debit not enabled for this merchant |

```json 400 Batch Reference Exists theme={null}
{
  "status": false,
  "message": "Reference already exist."
}
```