Get Merchant Transactions

Get merchant customer transactions with pagination

Returns customer transactions (deposits, payouts, refunds from end customers).
For internal wallet operations (settlements, balance movements), use /merchants/wallet/transactions.

Query Parameters:

currency_code (optional): Filter by currency (e.g., USD, EUR)

transaction_type (optional): Filter by type (deposit, payout, refund)

status (optional): Filter by status (pending, completed, failed, cancelled)

page: Page number (starts from 1, default: 1)

size: Number of transactions per page (default: 50, max: 100)

Returns:
Customer transactions ordered by created_at (newest first) with pagination metadata including:

transaction_id: Unique transaction ID

transaction_type: deposit, payout, refund

status: pending, completed, failed, cancelled

settlement_status: unsettled, settled

amount: Gross transaction amount

fee_amount: Fees charged

net_amount: Net amount (amount - fees)

customer_email: Customer email (if available)

customer_name: Customer name (if available)

external_reference: External payment reference

created_at: Transaction timestamp

Examples:

Get all transactions: GET /api/v1/merchants/customer/transactions

Get USD deposits: GET /api/v1/merchants/customer/transactions?currency_code=USD&transaction_type=deposit

Get completed transactions: GET /api/v1/merchants/customer/transactions?status=completed&page=2

{ "data": [ { "transaction_id": "64e83f98-47ba-435d-a0fc-87e1212c48f0", "merchant_id": "7bb54443-6fc9-4a1d-ab46-d787ec90c87f", "currency_id": "dd7fb8f3-c044-4dc5-a4ec-c0595a469876", "transaction_type": "deposit", "status": "completed", "amount": 200.0, "fee_amount": 0.0, "net_amount": 200.0, "created_at": "2025-11-17T17:02:02.006852", "updated_at": null, "completed_at": "2025-11-17T16:02:02.009258", "failed_at": null, "settlement_status": "unsettled", "settled_at": null, "settlement_batch_id": null, "customer_email": "test.ngn@example.com", "customer_name": "Chidi NGN Test", "customer_phone": "+2348012345678", "checkout_session_id": null, "payment_method": null, "payout_type": null, "recipient_name": null, "recipient_email": null, "recipient_phone": null, "payout_reason": null, "bank_account_number": null, "bank_routing_number": null, "bank_name": null, "account_holder_name": null, "mobile_number": null, "network_provider": null, "provider": null, "provider_reference": null, "provider_metadata": null, "meta_data": { "checkout_id": "16bf6799-bcd1-4493-a57e-2b59904be3cc" }, "refunds_transaction_id": null, "external_reference": "16bf6799-bcd1-4493-a57e-2b59904be3cc", "idempotency_key": null, "notes": "Checkout approved: 16bf6799-bcd1-4493-a57e-2b59904be3cc" }, { "transaction_id": "3b0d0c05-476a-448b-abbf-8628b3daf7d6", "merchant_id": "7bb54443-6fc9-4a1d-ab46-d787ec90c87f", "currency_id": "dd7fb8f3-c044-4dc5-a4ec-c0595a469876", "transaction_type": "deposit", "status": "completed", "amount": 2000.0, "fee_amount": 0.0, "net_amount": 2000.0, "created_at": "2025-11-13T13:19:15.083076", "updated_at": null, "completed_at": "2025-11-13T12:19:15.100833", "failed_at": null, "settlement_status": "unsettled", "settled_at": null, "settlement_batch_id": null, "customer_email": "customer@example.com", "customer_name": "John Doe", "customer_phone": "+1234567890", "checkout_session_id": null, "payment_method": null, "payout_type": null, "recipient_name": null, "recipient_email": null, "recipient_phone": null, "payout_reason": null, "bank_account_number": null, "bank_routing_number": null, "bank_name": null, "account_holder_name": null, "mobile_number": null, "network_provider": null, "provider": null, "provider_reference": null, "provider_metadata": null, "meta_data": { "checkout_id": "25f14d1d-82e5-49ad-92aa-5da5da24bf83" }, "refunds_transaction_id": null, "external_reference": "25f14d1d-82e5-49ad-92aa-5da5da24bf83", "idempotency_key": null, "notes": "Checkout approved: 25f14d1d-82e5-49ad-92aa-5da5da24bf83" } ], "pagination": { "total": 2, "page": 1, "size": 10, "total_pages": 1, "has_more": false }, "message": "Merchant transactions retrieved successfully", "status": "success" }

Request

Responses