Wallet Core Admin

Overview

Platform admin endpoints for viewing and analyzing POS transactions and settlements. These endpoints provide comprehensive visibility into payment processing across all tenants.

Transaction Lifecycle

POS transactions flow through a defined lifecycle from initiation to settlement.

Stage	Description
Inflow	Transaction initiated at terminal - card swipe, NFC tap, or bank transfer
Processing	Payment processed through the card processor or payment provider
Confirmation	Transaction confirmed as completed or failed
Settlement	Successful transactions batched into settlement jobs based on profile frequency
Payout	Settlement funds transferred to merchant's designated account

Transaction Channels

POS terminals support multiple payment channels, each with unique identifiers and processing flows.

Channel	Code	Description	Unique Reference
Debit Card	card_processor	Traditional card swipe or chip insert	RRN (Retrieval Reference Number)
NFC Card	nfc_purchase	Contactless tap-to-pay transactions	NFC Code
Bank Transfer	va_pos_payment	Transfer to terminal's virtual account	VA Session ID
Funds Transfer	funds_transfer_inflow	Direct funds transfer inflow	Reference ID

Transaction Statuses

Transaction status indicates the current state in the processing lifecycle.

Status	Description	Settable
pending	Transaction initiated, awaiting processor confirmation	No
completed	Transaction successfully processed and confirmed	Yes
failed	Transaction failed during processing	No
reversed	Transaction was reversed after completion	No

Settlement States

Settlement jobs track the batching and payout of transactions.

State	Description
pending	Settlement job created, awaiting transaction collection
collecting	Actively collecting transactions for the settlement window
payout_submitted	Payout request submitted to the provider
settled	Funds successfully transferred to merchant
failed	Settlement failed - may require retry or manual review
needs_manual_review	Settlement flagged for manual intervention

List POS Transactions

Retrieve POS inflow transactions with comprehensive filtering and pagination.

Endpoint

GET/api/v1/admin/pos-transactions

List all POS inflow transactions across the platform. Supports filtering by tenant, terminal, status, channel, date range, and amount range.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}

Query Parameters

Parameter	Type	Required	Description
`tenant_id`	string	No	Filter by tenant UUID. Omit to view all tenants.
`terminal_id`	string	No	Filter by terminal ID (human code or UUID)
`status`	string	No	Comma-separated statusesValues: pending, completed, failed, reversed
`channel`	string	No	Comma-separated channelsValues: card_processor, nfc_purchase, va_pos_payment, funds_transfer_inflow
`type`	string	No	Transaction typeValues: credit, debit
`from_date`	string	No	Start date filter (RFC3339 format: 2024-01-01T00:00:00Z)
`to_date`	string	No	End date filter (RFC3339 format)
`min_amount`	string	No	Minimum transaction amount (decimal string)
`max_amount`	string	No	Maximum transaction amount (decimal string)
`search`	string	No	Search by RRN, identifier, or reference
`sort`	string	No (default: registered_at)	Values: created_at, amount, completed_at, registered_at, status
`order`	string	No (default: desc)	Values: asc, desc
`page`	integer	No (default: 1)	Page number
`page_size`	integer	No (default: 20)	Items per page (max 100)

Response- Paginated list of transactions with optional summary

json

