Transactions

Every movement of funds in TagPay is recorded as a transaction. Whether you credit a customer wallet, process a bank transfer, or run a batch payout, each operation produces a transaction record with a unique reference, a type, and a state that reflects its progress.

Transaction types

Type	Description
Credit (`CREDIT`)	Funds added to a wallet — e.g. an inbound bank transfer or a merchant credit
Debit (`DEBIT`)	Funds removed from a wallet — e.g. a bank transfer or a merchant debit
Bank transfer	A debit that sends funds to an external Nigerian bank account via NIP
Wallet transfer	A transfer from one TagPay wallet to another, settled instantly

When querying transaction lists, filter by type using type=CREDIT, type=DEBIT, or type=ALL (default).

Transaction states

A transaction moves through states as it is processed:

State	Meaning
Pending	The transaction has been created but not yet processed.
Approved	The transaction has been authorised and queued for settlement.
Completed / Success	Funds have settled and the transaction is final.
Failed	The transaction could not be processed. No funds moved.
Reversed	The transaction was successfully reversed after completion.

Not all transaction types go through every state. Wallet-to-wallet transfers typically settle immediately and skip the pending/approved flow.

Pending transactions

Transactions that require explicit approval queue up as pending. Retrieve them with:

GET https://api.tagpay.ng/v1/transaction/pending
Authorization: Bearer <your-access-token>

Approving a pending transaction

POST https://api.tagpay.ng/v1/transaction/approve
Authorization: Bearer <your-access-token>
Content-Type: application/json

{
  "transactionId": "txn_abc123"
}

Removing a pending transaction

Discard a pending transaction that should not be processed:

DELETE https://api.tagpay.ng/v1/transaction/:transactionId
Authorization: Bearer <your-access-token>

Transaction references

Every transaction is identified by a reference — a unique string that you provide or that TagPay generates. References let you:

Look up a specific transaction by its reference
Safely retry a request without double-processing (idempotency)
Correlate TagPay records with your own internal order or payment IDs

Always supply your own reference when creating transactions. References must be at least 10 characters. Using the same reference for two different transactions will cause the second request to be rejected.

Looking up a transaction by reference

GET https://api.tagpay.ng/v1/transaction/info?reference=ref_20260401_001
Authorization: Bearer <your-access-token>

Or via the merchant-scoped endpoint:

GET https://api.tagpay.ng/v1/merchant/transaction/:reference
Authorization: Bearer <your-access-token>

Batch transactions

Batch operations group multiple credits or debits into a single API call, each identified by a shared batchReference. This is efficient for payroll runs, bulk disbursements, and mass collections.

Creating a batch credit

POST https://api.tagpay.ng/v1/wallet/batch-credit-customer-wallet
Authorization: Bearer <your-access-token>
Content-Type: application/json

{
  "batchReference": "batch_payroll_20260401",
  "transactions": [
    {
      "customerId": "cust_001",
      "amount": 50000,
      "reference": "ref_payroll_001_20260401"
    },
    {
      "customerId": "cust_002",
      "amount": 75000,
      "reference": "ref_payroll_002_20260401"
    }
  ]
}

Field	Required	Description
`batchReference`	Yes	Unique identifier for the batch (min. 10 characters)
`transactions[].customerId`	Yes	ID of the customer wallet to credit
`transactions[].amount`	Yes	Amount in kobo (must be greater than 0)
`transactions[].reference`	No	Per-transaction reference (min. 10 characters)

Retrieving batch status

GET https://api.tagpay.ng/v1/transaction/batch
Authorization: Bearer <your-access-token>

Retrieve the details of a specific batch by its reference:

GET https://api.tagpay.ng/v1/transaction/batch/:reference
Authorization: Bearer <your-access-token>

Uploading batches via CSV

For very large disbursements, upload a CSV file directly:

POST https://api.tagpay.ng/v1/wallet/upload-bulk-credit-customer
Authorization: Bearer <your-access-token>
Content-Type: multipart/form-data

After upload, process the batch:

POST https://api.tagpay.ng/v1/wallet/process-bulk-credit-customer
Authorization: Bearer <your-access-token>
Content-Type: application/json

{
  "batchReference": "batch_payroll_20260401"
}

Check the status of an uploaded batch:

GET https://api.tagpay.ng/v1/wallet/bulk-credit-customer-status
Authorization: Bearer <your-access-token>

Transaction limits

Transaction limits control the maximum amount a customer can transact in a given period. Limits are applied at the customer tier level (TIER_1, TIER_2, TIER_3) and are configured per merchant. If a transaction exceeds a customer’s tier limit, it is rejected at the point of creation. To allow higher volumes, upgrade the customer’s KYC tier. See Customers for details on tier upgrades. Retrieve your merchant’s current limit settings:

GET https://api.tagpay.ng/v1/merchant/limits
Authorization: Bearer <your-access-token>

Check how much of each limit has been consumed today:

GET https://api.tagpay.ng/v1/merchant/limits/usage
Authorization: Bearer <your-access-token>

Reversals

A reversal returns funds to the originating wallet after a transaction has completed. Reversals are appropriate when a transaction was processed in error or a customer dispute requires a refund.

Not all transaction types are reversible. Reversals must be authorised by an administrator or a merchant with reversal permissions enabled.

Reversing a batch transaction

POST https://api.tagpay.ng/v1/wallet/reverse-batch-transaction
Authorization: Bearer <your-access-token>
Content-Type: application/json

{
  "batchReference": "batch_payroll_20260401",
  "description": "Incorrect payment amounts — reversing full batch"
}

Viewing your reversal history

GET https://api.tagpay.ng/v1/merchant/reversals
Authorization: Bearer <your-access-token>

Retrieve a specific reversal record:

GET https://api.tagpay.ng/v1/merchant/reversals/:id
Authorization: Bearer <your-access-token>

Review reversal statistics (totals by status):

GET https://api.tagpay.ng/v1/merchant/reversals/stats
Authorization: Bearer <your-access-token>

Configuring reversal settings

Control which reversal scenarios are permitted for your merchant:

GET https://api.tagpay.ng/v1/merchant/reversal-config
PUT  https://api.tagpay.ng/v1/merchant/reversal-config
Authorization: Bearer <your-access-token>

Downloading transaction history

Merchant transactions (CSV)

Export all transactions for your merchant account as a CSV file:

GET https://api.tagpay.ng/v1/transaction/download/merchant
Authorization: Bearer <your-access-token>

Apply filters using query parameters: type, category, startDate, endDate, status.

Customer transactions (CSV)

Export the full transaction history for a specific customer:

GET https://api.tagpay.ng/v1/transaction/download/customer?customerId=cust_abc123
Authorization: Bearer <your-access-token>

Batch transactions (CSV)

Export your batch transaction list:

GET https://api.tagpay.ng/v1/transaction/batch/export
Authorization: Bearer <your-access-token>

Pending transactions (CSV)

Export the current pending transaction queue:

GET https://api.tagpay.ng/v1/transaction/pending/export
Authorization: Bearer <your-access-token>

Viewing customer transactions

As a merchant, retrieve the transaction history for any customer under your account:

GET https://api.tagpay.ng/v1/transaction/customer?customerId=cust_abc123&type=ALL&page=1&perPage=20
Authorization: Bearer <your-access-token>

Customers can also view their own transactions when authenticated:

GET https://api.tagpay.ng/v1/customer/transactions
Authorization: Bearer <customer_token>

Wallets

Credit, debit, and manage customer wallet balances

Funds transfer

Send funds to banks and between wallets

Webhooks

Receive real-time notifications for transaction events

API reference

Full endpoint reference for transaction operations

Get Started

Core Concepts

Guides

Transaction types

Transaction states

Pending transactions

Approving a pending transaction

Removing a pending transaction

Transaction references

Looking up a transaction by reference

Batch transactions

Creating a batch credit

Retrieving batch status

Uploading batches via CSV

Transaction limits

Reversals

Reversing a batch transaction

Viewing your reversal history

Configuring reversal settings

Downloading transaction history

Merchant transactions (CSV)

Customer transactions (CSV)

Batch transactions (CSV)

Pending transactions (CSV)

Viewing customer transactions

Wallets

Funds transfer

Webhooks

API reference

​Transaction types

​Transaction states

​Pending transactions

​Approving a pending transaction

​Removing a pending transaction

​Transaction references

​Looking up a transaction by reference

​Batch transactions

​Creating a batch credit

​Retrieving batch status

​Uploading batches via CSV

​Transaction limits

​Reversals

​Reversing a batch transaction

​Viewing your reversal history

​Configuring reversal settings

​Downloading transaction history

​Merchant transactions (CSV)

​Customer transactions (CSV)

​Batch transactions (CSV)

​Pending transactions (CSV)

​Viewing customer transactions

​Related pages

Wallets

Funds transfer

Webhooks

API reference

Transaction types

Transaction states

Pending transactions

Approving a pending transaction

Removing a pending transaction

Transaction references

Looking up a transaction by reference

Batch transactions

Creating a batch credit

Retrieving batch status

Uploading batches via CSV

Transaction limits

Reversals

Reversing a batch transaction

Viewing your reversal history

Configuring reversal settings

Downloading transaction history

Merchant transactions (CSV)

Customer transactions (CSV)

Batch transactions (CSV)

Pending transactions (CSV)

Viewing customer transactions

Related pages