Wallet Core Admin

Overview

Platform admin endpoints for managing payment processors. Processors are external payment providers that handle transaction routing, settlement, and various financial operations.

What is a Processor?

A processor represents an external payment provider integrated with the platform. Each processor has specific capabilities, fee structures, and settlement configurations.

Aspect	Description
Identity	Unique code and display name for identification
Category	Type of transactions handled (debit card, virtual account, etc.)
Flow Direction	Whether it supports inflows, outflows, or both
Settlement	Bank settlement details and timing configuration
Fees	Fee rules for different transaction types
GL Accounts	General ledger accounts for financial tracking

Processor Categories

Processors are organized by the type of transactions they handle.

Category	Code	Description
Debit Card	debit_card	Card payment processing (POS, online)
Virtual Account Inflow	virtual_account_inflow	Incoming transfers via virtual accounts
Funds Transfer	funds_transfer	Bank-to-bank transfers and payouts
Identity	identity	KYC and identity verification services
Bills Payment	bills_payment	Utility and service bill payments

Processor Status

Status	Description	Transactions Allowed
active	Processor is operational and accepting transactions	Yes
inactive	Processor is disabled, no new transactions routed	No

Required Permissions

Admin permissions required for processor operations.

Operation	Permission
List/View Processors	view_processors
Onboard/Update Processors	manage_processors
View/Update Fees	manage_processors
View GL Accounts	view_processors

Onboard Processor

Create a new payment processor with initial fee configuration.

Endpoint

POST/api/v1/processors

Onboard a new payment processor. This creates the processor record, initializes GL accounts, and sets up the initial fee structure.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}
`Content-Type`	string	Yes	application/json

Response- Created processor with initialized GL accounts

json

{
  "processor": {
    "id": "proc_550e8400-e29b-41d4-a716-446655440000",
    "code": "PAYSTACK",
    "name": "Paystack",
    "category": "debit_card",
    "supportsInflows": true,
    "supportsOutflows": true,
    "settlementBank": true,
    "settlementDelayDays": 1,
    "settlementCurrency": "NGN",
    "status": "active",
    "createdAt": "2024-01-15T09:00:00Z",
    "updatedAt": "2024-01-15T09:00:00Z"
  },
  "glAccounts": {
    "processorId": "proc_550e8400-e29b-41d4-a716-446655440000",
    "code": "PAYSTACK",
    "base": {
      "settlementFloat": {
        "id": "gl_001",
        "accountNumber": "1001001001",
        "name": "Paystack Settlement Float"
      },
      "feeExpense": {
        "id": "gl_002",
        "accountNumber": "5001001001",
        "name": "Paystack Fee Expense"
      },
      "feePayable": {
        "id": "gl_003",
        "accountNumber": "2001001001",
        "name": "Paystack Fee Payable"
      }
    }
  }
}

Request Payload

json

{
  "code": "PAYSTACK",
  "displayName": "Paystack",
  "category": "debit_card",
  "supportsInflows": true,
  "supportsOutflows": true,
  "settlementBank": true,
  "settlementDelayDays": 1,
  "settlementCurrency": "NGN",
  "fees": [
    {
      "eventType": "card_purchase",
      "direction": "inbound",
      "basis": "flat_plus_percent",
      "amount": 10000,
      "percentage": 0.015,
      "maximum": 200000,
      "vatRate": 0.075,
      "currency": "NGN"
    },
    {
      "eventType": "payout",
      "direction": "outbound",
      "basis": "flat",
      "amount": 5000,
      "percentage": 0,
      "vatRate": 0.075,
      "currency": "NGN"
    }
  ]
}

Example Request

bash

curl -X POST "https://api.example.com/api/v1/processors" \
  -H "Authorization: Bearer {admin_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "PAYSTACK",
    "displayName": "Paystack",
    "category": "debit_card",
    "supportsInflows": true,
    "supportsOutflows": true,
    "settlementBank": true,
    "settlementDelayDays": 1,
    "settlementCurrency": "NGN",
    "fees": [
      {
        "eventType": "card_purchase",
        "direction": "inbound",
        "basis": "flat_plus_percent",
        "amount": 10000,
        "percentage": 0.015,
        "maximum": 200000,
        "vatRate": 0.075,
        "currency": "NGN"
      }
    ]
  }'

Fee Basis Types

