Transactions

View payment transaction history.

List Transactions

Get a paginated list of transactions.

Endpoint: GET /v1/pay/transactions

Authentication: Required

Query Parameters:

Parameter	Type	Required	Description
`offset`	integer	No	Number of items to skip
`limit`	integer	No	Maximum number of items to return
`status`	string	No	Filter by status
`start_date`	string	No	Filter transactions after this date (ISO 8601)
`end_date`	string	No	Filter transactions before this date (ISO 8601)

Transaction Statuses:

pending - Transaction initiated, awaiting processing

processing - Transaction being processed by payment provider

completed - Transaction completed successfully

failed - Transaction failed

cancelled - Transaction cancelled

expired - Transaction expired before completion

refunded - Transaction fully refunded

partially_refunded - Transaction partially refunded

Payment Methods:

wave - Wave Mobile Money

afrimoney - Afrimoney Mobile Money

card - card (via payment gateway)

Example:

HTTP

TypeScript

Python

Success Response (200):

{
  "data": {
    "items": [
      {
        "id": "txn_abc123",
        "payment_session_id": "ps_xyz789",
        "object_type": "payment_link",
        "object_id": "pl_def456",
        "organization_id": "org_test123",
        "customer_id": "cus_ghi789",
        "amount": "100.00",
        "fee": "2.50",
        "net_amount": "97.50",
        "currency": "GMD",
        "payment_method": "wave",
        "payment_method_transaction_id": "wave_txn_123",
        "status": "completed",
        "customer_email": "customer@example.com",
        "customer_name": "John Doe",
        "customer_phone": "+2207654321",
        "payment_phone": "+2207654321",
        "mode": "test",
        "livemode": false,
        "initiated_at": "2024-01-15T10:30:00Z",
        "processing_at": "2024-01-15T10:30:05Z",
        "completed_at": "2024-01-15T10:31:00Z",
        "refunded_amount": "0.00",
        "attempt_count": 1,
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:31:00Z"
      }
    ],
    "count": 1,
    "offset": 0,
    "limit": 20
  }
}

INFO

Mode Filtering: Transactions are automatically filtered by your API key mode. Test API keys only see test transactions, live API keys only see live transactions.

Get Transaction

Get details of a specific transaction.

Endpoint: GET /v1/pay/transactions/{id}

Authentication: Required

Example:

HTTP

TypeScript

Python

Success Response (200):

{
  "data": {
    "id": "txn_abc123",
    "payment_session_id": "ps_xyz789",
    "object_type": "payment_link",
    "object_id": "pl_def456",
    "organization_id": "org_test123",
    "customer_id": "cus_ghi789",
    "amount": "100.00",
    "fee": "2.50",
    "net_amount": "97.50",
    "currency": "GMD",
    "payment_method": "wave",
    "payment_method_transaction_id": "wave_txn_123",
    "status": "completed",
    "customer_email": "customer@example.com",
    "customer_name": "John Doe",
    "customer_phone": "+2207654321",
    "payment_phone": "+2207654321",
    "payment_details": {
      "provider": "wave",
      "reference": "wave_txn_123"
    },
    "mode": "test",
    "livemode": false,
    "initiated_at": "2024-01-15T10:30:00Z",
    "processing_at": "2024-01-15T10:30:05Z",
    "completed_at": "2024-01-15T10:31:00Z",
    "failed_at": null,
    "refunded_amount": "0.00",
    "failure_reason": null,
    "state_transitions": [
      {
        "status": "pending",
        "timestamp": "2024-01-15T10:30:00Z"
      },
      {
        "status": "processing",
        "timestamp": "2024-01-15T10:30:05Z"
      },
      {
        "status": "completed",
        "timestamp": "2024-01-15T10:31:00Z"
      }
    ],
    "payment_method_response": {
      "status": "success",
      "provider_reference": "wave_txn_123"
    },
    "attempt_count": 1,
    "metadata": {},
    "processing_type": "async",
    "recording_source": "payment_session",
    "recorded_by": null,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:31:00Z"
  }
}

Transaction Fields:

Field	Type	Description
`id`	string	Transaction ID
`payment_session_id`	string	Associated payment session ID
`object_type`	string	Type of object (`payment_link`, `invoice`, `checkout`, `donation`)
`object_id`	string	ID of the related payment object
`organization_id`	string	Organization ID
`customer_id`	string	Customer ID
`amount`	string	Transaction amount
`fee`	string	Payment provider fee
`net_amount`	string	Net amount after fees
`currency`	string	Currency code
`payment_method`	string	Payment method (`wave`, `afrimoney`, `card`)
`payment_method_transaction_id`	string	Transaction ID from payment provider
`status`	string	Transaction status
`customer_email`	string	Customer email
`customer_name`	string	Customer name
`customer_phone`	string	Customer phone number
`payment_phone`	string	Phone number used for payment
`payment_details`	object	Additional payment method details
`mode`	string	Payment mode (`test`, `live`)
`livemode`	boolean	Whether transaction is in live mode
`initiated_at`	string	When transaction was initiated (ISO 8601)
`processing_at`	string	When transaction started processing (ISO 8601)
`completed_at`	string	When transaction completed (ISO 8601)
`failed_at`	string	When transaction failed (ISO 8601)
`refunded_amount`	string	Amount refunded
`failure_reason`	string	Reason for failure
`state_transitions`	array	History of status changes
`payment_method_response`	object	Raw response from payment provider
`attempt_count`	integer	Number of payment attempts
`metadata`	object	Additional metadata
`processing_type`	string	Type of processing (`sync`, `async`)
`recording_source`	string	Source of transaction record
`recorded_by`	string	User who recorded the transaction
`created_at`	string	Creation timestamp (ISO 8601)
`updated_at`	string	Last update timestamp (ISO 8601)

TIP

State Transitions: The state_transitions array provides a complete audit trail of all status changes with timestamps, useful for debugging payment issues.

Transactions

List Transactions#

Get Transaction#

List Transactions

Get Transaction