Bulk Operations

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.

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.

Request

string

required

Bearer token.

string

required

multipart/form-data

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.

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`)

Example CSV

first_name,last_name,phone_number,date_of_birth,bvn,nin,email,tier
Amaka,Okonkwo,08031234567,1990-05-14,12345678901,,[email protected],TIER_1
Chidi,Eze,08029876543,1988-11-22,98765432109,11122233344,[email protected],TIER_2

Response

boolean

true — the file was accepted and background processing has started.

string

"Wallet processing is in progress. Please check back soon"

Examples

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

Response (201 Created)

{
  "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

string

required

Bearer token.

array

required

Array of transaction objects. Each item must have customerId and amount. Entries with amount <= 1 or missing customerId are filtered out automatically.

Show Transaction object

string

required

UUID of the customer to credit.

number

required

Amount in kobo. Must be greater than 1.

string

Unique reference for this individual transaction. Minimum 10 characters. Auto-generated if omitted.

string

A reference for the entire batch. Minimum 10 characters. Auto-generated if omitted. Must be unique — duplicate batch references are rejected.

Response

boolean

true on success.

string

"Transaction successfully completed." or a description of the result.

object

Show data properties

string

The batch reference for this operation.

array

Transactions that were processed successfully. Each object contains the original transaction fields plus walletId.

array

Transactions that could not be processed. Each object contains the original transaction fields plus a reason string.

Examples

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"
      }
    ]
  }'

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();

Response

{
  "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

string

required

Bearer token.

array

required

Array of transaction objects. Each item requires customerId and amount.

Show Transaction object

string

required

UUID of the customer to debit.

number

required

Amount in kobo. Must be greater than 1.

string

Unique reference for this transaction. Minimum 10 characters.

string

Reference for the batch. Minimum 10 characters.

Examples

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"
      }
    ]
  }'

Response

{
  "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

string

required

Bearer token.

array

required

Show Transaction object

string

required

UUID of the wallet to credit.

number

required

Amount in kobo. Must be greater than 1.

string

Unique transaction reference. Minimum 10 characters.

string

Reference for the batch. Minimum 10 characters.

Examples

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"
      }
    ]
  }'

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, but debits the listed wallets.

array

required

Show Transaction object

string

required

UUID of the wallet to debit.

number

required

Amount in kobo. Must be greater than 1.

string

Unique transaction reference. Minimum 10 characters.

string

Reference for the batch. Minimum 10 characters.

Examples

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"
      }
    ]
  }'

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

string

required

Bearer token.

Examples

curl "https://api.tagpay.ng/v1/wallet/bulk-credit-customer-records" \
  -H "Authorization: Bearer <token>"

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

string

required

Bearer token.

Examples

curl "https://api.tagpay.ng/v1/wallet/bulk-credit-customer-status" \
  -H "Authorization: Bearer <token>"

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

string

required

Bearer token.

string

required

The ID of the batch to cancel.

Examples

curl -X DELETE "https://api.tagpay.ng/v1/wallet/bulk-credit-customer/batch_abc123def456" \
  -H "Authorization: Bearer <token>"

Response

{
  "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

400 Batch Reference Exists

{
  "status": false,
  "message": "Reference already exist."
}

Wallets

Transfers

Transactions

Webhooks

Bulk create wallets via CSV

Request

CSV format

Response

Examples

Batch credit customer wallets

Request

Response

Examples

Batch debit customer wallets

Request

Examples

Batch credit by wallet ID

Request

Examples

Batch debit by wallet ID

Request

Examples

List bulk credit records

Request

Examples

Check batch credit status

Request

Examples

Cancel a batch

Request

Examples

Error responses

​Bulk create wallets via CSV

​Request

​CSV format

​Response

​Examples

​Batch credit customer wallets

​Request

​Response

​Examples

​Batch debit customer wallets

​Request

​Examples

​Batch credit by wallet ID

​Request

​Examples

​Batch debit by wallet ID

​Request

​Examples

​List bulk credit records

​Request

​Examples

​Check batch credit status

​Request

​Examples

​Cancel a batch

​Request

​Examples

​Error responses

Bulk create wallets via CSV

Request

CSV format

Response

Examples

Batch credit customer wallets

Request

Response

Examples

Batch debit customer wallets

Request

Examples

Batch credit by wallet ID

Request

Examples

Batch debit by wallet ID

Request

Examples

List bulk credit records

Request

Examples

Check batch credit status

Request

Examples

Cancel a batch

Request

Examples

Error responses