Skip to main content

Transaction History

Overview​

The Transaction History endpoint provides comprehensive access to all past transactions for a merchant account. This endpoint is essential for transaction monitoring, reconciliation, reporting, and customer support operations.

Endpoint Details​

Endpoint: GET /api/v1/transactions/in/transaction-histories

Purpose: Retrieves a complete list of all historical transactions with detailed information including payment status, customer data, settlement breakdowns, and gateway responses

Authentication: Requires Bearer token (merchant_secret_key) in Authorisation header

Request Structure​

Method: GET

Headers:

  • Authorization: Bearer {merchant_secret_key}

Query Parameters: None (returns all transactions)

  • payment_status(paid, pending, failed)
  • payment_method(card, bank,bank-transfer)
  • reference
  • start_date
  • end_date

Code Snippets​

const baseUrl = "https://ags.payislands.com/api/v1/transactions/in/transaction-histories";

// Example with optional filters:
const url = new URL(baseUrl);
url.searchParams.set("payment_status", "paid");
url.searchParams.set("start_date", "2024-01-01");
url.searchParams.set("end_date", "2024-12-31");

const res = await fetch(url.toString(), {
  headers: { Authorization: `Bearer ${process.env.MERCHANT_SECRET_KEY}` },
});

const json = await res.json();
console.log(json);

Response Structure​

Success Response (200 OK)​

{
  "status": true,
  "message": "",
  "data": [
    {
      "id": 238,
      "amount": "1000",
      "payment_status": "pending",
      "reference": "PISL2509280000000238",
      // ... additional fields
    }
  ],
  "statusCode": 200
}

Transaction Object Fields​

Core Transaction Information​

id

  • Type: Integer
  • Purpose: Internal transaction ID
  • Usage: Database references, internal tracking
  • Note: Not exposed to customers; use reference for customer-facing operations

reference

  • Type: String
  • Purpose: Unique transaction identifier
  • Example: "PISL2509280000000238"
  • Critical Use Cases:
    • Transaction lookup and verification
    • Customer support queries

amount

  • Type: String (numeric)
  • Purpose: Original transaction amount (base amount)
  • Format: In smallest currency unit (kobo/cents)
  • Example: "1000" = ₦10.00

amount_paid

  • Type: String (numeric)
  • Purpose: Actual amount paid including fees
  • Note: May be "0" for pending transactions
  • Example: "1010" = ₦10.10 (includes transaction fee)

transaction_fee

  • Type: String (numeric)
  • Purpose: Payment processing fee
  • Note: May vary by payment channel and amount
  • Example: "10" = ₦0.10 transaction fee

Payment Status Information​

payment_status

  • Type: String
  • Purpose: Current transaction status
  • Possible Values:
    • "pending" - Awaiting payment
    • "paid" - Completed
    • "failed" - Payment failed

Status Meanings:

pending

  • Payment has been initialised but not completed
  • The customer may still complete payment
  • Can transition to paid, or fail

paid

  • Payment successfully processed
  • Funds received and verified
  • Settlement initiated or completed
  • Final successful state

failed

  • Payment attempt was unsuccessful
  • No funds received
  • The customer may retry with a new transaction

paid_at

  • Type: String (ISO 8601 datetime) or null
  • Purpose: Timestamp when payment was completed
  • Example: "2024-09-25T15:03:19.684Z"
  • Note: Null for non-paid transactions

created_at

  • Type: String (ISO 8601 datetime)
  • Purpose: Transaction initialisation timestamp
  • Usage: Age calculation, reporting, filtering

initiation_time

  • the Type: String (ISO 8601 datetime) or null
  • Purpose: When the payment process was started (the customer began payment)
  • Note: Different from created_at; indicates customer engagement

Payment Channel Information​

payment_channel

  • Type: String or null

  • Purpose: Payment method used or selected

  • Values:

    • "card" - Card payment
    • "bank" - Bank transfer
    • "bank-transfer" - Direct bank transfer