Basis	Calculation	Example
flat	Fixed amount per transaction	₦100 per transaction
percent	Percentage of transaction amount	1.5% of amount
flat_plus_percent	Fixed amount plus percentage	₦100 + 1.5% (capped at ₦2,000)

List Processors

Retrieve all payment processors with filtering and pagination.

Endpoint

GET/api/v1/processors

List all registered payment processors. Supports filtering by status and category.

Headers

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

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Comma-separated statusesValues: active, inactive
`category`	string	No	Comma-separated categoriesValues: debit_card, virtual_account_inflow, funds_transfer, identity, bills_payment
`sort`	string	No (default: created_at)	Values: created_at, name, code, status
`order`	string	No (default: desc)	Values: asc, desc
`page`	integer	No (default: 1)
`page_size`	integer	No (default: 50)

Response- Paginated list of processors

json

{
  "processors": [
    {
      "id": "proc_550e8400-e29b-41d4-a716-446655440000",
      "code": "PAYSTACK",
      "name": "Paystack",
      "category": "debit_card",
      "supportsInflows": true,
      "supportsOutflows": true,
      "settlementBank": true,
      "settlementDelayDays": 1,
      "settlementCurrency": "NGN",
      "status": "active",
      "createdAt": "2024-01-15T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total": 8
  }
}

Example Requests

bash

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

# Filter by status
curl -X GET "https://api.example.com/api/v1/processors?status=active" \
  -H "Authorization: Bearer {admin_token}"

# Filter by category
curl -X GET "https://api.example.com/api/v1/processors?category=debit_card,funds_transfer" \
  -H "Authorization: Bearer {admin_token}"

# Sort by name ascending
curl -X GET "https://api.example.com/api/v1/processors?sort=name&order=asc" \
  -H "Authorization: Bearer {admin_token}"

Get Processor Details

Retrieve detailed information about a specific processor.

Endpoint

GET/api/v1/processors/{id}

Get comprehensive details for a single processor including all configuration settings.

Headers

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

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	UUID of the processor

Response- Full processor details

json

{
  "id": "proc_550e8400-e29b-41d4-a716-446655440000",
  "code": "PAYSTACK",
  "name": "Paystack",
  "category": "debit_card",
  "supportsInflows": true,
  "supportsOutflows": true,
  "settlementBank": true,
  "settlementDelayDays": 1,
  "settlementCurrency": "NGN",
  "status": "active",
  "createdAt": "2024-01-15T09:00:00Z",
  "updatedAt": "2024-01-20T14:30:00Z"
}

Example Request

bash

curl -X GET "https://api.example.com/api/v1/processors/proc_550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer {admin_token}"

Response Fields

Field	Type	Description
id	string	Unique processor UUID
code	string	Processor code (e.g., PAYSTACK)
name	string	Display name
category	string	Processor category
supportsInflows	boolean	Can receive inbound payments
supportsOutflows	boolean	Can send outbound payments
settlementBank	boolean	Settles via bank transfer
settlementDelayDays	integer	Settlement delay (T+N days)
settlementCurrency	string	Settlement currency code
status	string	Current status (active/inactive)
createdAt	string	Creation timestamp
updatedAt	string	Last update timestamp

Update Processor

Update an existing processor's configuration.

Endpoint

PATCH/api/v1/processors/{id}

Partially update a processor's settings. Only provided fields are updated.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}
`Content-Type`	string	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	UUID of the processor to update

Response- Updated processor object

json

{
  "id": "proc_550e8400-e29b-41d4-a716-446655440000",
  "code": "PAYSTACK",
  "name": "Paystack Updated",
  "status": "inactive",
  "updatedAt": "2024-01-21T10:15:00Z"
}

Request Payload

json

{
  "displayName": "Paystack (Legacy)",
  "status": "inactive",
  "settlementDelayDays": 2,
  "supportsInflows": true,
  "supportsOutflows": false
}

Example Request

bash

# Deactivate a processor
curl -X PATCH "https://api.example.com/api/v1/processors/proc_550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer {admin_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "inactive"
  }'

# Update multiple fields
curl -X PATCH "https://api.example.com/api/v1/processors/proc_550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer {admin_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Paystack (Legacy)",
    "settlementDelayDays": 2,
    "supportsOutflows": false
  }'

Important Notes

Field	Restriction
code	Cannot be changed after creation
category	Cannot be changed after creation
settlementCurrency	Cannot be changed (requires new processor)
status	Setting to inactive stops new transaction routing