{
  "transactions": [
    {
      "id": "txn_550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "tnt_f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "tenant_name": "Acme Payments",
      "terminal_id": "2057TID001",
      "terminal_name": "Store Alpha POS",
      "profile_id": "prof_abc123",
      "processor_id": "proc_xyz789",
      "channel": "card_processor",
      "status": "completed",
      "amount": 15000,
      "currency": "NGN",
      "fee_amount": 150,
      "fee_currency": "NGN",
      "reference": "REF123456789",
      "rrn": "012345678901",
      "identifier": null,
      "nfc_code": null,
      "va_session_id": null,
      "customer_info": {
        "pan": "****1234",
        "card_type": "mastercard",
        "card_name": "JOHN DOE"
      },
      "metadata": {
        "card_pan": "****1234",
        "card_type": "mastercard"
      },
      "registered_at": "2024-01-20T14:30:00Z",
      "confirmed_at": "2024-01-20T14:30:05Z",
      "settled_job_id": "job_def456",
      "settled_at": "2024-01-20T18:00:00Z",
      "created_at": "2024-01-20T14:30:00Z",
      "updated_at": "2024-01-20T18:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1250
  },
  "summary": {
    "total_amount": "18750000.00",
    "transaction_count": 1250,
    "success_rate": 97.5
  }
}

Example Requests

bash

# List all transactions
curl -X GET "https://api.example.com/api/v1/admin/pos-transactions" \
  -H "Authorization: Bearer {admin_token}"

# Filter by tenant and status
curl -X GET "https://api.example.com/api/v1/admin/pos-transactions?tenant_id=tnt_abc123&status=completed,pending" \
  -H "Authorization: Bearer {admin_token}"

# Filter by date range and channel
curl -X GET "https://api.example.com/api/v1/admin/pos-transactions?from_date=2024-01-01T00:00:00Z&to_date=2024-01-31T23:59:59Z&channel=card_processor,nfc_purchase" \
  -H "Authorization: Bearer {admin_token}"

# Search by RRN
curl -X GET "https://api.example.com/api/v1/admin/pos-transactions?search=012345678901" \
  -H "Authorization: Bearer {admin_token}"

Transaction Response Fields

Field	Type	Description
id	string	Unique transaction identifier (UUID)
tenant_id	string	Parent tenant UUID
tenant_name	string	Tenant display name
terminal_id	string	Terminal ID (human code like '2057TID001')
terminal_name	string	Terminal display name
profile_id	string \| null	Associated terminal profile UUID
processor_id	string	Payment processor UUID
channel	string	Payment channel (card_processor, nfc_purchase, va_pos_payment)
status	string	Transaction status
amount	number	Transaction amount in minor units
currency	string	Currency code (NGN)
fee_amount	number	Fee charged for transaction
fee_currency	string	Fee currency code
reference	string	Unique transaction reference
rrn	string \| null	Retrieval Reference Number (card transactions)
nfc_code	string \| null	NFC transaction code (NFC transactions)
va_session_id	string \| null	Virtual account session ID (transfer transactions)
customer_info	object	Customer/card holder information
registered_at	string	When transaction was registered (ISO timestamp)
confirmed_at	string \| null	When transaction was confirmed
settled_job_id	string \| null	Settlement job this transaction belongs to
settled_at	string \| null	When transaction was settled

Customer Info by Channel

The customer_info object varies based on the transaction channel.

Channel	Available Fields
card_processor	pan (masked), card_type, card_name, card_expiry, issuing_bank
nfc_purchase	pan (masked), card_type, card_name, serial_number, stan
va_pos_payment	sender_name, sender_bank, sender_account (masked), session_id

Transaction Analytics

Get aggregated analytics for POS transactions with time series data.

Endpoint

GET/api/v1/admin/pos-transactions/analytics

Retrieve transaction analytics including counts, volumes, and time series data broken down by payment channel. Ideal for dashboards and reporting.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}

Query Parameters

Parameter	Type	Required	Description
`from`	string	Yes	Start date (RFC3339 format: 2024-01-01T00:00:00Z)
`to`	string	Yes	End date (RFC3339 format)
`interval`	string	No (default: day)	Time series bucket intervalValues: day, week, month
`tenant_id`	string	No	Filter analytics to a specific tenant
`channel`	string	No	Comma-separated channels to include

Response- Analytics response with summary and time series

json