payment_type

  • Type: String or null
  • Purpose: More specific payment method classification
  • Note: Often matches payment_channel but can provide additional detail

authorization_url

  • Type: String (URL) or null
  • Purpose: Payment page URL for the customer
  • Example: "https://checkout-demo.payislands.com/?reference=PISL2509280000000238"
  • Usage:
    • Redirect customers to complete payment
    • Resend payment links
    • Customer support assistance

no_of_attempts

  • Type: Integer
  • Purpose: Number of payment attempts made
  • Usage:
    • Fraud detection (excessive attempts)
    • User experience optimisation
    • Success rate analysis
  • Note: Multiple attempts may indicate payment issues

Example Gateway Response:

{
  "id": 51,
  "amount": 1010,
  "status": "success",
  "created_at": "2025-09-25T15:03:19.626Z",
  "transaction_type": "debit",
  "user_wallet_id": 1,
  "current_balance": 400706.01,
  "previous_balance": 401716.01,
  "transaction_reference": "PISL2509250000000235"
}

Customer Information​

customer_id

  • Type: Integer
  • Purpose: Internal customer identifier
  • Usage: Customer relationship management

customer_tag

  • Type: String
  • Format: Cus_ + alphanumeric string
  • Purpose: Unique customer identifier
  • Example: "Cus_208FZen2hmLqKTcTlj8hiV1PdR"

customer_email

  • Type: String
  • Purpose: Customer email address
  • Usage: Receipts, notifications, support

customer_phone_number

  • Type: String
  • Purpose: Customer phone number
  • Usage: SMS notifications, verification

customer (Object)

  • Type: Object
  • Contains:
    • id: Customer ID
    • customer_tag: Customer tag
    • first_name: Customer first name
    • last_name: Customer last name
  • Purpose: Complete customer details for display

Business and Merchant Information​

core_service_business_id

  • Type: Integer
  • Purpose: Internal business identifier

business_merchant_id

  • Type: String
  • Purpose: Merchant account identifier
  • Example: "0000000002"

business (Object)

  • Contains: business_name
  • Purpose: Merchant business name
  • Example: {"business_name": "Dune Imperium"}

Payment Item Information​

payment_item_id

  • Type: Integer
  • Purpose: Identifies the product/service purchased
  • Usage: Product analytics, inventory management

payment_item (Object)

  • Type: Complete payment item object
  • Contains: All payment item details including:
    • Name and description
    • Amount configuration
    • Form data requirements
    • Category information
    • Split code configuration
  • Purpose: Full context of what was purchased

Settlement and Split Information​

transaction_split_code

  • Type: String
  • Purpose: Revenue sharing configuration identifier
  • Example: "TS_PSL2v2CwhVQoGCG8cdf9CoEOiGn"

transaction_split_breakdown

  • Type: Array of objects or null
  • Purpose: Details of how funds were/will be distributed
  • Present: Only for paid transactions with splits
  • Structure:
[
  {
    "share": 1000,
    "bank_id": 5,
    "bank_name": "Access Bank",
    "account_code": "PSL_SA_25c1GAdZ8QscAazOOci8nph",
    "account_name": "ABDULQUDDUUS LUQMAN BABALOLA",
    "account_number": "0817064402"
  }
]

Split Breakdown Fields:

  • share: Amount allocated to this account
  • bank_id: Bank identifier
  • bank_name: Bank name
  • account_code: PayIslands settlement account code
  • account_name: Account holder name
  • account_number: Bank account number

Bank Transfer Specific Fields​

payment_bank_name

  • Type: String or null
  • Purpose: Bank name for bank transfer payments
  • Example: "9PSB"
  • Present: Only for bank-transfer channel

payment_account_number

  • Type: String or null
  • Purpose: Virtual account number for transfer
  • Example: "5031490455"
  • Usage: Customer transfers to this account