Processor Fee Rules

Manage fee configurations for a processor.

Get Processor Fees

GET/api/v1/processors/{id}/fees

Retrieve all fee rules configured for a processor.

Headers

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

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	UUID of the processor

Response- Array of fee rules

json

{
  "fees": [
    {
      "id": "fee_001",
      "eventType": "card_purchase",
      "direction": "inbound",
      "basis": "flat_plus_percent",
      "amount": 10000,
      "percentage": 0.015,
      "minimum": null,
      "maximum": 200000,
      "vatRate": 0.075,
      "currency": "NGN",
      "effectiveFrom": "2024-01-01T00:00:00Z",
      "effectiveTo": null
    },
    {
      "id": "fee_002",
      "eventType": "payout",
      "direction": "outbound",
      "basis": "flat",
      "amount": 5000,
      "percentage": 0,
      "vatRate": 0.075,
      "currency": "NGN",
      "effectiveFrom": "2024-01-01T00:00:00Z"
    }
  ]
}

Update Processor Fees

PUT/api/v1/processors/{id}/fees

Replace all fee rules for a processor. This is an upsert operation - all existing fees are replaced with the provided set.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}
`Content-Type`	string	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	UUID of the processor

Response- Updated fee rules with assigned IDs

json

{
  "fees": [
    {
      "id": "fee_new_001",
      "eventType": "card_purchase",
      "direction": "inbound",
      "basis": "percent",
      "amount": 0,
      "percentage": 0.02,
      "maximum": 250000,
      "vatRate": 0.075,
      "currency": "NGN",
      "effectiveFrom": "2024-01-21T00:00:00Z"
    }
  ]
}

Request Payload (PUT)

Full fee array to replace all existing fees.

json

{
  "fees": [
    {
      "eventType": "card_purchase",
      "direction": "inbound",
      "basis": "flat_plus_percent",
      "amount": 10000,
      "percentage": 0.015,
      "minimum": 5000,
      "maximum": 200000,
      "vatRate": 0.075,
      "currency": "NGN"
    },
    {
      "eventType": "payout",
      "direction": "outbound",
      "basis": "flat",
      "amount": 5000,
      "percentage": 0,
      "vatRate": 0.075,
      "currency": "NGN"
    },
    {
      "eventType": "refund",
      "direction": "outbound",
      "basis": "flat",
      "amount": 0,
      "percentage": 0,
      "vatRate": 0,
      "currency": "NGN"
    }
  ]
}

Example Requests

bash

# Get current fees
curl -X GET "https://api.example.com/api/v1/processors/proc_550e8400-e29b-41d4-a716-446655440000/fees" \
  -H "Authorization: Bearer {admin_token}"

# Update fees (replaces ALL existing)
curl -X PUT "https://api.example.com/api/v1/processors/proc_550e8400-e29b-41d4-a716-446655440000/fees" \
  -H "Authorization: Bearer {admin_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "fees": [
      {
        "eventType": "card_purchase",
        "direction": "inbound",
        "basis": "percent",
        "amount": 0,
        "percentage": 0.02,
        "maximum": 250000,
        "vatRate": 0.075,
        "currency": "NGN"
      },
      {
        "eventType": "payout",
        "direction": "outbound",
        "basis": "flat",
        "amount": 7500,
        "percentage": 0,
        "vatRate": 0.075,
        "currency": "NGN"
      }
    ]
  }'

Fee Rule Fields

Field	Type	Description
id	string	Unique fee rule identifier (read-only)
eventType	string	Transaction type this fee applies to (e.g., card_purchase, payout)
direction	string	Transaction direction: inbound, outbound, or both
basis	string	Fee calculation method: flat, percent, flat_plus_percent
amount	number	Flat fee amount in minor units (kobo/cents)
percentage	number	Percentage fee as decimal (0.015 = 1.5%)
minimum	number \| null	Minimum fee floor
maximum	number \| null	Maximum fee cap
vatRate	number	VAT rate to apply (0.075 = 7.5%)
currency	string	Fee currency code
effectiveFrom	string	When fee becomes effective (read-only)
effectiveTo	string \| null	When fee expires (read-only)

Processor GL Accounts

View general ledger accounts associated with a processor.

Endpoint

GET/api/v1/processors/{id}/gl-accounts

Retrieve the GL account configuration for a processor. GL accounts are used for financial tracking, settlement reconciliation, and fee accounting.

