Transaction Details

Get transaction info

Retrieve a single transaction by its ID or reference. You must provide at least one of transactionId or reference.

GET https://api.tagpay.ng/v1/transaction/info

Query parameters

string

The UUID of the transaction. Takes precedence over reference when both are provided.

string

The unique reference string assigned to the transaction.

You must supply either transactionId or reference. Requests that omit both will receive a 400 error.

Response

boolean

true when the request succeeded.

object

The matching transaction record.

Show Transaction object

string

Unique transaction identifier (UUID).

string

Transaction reference string.

string

CREDIT or DEBIT.

string

success, pending, or failed.

number

Transaction amount in kobo.

number

Processing fee in kobo.

number

VAT in kobo.

number

Total deducted amount including fee and VAT.

string

Currency code, e.g. NGN.

string

Transaction category.

string

Transaction description.

string

Source account or wallet.

string

Destination account or wallet.

number

Wallet balance before the transaction.

number

Wallet balance after the transaction.

object

Arbitrary metadata attached to the transaction.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

curl --request GET \
  --url "https://api.tagpay.ng/v1/transaction/info?reference=TXN-20240401-001" \
  --header "Authorization: Bearer <token>"

curl --request GET \
  --url "https://api.tagpay.ng/v1/transaction/info?transactionId=a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  --header "Authorization: Bearer <token>"

{
  "status": true,
  "transaction": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "reference": "TXN-20240401-001",
    "type": "DEBIT",
    "status": "success",
    "amount": 500000,
    "fee": 1000,
    "vat": 75,
    "total": 501075,
    "currency": "NGN",
    "category": "BANK_TRANSFER",
    "description": "Transfer to Access Bank",
    "source": "wallet_001",
    "destination": "0123456789",
    "balance_before": 1000000,
    "balance_after": 498925,
    "metadata": {},
    "createdAt": "2024-04-01T10:30:00.000Z",
    "updatedAt": "2024-04-01T10:30:05.000Z"
  }
}

{
  "status": false,
  "message": "Record not found"
}

Get batch transaction details

Retrieve the details of a single batch transaction by its reference.

GET https://api.tagpay.ng/v1/transaction/batch/:reference

Path parameters

string

required

The reference of the batch transaction.

Response

boolean

true when the request succeeded.

object

The batch transaction record. Internal fields mode and merchantId are excluded.

curl --request GET \
  --url "https://api.tagpay.ng/v1/transaction/batch/BATCH-20240401-001" \
  --header "Authorization: Bearer <token>"

{
  "status": true,
  "data": {
    "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "reference": "BATCH-20240401-001",
    "type": "DEBIT",
    "status": "success",
    "totalAmount": 5000000,
    "totalCount": 10,
    "category": "BATCH_BANK_TRANSFER",
    "createdAt": "2024-04-01T14:00:00.000Z",
    "updatedAt": "2024-04-01T14:05:30.000Z"
  }
}

{
  "status": false,
  "message": "Transaction cannot be found!"
}

Approve a pending transaction

Approve a pending transaction that is at or above your user’s configured approval limit. You cannot approve a transaction you initiated unless you are the merchant account owner.

POST https://api.tagpay.ng/v1/transaction/approve

Request body

string

required

The UUID of the pending transaction to approve.

Response

boolean

true when the approval succeeded.

string

Confirmation message: "Transaction successfully approved.".

This action is irreversible once the underlying transfer has been processed. Ensure you have verified the transaction details before approving.

curl --request POST \
  --url "https://api.tagpay.ng/v1/transaction/approve" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "transactionId": "c3d4e5f6-a7b8-9012-cdef-123456789012"
  }'

{
  "status": true,
  "message": "Transaction successfully approved."
}

{
  "status": false,
  "message": "You are not authorized to approve this transaction."
}

{
  "status": false,
  "message": "Transaction has already been processed."
}

{
  "status": false,
  "message": "You cannot approve transaction you initiated."
}

Reverse a transaction

Reverse a completed transaction and credit the originating wallet. This endpoint is restricted to admin users only.

POST https://api.tagpay.ng/v1/transaction/reverse

This endpoint requires admin-level access. Merchant tokens will receive a 403 Forbidden response. Only transactions in a pending state can be reversed.

Request body

string

The reference string of the transaction to reverse. Provide either this or transactionId.

string

The UUID of the transaction to reverse. Takes precedence when both fields are present.

Response

boolean

true when the reversal succeeded.

string

Confirmation message: "Transaction successfully reversed".

The reversal creates a corresponding CREDIT transaction with reference prefixed r- (e.g. r-TXN-20240401-001) and marks the original transaction as failed.

curl --request POST \
  --url "https://api.tagpay.ng/v1/transaction/reverse" \
  --header "Authorization: Bearer <admin-token>" \
  --header "Content-Type: application/json" \
  --data '{
    "reference": "TXN-20240401-001"
  }'

{
  "status": true,
  "message": "Transaction successfully reversed"
}

{
  "status": false,
  "message": "You can only reverse transaction in pending state"
}

{
  "status": false,
  "message": "Transaction not found"
}

Remove a pending transaction

Cancel and remove a pending transaction. The transaction status is set to CANCELLED.

DELETE https://api.tagpay.ng/v1/transaction/:transactionId

Path parameters

string

required

The UUID of the pending transaction to cancel.

Response

boolean

true when the cancellation succeeded.

string

Confirmation message: "Transaction successfully declined.".

curl --request DELETE \
  --url "https://api.tagpay.ng/v1/transaction/c3d4e5f6-a7b8-9012-cdef-123456789012" \
  --header "Authorization: Bearer <token>"

{
  "status": true,
  "message": "Transaction successfully declined."
}

{
  "status": false,
  "message": "There is a problem retrieving transactions"
}

Wallets

Transfers

Transactions

Webhooks

Get transaction info

Query parameters

Response

Get batch transaction details

Path parameters

Response

Approve a pending transaction

Request body

Response

Reverse a transaction

Request body

Response

Remove a pending transaction

Path parameters

Response

​Get transaction info

​Query parameters

​Response

​Get batch transaction details

​Path parameters

​Response

​Approve a pending transaction

​Request body

​Response

​Reverse a transaction

​Request body

​Response

​Remove a pending transaction

​Path parameters

​Response

Get transaction info

Query parameters

Response

Get batch transaction details

Path parameters

Response

Approve a pending transaction

Request body

Response

Reverse a transaction

Request body

Response

Remove a pending transaction

Path parameters

Response