{
  "period": {
    "from": "2024-01-01T00:00:00Z",
    "to": "2024-01-31T23:59:59Z",
    "interval": "day"
  },
  "summary_by_channel": {
    "card_processor": {
      "count": 15420,
      "volume": 231300000
    },
    "nfc_purchase": {
      "count": 8750,
      "volume": 87500000
    },
    "va_pos_payment": {
      "count": 3280,
      "volume": 164000000
    },
    "funds_transfer_inflow": {
      "count": 120,
      "volume": 12000000
    }
  },
  "series": [
    {
      "bucket": "2024-01-01T00:00:00Z",
      "total_count": 892,
      "total_volume": 15680000,
      "by_channel": {
        "card_processor": {
          "count": 520,
          "volume": 7800000
        },
        "nfc_purchase": {
          "count": 280,
          "volume": 4200000
        },
        "va_pos_payment": {
          "count": 92,
          "volume": 3680000
        }
      }
    },
    {
      "bucket": "2024-01-02T00:00:00Z",
      "total_count": 945,
      "total_volume": 16520000,
      "by_channel": {
        "card_processor": {
          "count": 548,
          "volume": 8220000
        },
        "nfc_purchase": {
          "count": 298,
          "volume": 4470000
        },
        "va_pos_payment": {
          "count": 99,
          "volume": 3830000
        }
      }
    }
  ]
}

Example Request

bash

# Get daily analytics for January 2024
curl -X GET "https://api.example.com/api/v1/admin/pos-transactions/analytics?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z&interval=day" \
  -H "Authorization: Bearer {admin_token}"

# Get weekly analytics for a specific tenant
curl -X GET "https://api.example.com/api/v1/admin/pos-transactions/analytics?from=2024-01-01T00:00:00Z&to=2024-03-31T23:59:59Z&interval=week&tenant_id=tnt_abc123" \
  -H "Authorization: Bearer {admin_token}"

# Get card-only analytics
curl -X GET "https://api.example.com/api/v1/admin/pos-transactions/analytics?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z&channel=card_processor,nfc_purchase" \
  -H "Authorization: Bearer {admin_token}"

Analytics Response Fields

Field	Type	Description
period.from	string	Start of analytics period (ISO timestamp)
period.to	string	End of analytics period (ISO timestamp)
period.interval	string	Bucket interval used (day, week, month)
summary_by_channel	object	Aggregated totals by channel for entire period
summary_by_channel.{channel}.count	number	Total transaction count for channel
summary_by_channel.{channel}.volume	number	Total transaction volume for channel
series	array	Time series data points
series[].bucket	string	Start of time bucket (ISO timestamp)
series[].total_count	number	Total transactions in bucket
series[].total_volume	number	Total volume in bucket
series[].by_channel	object	Breakdown by channel for this bucket

Use Cases

Use Case	Parameters
Daily dashboard	interval=day, last 7-30 days
Weekly trends	interval=week, last 4-12 weeks
Monthly reports	interval=month, last 3-12 months
Channel comparison	Include all channels, compare summary_by_channel
Tenant performance	Set tenant_id to compare individual tenants

List POS Settlements

Retrieve POS settlement jobs with filtering and pagination.

Endpoint

GET/api/v1/admin/pos-settlements

List all POS settlement jobs across the platform. Settlement jobs batch transactions from a settlement window and track the payout process.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}

Query Parameters

Parameter	Type	Required	Description
`tenant_id`	string	No	Filter by tenant UUID
`terminal_id`	string	No	Filter by terminal ID
`state`	string	No	Filter by settlement stateValues: pending, collecting, payout_submitted, settled, failed, needs_manual_review
`window_start`	string	No	Filter by window start date (RFC3339)
`window_end`	string	No	Filter by window end date (RFC3339)
`limit`	integer	No (default: 20)	Page size (max 200)
`offset`	integer	No (default: 0)	Page offset

Response- Paginated list of settlement jobs

json