Headers

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

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	UUID of the processor

Query Parameters

Parameter	Type	Required	Description
`tenant_id`	string	No	Optional tenant UUID to include tenant-specific GL overrides

Response- GL account configuration

json

{
  "processorId": "proc_550e8400-e29b-41d4-a716-446655440000",
  "code": "PAYSTACK",
  "base": {
    "settlementFloat": {
      "id": "gl_001",
      "accountNumber": "1001001001",
      "name": "Paystack Settlement Float"
    },
    "feeExpense": {
      "id": "gl_002",
      "accountNumber": "5001001001",
      "name": "Paystack Fee Expense"
    },
    "feePayable": {
      "id": "gl_003",
      "accountNumber": "2001001001",
      "name": "Paystack Fee Payable"
    }
  },
  "tenant": {
    "tenantId": "tnt_f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "principalReceivable": {
      "id": "gl_t001",
      "accountNumber": "1101001001",
      "name": "Tenant Principal Receivable"
    },
    "feePayableOverride": null
  }
}

Example Request

bash

# Get base GL accounts
curl -X GET "https://api.example.com/api/v1/processors/proc_550e8400-e29b-41d4-a716-446655440000/gl-accounts" \
  -H "Authorization: Bearer {admin_token}"

# Include tenant-specific overrides
curl -X GET "https://api.example.com/api/v1/processors/proc_550e8400-e29b-41d4-a716-446655440000/gl-accounts?tenant_id=tnt_f47ac10b" \
  -H "Authorization: Bearer {admin_token}"

GL Account Types

Understanding the different GL accounts and their purposes.

Account	Purpose	Usage
settlementFloat	Holds funds pending settlement from processor	Credits when processor confirms transaction, debits when settled to merchant
feeExpense	Tracks processor fees paid by platform	Debited when fees are charged by processor
feePayable	Liability for fees owed to processor	Credited when fee is incurred, debited when paid
principalReceivable (tenant)	Amount owed to tenant from transactions	Tenant-specific tracking
feePayableOverride (tenant)	Tenant-specific fee payable account	Overrides base feePayable for specific tenant

Settlement Issues

Manage processor settlement exceptions that require attention or intervention.

List Settlement Issues

GET/api/v1/processors/{processorID}/issues

Retrieve settlement exceptions for a specific processor. Issues are flagged when automatic settlement encounters problems that may require manual review.

Headers

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

Path Parameters

Parameter	Type	Required	Description
`processorID`	string	Yes	UUID of the processor

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by issue statusValues: pending, investigating, resolved, escalated
`type`	string	No	Filter by issue typeValues: amount_mismatch, missing_transaction, duplicate, timeout, rejected
`from`	string	No	Start date filter (RFC3339)
`to`	string	No	End date filter (RFC3339)
`limit`	integer	No (default: 50)
`offset`	integer	No (default: 0)

Response- Paginated list of settlement issues

json

{
  "data": [
    {
      "id": "exc_550e8400-e29b-41d4-a716-446655440000",
      "processorId": "proc_abc123",
      "type": "amount_mismatch",
      "status": "pending",
      "description": "Settlement amount differs from expected by ₦5,000",
      "expectedAmount": 1500000,
      "actualAmount": 1495000,
      "currency": "NGN",
      "settlementReference": "STL_20240120_001",
      "transactionIds": [
        "txn_001",
        "txn_002",
        "txn_003"
      ],
      "metadata": {
        "processor_reference": "PSK_STL_abc123"
      },
      "retryCount": 0,
      "maxRetries": 3,
      "createdAt": "2024-01-20T10:00:00Z",
      "updatedAt": "2024-01-20T10:00:00Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total_count": 15
  }
}

Update Settlement Issue

PATCH/api/v1/processors/issues/{exceptionID}

Update the status or add notes to a settlement issue.

Headers

Parameter	Type	Required	Description
`Authorization`	string	Yes	Bearer {admin_access_token}
`Content-Type`	string	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
`exceptionID`	string	Yes	UUID of the settlement issue

Response- Updated issue object

json

{
  "id": "exc_550e8400-e29b-41d4-a716-446655440000",
  "status": "investigating",
  "notes": "Investigating with processor support team",
  "assignedTo": "admin_user_123",
  "updatedAt": "2024-01-20T11:30:00Z"
}

Request Payload (Update Issue)

json

{
  "status": "investigating",
  "notes": "Checking with processor support team - ticket #12345",
  "assignedTo": "admin_user_123"
}

Request Payload (Resolve Issue)

json

{
  "status": "resolved",
  "resolution": "manual_adjustment",
  "notes": "Adjusted settlement amount per processor confirmation. Discrepancy due to refund processed after settlement window."
}

Retry Settlement Issue

POST/api/v1/processors/issues/{exceptionID}/retry

Retry automatic settlement for a failed issue. Only available for issues that haven't exceeded max retries.

Headers

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

Path Parameters

Parameter	Type	Required	Description
`exceptionID`	string	Yes	UUID of the settlement issue

Response- Retry result

json

{
  "id": "exc_550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "retryCount": 1,
  "nextRetryAt": "2024-01-20T12:00:00Z",
  "message": "Settlement retry queued successfully"
}

Example Requests

bash

# List pending issues for a processor
curl -X GET "https://api.example.com/api/v1/processors/proc_abc123/issues?status=pending" \
  -H "Authorization: Bearer {admin_token}"

# Mark issue as investigating
curl -X PATCH "https://api.example.com/api/v1/processors/issues/exc_550e8400" \
  -H "Authorization: Bearer {admin_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "investigating",
    "notes": "Checking with processor support",
    "assignedTo": "admin_user_123"
  }'

