Search by Reference

Overview

The Search by Reference endpoint allows merchants to search and retrieve complete transaction details using a transaction reference. This provides more comprehensive information than the requery endpoint and is ideal for detailed transaction lookups, customer support, and administrative operations.

Endpoint Details

Endpoint: GET /api/v1/transactions/in/search-transaction/{reference}

Authentication: Bearer token (merchant_secret_key) in Authorization header

Path Parameter: reference (String) - Transaction reference (e.g., PISL2408200000000035)

Code Snippets

JavaScript

const reference = "PISL2408200000000035";
const url = `https://ags.payislands.com/api/v1/transactions/in/search-transaction/${reference}`;

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

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

TypeScript

const reference = "PISL2408200000000035";
const url = `https://ags.payislands.com/api/v1/transactions/in/search-transaction/${reference}`;

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

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

Java

import okhttp3.*;
import java.io.IOException;

public class SearchTransactionByReference {
  public static void main(String[] args) throws IOException {
    String reference = "PISL2408200000000035";
    String url = "https://ags.payislands.com/api/v1/transactions/in/search-transaction/" + reference;
    String merchantSecretKey = System.getenv("MERCHANT_SECRET_KEY");

    OkHttpClient client = new OkHttpClient();
    Request request = new Request.Builder()
      .url(url)
      .get()
      .addHeader("Authorization", "Bearer " + merchantSecretKey)
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

Python

import os
import requests

reference = "PISL2408200000000035"
url = f"https://ags.payislands.com/api/v1/transactions/in/search-transaction/{reference}"
headers = {"Authorization": f"Bearer {os.environ['MERCHANT_SECRET_KEY']}"}

resp = requests.get(url, headers=headers, timeout=30)
print(resp.status_code, resp.text)

C#

using System.Net.Http;
using System.Net.Http.Headers;

var reference = "PISL2408200000000035";
var url = $"https://ags.payislands.com/api/v1/transactions/in/search-transaction/{reference}";
var merchantSecretKey = Environment.GetEnvironmentVariable("MERCHANT_SECRET_KEY");

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", merchantSecretKey);

var resp = await http.GetAsync(url);
var body = await resp.Content.ReadAsStringAsync();
Console.WriteLine(body);

Response Structure

Success Response (200 OK)

{
  "status": true,
  "message": "Transaction Found",
  "data": {
    "id": 35,
    "reference": "PISL2408200000000035",
    "authorization_url": "https://checkout.payislands.com/?reference=PISL2408200000000035",
    "amount": "3000",
    "amount_paid": "3051",
    "amount_to_be_paid": "3051",
    "transaction_fee": "51",
    "payment_status": "paid",
    "payment_channel": "card",
    "payment_type": "card",
    "paid_at": "2024-08-20T11:43:57.000Z",
    "created_at": "2024-08-20T10:42:39.133Z",
    "gateway_reference": "474714340",
    "transaction_split_breakdown": [
      {
        "share": 3000,
        "bank_id": 50,
        "account_code": "PSL_SA_16LkXxzoMIffQmtaeWhB0ei",
        "account_name": "Dere Sunday Toluwani",
        "account_number": "2061777014"
      }
    ],
    "payment_item": { /* complete payment item details */ },
    "customer": { /* complete customer details */ },
    "business": { /* business details */ },
    "meta_data": null
  },
  "statusCode": 200
}

Failure Response

Returns standard error format when transaction not found.

Key Differences from Requery Endpoint

More Comprehensive Data

Search returns complete transaction object with all fields, while requery returns minimal status information.

Additional Fields Included

Transaction Timestamps:

• created_at - When transaction was initialized
• paid_at - When payment was completed
• initiation_time - When customer started payment

Payment Details:

• authorization_url - Payment page link
• payment_channel - Payment method used
• payment_type - Specific payment type
• gateway_reference - External processor reference
• no_of_attempts - Number of payment attempts

Financial Breakdown:

• amount - Base amount
• amount_paid - Total paid including fees
• amount_to_be_paid - Expected total
• transaction_fee - Processing fee

Settlement Information:

• transaction_split_code - Revenue split configuration
• transaction_split_breakdown - Detailed fund distribution with account details

Additional Context:

• meta_data - Custom transaction metadata
• core_service_business_id - Internal business ID
• business_merchant_id - Merchant account ID
• customer_id - Internal customer ID
• customer_tag - Unique customer identifier

Primary Use Cases

1. Detailed Customer Support

Retrieve all transaction information for comprehensive customer assistance including payment method, attempts, timeline, and settlement details.

2. Transaction Investigation

Access complete transaction history for fraud investigation, dispute resolution, or payment troubleshooting with gateway references and attempt counts.

3. Settlement Verification

Verify fund distribution across settlement accounts with complete breakdown including bank details and account numbers.

4. Administrative Operations

Retrieve full transaction context for reporting, auditing, or manual processing with all metadata and business information.

5. Payment Link Retrieval

Get authorization URL for sending payment reminders or allowing customers to retry failed payments.

6. Integration Debugging

Access complete transaction data for troubleshooting integration issues with all gateway responses and references.

Key Response Fields

Core Transaction Data

• id: Internal transaction identifier
• reference: Unique transaction reference
• authorization_url: Payment page link (null for some channels)
• gateway_reference: External processor reference

Financial Information

• amount: Base transaction amount
• amount_paid: Actual amount received
• amount_to_be_paid: Total expected (amount + fees)
• transaction_fee: Processing charges

Status and Timeline

• payment_status: Current status (pending/paid/failed/cancelled/expired)
• created_at: Initialization timestamp
• paid_at: Completion timestamp (null if not paid)
• initiation_time: When payment process started
• no_of_attempts: Payment retry count

Payment Method

• payment_channel: Method used (card/bank/wallet/bank-transfer)
• payment_type: Specific payment type classification
• gateway_used: Payment processor name

Customer Information

• customer_id: Internal customer ID
• customer_tag: Unique customer identifier
• customer_email: Email address
• customer_phone_number: Phone number
• customer: Complete customer object with name

Business Information

• core_service_business_id: Internal business ID
• business_merchant_id: Merchant account identifier
• business: Business object with name

Settlement Details

• transaction_split_code: Split configuration ID
• transaction_split_breakdown: Array with distribution details:
  • share: Amount to this account
  • bank_id: Bank identifier
  • bank_name: Bank name
  • account_code: Settlement account code
  • account_name: Account holder name
  • account_number: Bank account number

Payment Item

• Complete payment item object with product/service details, pricing, categories, and configuration

Additional Data

• meta_data: Custom metadata object
• Transaction type, gateway responses, and other contextual information

When to Use Search vs Requery

Use Search Endpoint When:

• Need complete transaction details for support
• Require settlement breakdown information
• Need authorization URL for payment retry
• Investigating transaction issues
• Verifying fund distribution
• Accessing gateway references
• Need customer identification details
• Require full transaction timeline

Use Requery Endpoint When:

• Only need current payment status
• Quick status check for automation
• Webhook backup verification
• Polling for status changes
• Simple status display to customer
• Need minimal data transfer
• Building real-time status monitors

Best Practices

Data Usage

• Use search for one-time detailed lookups
• Don't repeatedly search for same reference
• Cache search results appropriately
• Extract only needed fields for display

Performance

• Search returns more data than requery (larger payload)
• Use requery for frequent status checks
• Implement caching for repeated searches
• Consider data transfer costs

Security

• Limit search access to authorized users
• Log all search operations for audit
• Don't expose full data to end customers
• Mask sensitive information when displaying

Error Handling

• Handle transaction not found gracefully
• Verify reference format before searching
• Implement retry logic for network errors
• Log failed searches for monitoring

Integration Patterns

• Use search for admin interfaces
• Use search for detailed transaction views
• Combine with transaction histories for bulk operations
• Use authorization_url for payment reminders

Common Scenarios

Customer Support Lookup

Support agents search by reference to view complete transaction details, payment methods, attempts, and settlement information for comprehensive assistance.

Payment Link Resend

Retrieve authorization_url from search results to resend the payment link to the customer for pending or failed transactions.

Settlement Reconciliation

Use transaction_split_breakdown to verify funds were distributed correctly across settlement accounts with complete banking details.

Fraud Investigation

Access no_of_attempts, payment timeline, gateway_reference, and customer details to investigate suspicious transaction patterns.

Dispute Resolution

Retrieve the complete transaction record, including gateway_reference, payment_channel, amounts, and timestamps for dispute documentation.