Skip to main content
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

TypeDescription
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 transferA debit that sends funds to an external Nigerian bank account via NIP
Wallet transferA 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:
StateMeaning
PendingThe transaction has been created but not yet processed.
ApprovedThe transaction has been authorised and queued for settlement.
Completed / SuccessFunds have settled and the transaction is final.
FailedThe transaction could not be processed. No funds moved.
ReversedThe 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"
    }
  ]
}
FieldRequiredDescription
batchReferenceYesUnique identifier for the batch (min. 10 characters)
transactions[].customerIdYesID of the customer wallet to credit
transactions[].amountYesAmount in kobo (must be greater than 0)
transactions[].referenceNoPer-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