# Retry a failed settlement
curl -X POST "https://api.example.com/api/v1/processors/issues/exc_550e8400/retry" \
  -H "Authorization: Bearer {admin_token}"

# Resolve an issue
curl -X PATCH "https://api.example.com/api/v1/processors/issues/exc_550e8400" \
  -H "Authorization: Bearer {admin_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "resolved",
    "resolution": "manual_adjustment",
    "notes": "Adjusted settlement amount per processor confirmation"
  }'

Issue Types

Type	Description	Common Resolution
amount_mismatch	Settlement amount differs from expected total	Reconcile with processor, adjust if confirmed
missing_transaction	Expected transaction not in settlement file	Check processor logs, may need manual credit
duplicate	Same transaction appears multiple times	Verify with processor, reverse if confirmed
timeout	Settlement request timed out	Retry after processor systems are stable
rejected	Processor rejected the settlement request	Review rejection reason, fix and retry

Webhook Notifications

View and manage stored processor webhook notifications.

List Webhook Notifications

GET/api/v1/admin/webhook-notifications

List stored processor webhook notifications. Webhooks are stored for audit, debugging, and replay purposes.

Headers

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

Query Parameters

Parameter	Type	Required	Description
`provider`	string	No	Filter by webhook provider
`status`	string	No	Comma-separated statusesValues: pending, processing, processed, failed, duplicate, held_blocked
`processor_code`	string	No	Filter by processor code (e.g., AELLAINFLOW, GRUPP)
`flow_type`	string	No	Filter by flow type
`channel`	string	No	Filter by channel
`tenant_id`	string	No	Filter by tenant UUID
`search`	string	No	Search by notification ID or idempotency key
`from`	string	No	Start date filter (RFC3339, filters on received_at)
`to`	string	No	End date filter (RFC3339)
`limit`	integer	No (default: 50)	Page size (max 200)
`offset`	integer	No (default: 0)

Response- Paginated list of webhook notifications

json