{
  "data": [
    {
      "id": "job_550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "tnt_f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "tenant_name": "Acme Payments",
      "terminal_id": "2057TID001",
      "terminal_name": "Store Alpha POS",
      "profile_id": "prof_abc123",
      "mode": "automatic",
      "settlement_frequency": "end_of_day",
      "state": "settled",
      "amount": 1250000,
      "currency": "NGN",
      "settlement_amount": "1237500.00",
      "transaction_count": 85,
      "attempts": 1,
      "max_attempts": 3,
      "window_start": "2024-01-20T00:00:00Z",
      "window_end": "2024-01-20T23:59:59Z",
      "payout_reference": "PAY_ABC123XYZ",
      "metadata": {
        "settlement_route": "terminal_settlement_account",
        "transaction_total_amount": "1250000",
        "transaction_total_fee": "12500"
      },
      "created_at": "2024-01-21T00:00:00Z",
      "updated_at": "2024-01-21T00:05:00Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total_count": 1580
  }
}

Example Requests

bash

# List all settlements
curl -X GET "https://api.example.com/api/v1/admin/pos-settlements" \
  -H "Authorization: Bearer {admin_token}"

# Filter by state
curl -X GET "https://api.example.com/api/v1/admin/pos-settlements?state=failed" \
  -H "Authorization: Bearer {admin_token}"

# Filter by date range
curl -X GET "https://api.example.com/api/v1/admin/pos-settlements?window_start=2024-01-01T00:00:00Z&window_end=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer {admin_token}"

# Filter by terminal
curl -X GET "https://api.example.com/api/v1/admin/pos-settlements?terminal_id=2057TID001" \
  -H "Authorization: Bearer {admin_token}"

Settlement Response Fields

Field	Type	Description
id	string	Unique settlement job identifier
tenant_id	string	Parent tenant UUID
tenant_name	string	Tenant display name
terminal_id	string	Terminal ID (human code)
terminal_name	string	Terminal display name
profile_id	string	Associated terminal profile UUID
mode	string	Settlement mode (automatic, manual)
settlement_frequency	string	Frequency from profile (instant, hourly, six_hourly, end_of_day)
state	string	Current settlement state
amount	number	Total transaction amount before fees
currency	string	Currency code
settlement_amount	string	Net amount to settle (after fees)
transaction_count	number	Number of transactions in this settlement
attempts	number	Number of payout attempts made
max_attempts	number	Maximum allowed payout attempts
window_start	string	Settlement window start (ISO timestamp)
window_end	string	Settlement window end (ISO timestamp)
payout_reference	string \| null	Provider payout reference (when submitted)
metadata	object	Additional settlement metadata

Settlement Metadata

The metadata object contains additional settlement details.

Field	Type	Description
settlement_route	string	Where funds are routed (terminal_settlement_account or profile_wallet)
transaction_total_amount	string	Sum of all transaction amounts
transaction_total_fee	string	Sum of all transaction fees
transaction_ids	array	List of transaction IDs included in settlement
profile_settlement_account_id	string	Profile wallet account ID (for profile_wallet route)

Settlement Analytics

Get aggregated analytics for POS settlements with time series data by state.

Endpoint

GET/api/v1/admin/pos-settlements/analytics

Retrieve settlement analytics including counts and time series data broken down by settlement state. Useful for monitoring settlement health and identifying issues.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}

Query Parameters

Parameter	Type	Required	Description
`from`	string	Yes	Start date (RFC3339 format)
`to`	string	Yes	End date (RFC3339 format)
`interval`	string	No (default: day)	Time series bucket intervalValues: day, week, month
`tenant_id`	string	No	Filter analytics to a specific tenant
`profile_id`	string	No	Filter analytics to a specific profile
`terminal_id`	string	No	Filter analytics to a specific terminal
`states`	string	No	Comma-separated states to include (e.g., 'settled,pending,failed')

Response- Analytics response with summary and time series by state

json

{
  "period": {
    "from": "2024-01-01T00:00:00Z",
    "to": "2024-01-31T23:59:59Z",
    "interval": "day"
  },
  "summary_by_state": {
    "settled": 1450,
    "pending": 25,
    "collecting": 12,
    "payout_submitted": 8,
    "failed": 15,
    "needs_manual_review": 3
  },
  "series": [
    {
      "bucket": "2024-01-01T00:00:00Z",
      "total": 52,
      "by_state": {
        "settled": 48,
        "pending": 2,
        "collecting": 1,
        "failed": 1
      }
    },
    {
      "bucket": "2024-01-02T00:00:00Z",
      "total": 55,
      "by_state": {
        "settled": 52,
        "pending": 1,
        "collecting": 2
      }
    }
  ]
}