payment_account_name

  • Type: String or null
  • Purpose: Account name for verification
  • Example: "Dune Imperium"

payment_expiry_date

  • Type: String (ISO 8601 datetime) or null
  • Purpose: When virtual account expires
  • Example: "2025-08-30T09:00:33.887Z"
  • Critical: Transactions cannot complete after expiry

duration

  • Type: Integer or null
  • Purpose: Payment window duration (likely in days)
  • Example: 2
  • Usage: Calculating expiry times

Additional Fields​

meta_data

  • Type: Object or null
  • Purpose: Custom transaction metadata
  • Usage: Store additional context, custom fields, and integration data
  • Note: Structure varies based on implementation

Use Cases and Implementation Patterns​

1. Transaction Monitoring Dashboard​

Purpose: Real-time overview of transaction activity

Implementation:

// Fetch recent transactions
const response = await fetch('/api/v1/transactions/in/transaction-histories', {
  headers: {
    'Authorization': 'Bearer ' + merchantSecretKey
  }
});

const { data } = await response.json();

// Calculate metrics
const metrics = {
  totalTransactions: data.length,
  pendingCount: data.filter(t => t.payment_status === 'pending').length,
  paidCount: data.filter(t => t.payment_status === 'paid').length,
  totalRevenue: data
    .filter(t => t.payment_status === 'paid')
    .reduce((sum, t) => sum + parseFloat(t.amount), 0)
};

2. Transaction Reconciliation​

Purpose: Match payments with bank settlements

Key Fields:

  • reference: Primary matching key
  • amount_paid: Compare with bank credit
  • paid_at: Match settlement dates
  • transaction_split_breakdown: Verify fund distribution
  • gateway_reference: Cross-reference with the processor

Process:

  1. Export paid transactions for date range
  2. Match with bank statement using amount and reference
  3. Verify split amounts match settlements
  4. Flag discrepancies for investigation

3. Customer Support​

Purpose: Quickly locate and verify customer transactions

Search Patterns:

// By reference
const findByReference = (transactions, ref) => 
  transactions.find(t => t.reference === ref);

// By customer email
const findByEmail = (transactions, email) => 
  transactions.filter(t => t.customer_email === email);

// By phone number
const findByPhone = (transactions, phone) => 
  transactions.filter(t => t.customer_phone_number === phone);

Support Information to Provide:

  • Payment status and timestamp
  • Amount and fees
  • Payment method used
  • Authorisation URL (for retries)
  • Gateway reference (for disputes)
async function fetchTransactionHistories() {
  try {
    const response = await fetch('/api/v1/transactions/in/transaction-histories', {
      headers: {
        'Authorization': 'Bearer ' + merchantSecretKey
      }
    });
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    
    const result = await response.json();
    
    if (!result.status) {
      throw new Error(result.message || 'Failed to fetch transactions');
    }
    
    return result.data;
    
  } catch (error) {
    console.error('Transaction fetch error:', error);
    
    // Implement retry logic
    if (error.message.includes('network') || error.message.includes('timeout')) {
      return retryWithBackoff(() => fetchTransactionHistories());
    }
    
    throw error;
  }
}

Common Questions​

Q: How far back does transaction history go? A: The endpoint returns all historical transactions. Implement date filtering on your end.

Q: Is there a limit on the number of transactions returned? A: Check with PayIslands support. Implement pagination to handle large datasets.

Q: How often is the data updated? A: Real-time. Transactions appear immediately after initialization.

Q: Can I filter by date range in the API call? A: Not currently. Implement client-side filtering or request this feature.

Q: What if a transaction is missing? A: Use the search endpoint or check if transaction was initialized under a different merchant account.

Q: How do I handle timezone differences? A: All timestamps are in UTC (ISO 8601 format). Convert to local timezone for display.

Q: Can I modify transaction records? A: No. Transactions are immutable. Contact support for corrections.