{
  "data": [
    {
      "id": "wh_550e8400-e29b-41d4-a716-446655440000",
      "provider": "paystack",
      "event_type": "charge.success",
      "status": "processed",
      "processor_code": "PAYSTACK",
      "flow_type": "inflow",
      "channel": "card",
      "tenant_id": "tnt_f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "processor_id": "proc_abc123",
      "terminal_id": "2057TID001",
      "pos_card_transaction_id": "txn_xyz789",
      "error_message": null,
      "retry_count": 0,
      "received_at": "2024-01-20T14:30:00Z",
      "processed_at": "2024-01-20T14:30:02Z",
      "webhook_timestamp": "2024-01-20T14:29:58Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total_count": 1250
  }
}

Get Webhook Notification Detail

GET/api/v1/admin/webhook-notifications/{id}

Retrieve detailed information about a specific webhook notification including raw payload data.

Headers

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

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	UUID of the webhook notification

Query Parameters

Parameter	Type	Required	Description
`include_raw_body`	boolean	No (default: false)	Include base64-encoded raw request body

Response- Detailed webhook notification

json

{
  "id": "wh_550e8400-e29b-41d4-a716-446655440000",
  "provider": "paystack",
  "event_type": "charge.success",
  "status": "processed",
  "processor_code": "PAYSTACK",
  "flow_type": "inflow",
  "channel": "card",
  "tenant_id": "tnt_f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "idempotency_key": "IDK_20240120_143000_abc123",
  "raw_payload": {
    "event": "charge.success",
    "data": {
      "reference": "REF123456",
      "amount": 1500000,
      "currency": "NGN",
      "status": "success"
    }
  },
  "headers": {
    "x-paystack-signature": "sha512=abc123...",
    "content-type": "application/json"
  },
  "raw_body": "eyJldmVudCI6ImNoYXJnZS5zdWNjZXNzIi4uLn0=",
  "error_message": null,
  "retry_count": 0,
  "received_at": "2024-01-20T14:30:00Z",
  "processed_at": "2024-01-20T14:30:02Z"
}

Example Requests

bash

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

# Filter by processor and status
curl -X GET "https://api.example.com/api/v1/admin/webhook-notifications?processor_code=PAYSTACK&status=failed" \
  -H "Authorization: Bearer {admin_token}"

# Filter by date range
curl -X GET "https://api.example.com/api/v1/admin/webhook-notifications?from=2024-01-20T00:00:00Z&to=2024-01-20T23:59:59Z" \
  -H "Authorization: Bearer {admin_token}"

# Get notification detail with raw body
curl -X GET "https://api.example.com/api/v1/admin/webhook-notifications/wh_550e8400?include_raw_body=true" \
  -H "Authorization: Bearer {admin_token}"

Notification Statuses

Status	Description	Action Required
pending	Received but not yet processed	Will be processed automatically
processing	Currently being processed	Wait for completion
processed	Successfully processed	No action required
failed	Processing failed	Investigate error_message, may need retry
duplicate	Duplicate notification (idempotency)	No action - already processed
held_blocked	Held due to blocking condition	Review and release or discard

Common Processor Codes

Code	Provider	Description
AELLAINFLOW	Aella	Aella inbound transactions
AELLAOUTFLOW	Aella	Aella outbound transactions
GRUPP	Grupp	Grupp payment processor
PAYSTACK	Paystack	Paystack card transactions
FLUTTERWAVE	Flutterwave	Flutterwave transactions

Best Practices

Recommended patterns for managing processors effectively.

Processor Lifecycle

Stage	Actions	Considerations
Onboard	POST /processors with fees	Verify fee structure before going live
Test	Process test transactions	Use inactive status during testing
Activate	PATCH status to active	Ensure all GL accounts are configured
Monitor	Review webhook notifications and issues	Set up alerts for failed webhooks
Maintain	Update fees as needed	Document all fee changes
Decommission	PATCH status to inactive	Wait for pending settlements to complete

Settlement Issue Management

Practice	Recommendation
Regular Review	Check pending issues daily
Assignment	Assign issues to specific team members
Escalation	Escalate issues older than 48 hours
Documentation	Add detailed notes for all investigations
Retry Strategy	Wait for processor confirmation before retrying

Webhook Monitoring

Key metrics to monitor for healthy webhook processing.

Metric	Alert Threshold	Action
Failed webhook rate	> 5%	Check processor connectivity
Processing latency	> 30 seconds	Review processing queue
Duplicate rate	> 10%	May indicate processor retry issues
Held/blocked count	> 100	Review blocking conditions

Processor Management

Overview

What is a Processor?

Processor Categories

Processor Status

Required Permissions

Onboard Processor

Endpoint

Request Payload

Example Request

Fee Basis Types

List Processors

Endpoint

Example Requests

Get Processor Details

Endpoint

Example Request

Response Fields

Update Processor

Endpoint

Request Payload

Example Request

Important Notes

Processor Fee Rules

Get Processor Fees

Update Processor Fees

Request Payload (PUT)

Example Requests

Fee Rule Fields

Processor GL Accounts

Endpoint

Example Request

GL Account Types

Settlement Issues

List Settlement Issues

Update Settlement Issue

Request Payload (Update Issue)

Request Payload (Resolve Issue)

Retry Settlement Issue

Example Requests

Issue Types

Webhook Notifications

List Webhook Notifications

Get Webhook Notification Detail

Example Requests

Notification Statuses

Common Processor Codes

Best Practices

Processor Lifecycle

Settlement Issue Management

Webhook Monitoring