Example Request

bash

# Get daily settlement analytics
curl -X GET "https://api.example.com/api/v1/admin/pos-settlements/analytics?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z&interval=day" \
  -H "Authorization: Bearer {admin_token}"

# Get analytics for failed settlements only
curl -X GET "https://api.example.com/api/v1/admin/pos-settlements/analytics?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z&states=failed,needs_manual_review" \
  -H "Authorization: Bearer {admin_token}"

# Get analytics for a specific terminal
curl -X GET "https://api.example.com/api/v1/admin/pos-settlements/analytics?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z&terminal_id=2057TID001" \
  -H "Authorization: Bearer {admin_token}"

Monitoring Use Cases

Scenario	What to Monitor	Action
Settlement Health	Ratio of settled vs failed	Alert if failure rate exceeds threshold
Pending Backlog	Count of pending/collecting states	Investigate if backlog grows
Manual Review Queue	Count of needs_manual_review	Prioritize manual intervention
Payout Delays	Count of payout_submitted over time	Check provider status if stuck

Get Settlement Transactions

Retrieve the individual transactions that make up a settlement job.

Endpoint

GET/api/v1/admin/pos-settlements/{jobID}/transactions

Get the list of transactions included in a specific settlement job. Useful for settlement reconciliation and dispute resolution.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}

Path Parameters

Parameter	Type	Required	Description
`jobID`	string	Yes	UUID of the settlement job

Query Parameters

Parameter	Type	Required	Description
`tenant_id`	string	Yes	UUID of the tenant (required for authorization)

Response- List of transactions in the settlement

json

{
  "transactions": [
    {
      "id": "txn_550e8400-e29b-41d4-a716-446655440000",
      "reference": "REF123456789",
      "amount": 15000,
      "fee": 150,
      "net": 14850,
      "currency": "NGN",
      "channel": "card_processor",
      "terminal_id": "2057TID001",
      "terminal_name": "Store Alpha POS",
      "created_at": "2024-01-20T14:30:00Z"
    },
    {
      "id": "txn_660f9511-f39c-52e5-b827-557766551111",
      "reference": "REF987654321",
      "amount": 8500,
      "fee": 85,
      "net": 8415,
      "currency": "NGN",
      "channel": "nfc_purchase",
      "terminal_id": "2057TID001",
      "terminal_name": "Store Alpha POS",
      "created_at": "2024-01-20T15:45:00Z"
    }
  ]
}

Example Request

bash

curl -X GET "https://api.example.com/api/v1/admin/pos-settlements/job_550e8400-e29b-41d4-a716-446655440000/transactions?tenant_id=tnt_f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Authorization: Bearer {admin_token}"

Transaction Fields

Field	Type	Description
id	string	Transaction UUID
reference	string	Unique transaction reference
amount	number	Gross transaction amount
fee	number	Fee deducted from transaction
net	number	Net amount (amount - fee)
currency	string	Currency code
channel	string	Payment channel
terminal_id	string	Terminal ID
terminal_name	string	Terminal display name
created_at	string	Transaction timestamp

Reconciliation Tips

Use this endpoint for settlement reconciliation:

Check	Formula/Comparison
Transaction Total	Sum of all transaction.amount should match settlement.amount
Fee Total	Sum of all transaction.fee should match metadata.transaction_total_fee
Net Total	Sum of all transaction.net should match settlement.settlement_amount
Count	Array length should match settlement.transaction_count

Get Settlement Payout

Retrieve payout details for a settlement job.

Endpoint

GET/api/v1/admin/pos-settlements/{jobID}/payout

Get detailed payout information for a settlement job including provider response, bank details, and transfer status.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}

Path Parameters

Parameter	Type	Required	Description
`jobID`	string	Yes	UUID of the settlement job

Query Parameters

Parameter	Type	Required	Description
`tenant_id`	string	Yes	UUID of the tenant (required for authorization)

Response- Payout details for the settlement

json

{
  "settlement_id": "job_550e8400-e29b-41d4-a716-446655440000",
  "payout_reference": "PAY_ABC123XYZ",
  "status": "success",
  "amount": "1237500.00",
  "currency": "NGN",
  "destination": {
    "bank_code": "058",
    "bank_name": "GTBank",
    "account_number": "0123456789",
    "account_name": "Acme Store Ltd"
  },
  "provider": "paystack",
  "provider_reference": "PSK_TRF_abc123xyz",
  "provider_response": {
    "status": "success",
    "message": "Transfer successful",
    "transfer_code": "TRF_abc123xyz"
  },
  "submitted_at": "2024-01-21T00:01:00Z",
  "completed_at": "2024-01-21T00:05:00Z",
  "created_at": "2024-01-21T00:00:00Z"
}

Example Request

bash

curl -X GET "https://api.example.com/api/v1/admin/pos-settlements/job_550e8400-e29b-41d4-a716-446655440000/payout?tenant_id=tnt_f47ac10b-58cc-4372-a567-0e02b2c3d479" \
  -H "Authorization: Bearer {admin_token}"

Payout Response Fields

Field	Type	Description
settlement_id	string	Parent settlement job ID
payout_reference	string	Internal payout reference
status	string	Payout status (pending, success, failed)
amount	string	Payout amount (decimal string)
currency	string	Currency code
destination	object	Recipient bank account details
destination.bank_code	string	Bank CBN code
destination.bank_name	string	Bank display name
destination.account_number	string	Bank account number
destination.account_name	string	Account holder name
provider	string	Payout provider used
provider_reference	string	Provider's transaction reference
provider_response	object	Raw response from provider
submitted_at	string	When payout was submitted to provider
completed_at	string \| null	When payout completed (if successful)

Payout Status Reference

Status	Description	Next Steps
pending	Payout queued but not yet submitted	Wait for system to process
success	Funds successfully transferred	No action required
failed	Payout failed	Review provider_response, investigate, retry settlement

Error Responses

Status	Code	Description
404	SETTLEMENT_NOT_FOUND	Settlement job does not exist
404	PAYOUT_NOT_FOUND	Settlement has no payout record (may not have reached payout stage)
403	ACCESS_DENIED	Admin not authorized to view this tenant's data

Best Practices

Recommended patterns for working with POS transactions and settlements.

Efficient Querying

Optimize your API usage for better performance.

Practice	Recommendation
Use Date Filters	Always include from_date/to_date or window_start/window_end to limit result sets
Paginate Large Results	Use page/page_size or limit/offset for lists over 100 items
Filter Early	Apply tenant_id, terminal_id, and status filters to reduce data transfer
Cache Analytics	Analytics responses are stable for historical periods - cache appropriately

Monitoring & Alerting

Key metrics to monitor for healthy POS operations.

Metric	Source	Alert Threshold
Transaction Success Rate	transactions summary.success_rate	< 95%
Settlement Failure Rate	settlements analytics failed/(total)	> 5%
Pending Settlement Backlog	settlements analytics pending count	> 100 or growing
Manual Review Queue	settlements analytics needs_manual_review	> 10

Reconciliation Workflow

Steps for daily reconciliation of POS transactions.

Step	Action	Endpoint
1. Get Day's Transactions	List all completed transactions for the day	GET /pos-transactions?status=completed&from_date=...
2. Get Day's Settlements	List all settlements for the day	GET /pos-settlements?window_start=...
3. Match Totals	Compare transaction totals with settlement amounts	Manual calculation
4. Drill Down Discrepancies	Get transactions for specific settlements	GET /pos-settlements/{id}/transactions
5. Verify Payouts	Check payout status for each settlement	GET /pos-settlements/{id}/payout