Skip to main content

Transaction Verification

Overview​

The Requery Transaction endpoint retrieves the current status of a specific transaction using its unique reference. Essential for verifying payment completion, handling webhook failures, and providing status updates to customers.

Endpoint Details​

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

Authentication: Bearer token (merchant_secret_key) in Authorisation header

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

Code Snippets​

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

const res = await fetch(url, {
  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": {
    "reference": "PISL2509280000000238",
    "payment_status": "pending",
    "amount": "1000",
    "payment_item": { /* complete payment item object */ },
    "customer": {
      "id": 46,
      "customer_tag": "Cus_208FZen2hmLqKTcTlj8hiV1PdR",
      "first_name": "Sunday",
      "last_name": "Dere"
    },
    "business": {
      "business_name": "Dune Imperium"
    }
  },
  "statusCode": 200
}

Failure Response (400 Bad Request)​

{
  "status": false,
  "message": "transaction not found",
  "data": null,
  "statusCode": 400
}

Key Response Fields​

reference​

  • Confirms the queried transaction reference
  • Use for verification and logging

payment_status​

  • Critical field - Current transaction state
  • Values:
    • pending - Payment not completed
    • paid - Successfully processed
    • failed - Payment attempt failed
    • cancelled - Transaction cancelled
    • expired - Payment window expired

amount​

  • Transaction amount in smallest currency unit (kobo/cents)
  • String format: "1000" = ₦10.00

payment_item​

  • Complete payment item object with product/service details
  • Includes name, pricing, categories, form requirements, and split configuration

customer​

  • Customer identification information
  • Contains ID, customer tag, and name

business​

  • Merchant business information
  • Contains business name

Primary Use Cases​

1. Webhook Failure Recovery​

Query transaction status when webhook notification fails or is delayed. Wait reasonable time (5-10 minutes) before querying.

2. Real-Time Status Updates​

Provide live payment status to customers waiting on payment page. Use intelligent polling with exponential backoff.

3. Pre-Fulfillment Verification​

Verify payment completion before releasing goods/services. Always confirm status is "paid" before fulfillment.

4. Customer Support​

Look up transaction status when customers inquire about payments. Verify reference before searching.

5. Reconciliation​

Periodically verify transaction records match payment gateway. Compare local status with API response.

6. Abandoned Transaction Follow-up​

Check status of pending transactions for recovery campaigns. Focus on transactions 24-72 hours old.

Best Practices​

Polling Strategy​

  • Start with 3-5 second intervals
  • Implement exponential backoff (increase interval over time)
  • Maximum interval: 30 seconds
  • Stop polling after 10 minutes or when terminal state reached
  • Terminal states: paid, failed, cancelled, expired

Rate Limiting​

  • Minimum 2 seconds between requests for same reference
  • Batch queries with delays between batches
  • Implement request queue for high-volume scenarios

Caching​

  • Cache responses for 5 seconds for non-terminal states
  • Cache terminal states for 1 hour
  • Invalidate cache on webhook receipt

Error Handling​

  • Transaction not found (400): Don't retry, verify reference
  • Authentication failure (403): Check credentials, don't retry
  • Network errors: Retry with exponential backoff (max 3 attempts)
  • Log all errors with context

Monitoring​

  • Log all requery attempts with duration
  • Alert on slow responses (>5 seconds)
  • Track failure patterns by reference
  • Monitor query frequency to prevent abuse

When to Use Requery​

✅ Appropriate Uses​

  • Webhook backup verification
  • Customer status inquiries
  • Pre-fulfillment checks
  • Daily reconciliation
  • Abandoned transaction checks
  • Payment flow debugging

❌ Avoid Using For​

  • Continuous rapid polling (< 2 seconds)
  • Primary status notification (use webhooks)
  • Bulk historical queries (use transaction histories)
  • Real-time dashboards with hundreds of references
  • Long-term status storage

Common Error Scenarios​

Transaction Not Found​

Cause: Invalid reference or transaction doesn't exist Solution: Verify reference format and ensure transaction was initialized

Authentication Failure​

Cause: Invalid or expired merchant_secret_key Solution: Verify credentials and key permissions

Rate Limiting​

Cause: Too many requests in short period Solution: Implement proper delays and request queuing

Implementation Guidelines​

Polling Implementation​

  • Use exponential backoff starting at 3 seconds
  • Maximum 100 polling attempts
  • Stop on terminal states
  • Implement timeout after 10 minutes

Batch Queries​

  • Process maximum 5 references concurrently
  • Add 1 second delay between batches
  • Handle failures individually
  • Use Promise.allSettled for parallel processing

Circuit Breaker​

  • Open circuit after 5 consecutive failures
  • Wait 60 seconds before retry
  • Gradually resume service with half-open state
  • Verify status field is true
  • Check payment_status exists
  • Validate reference matches query
  • Ensure data object is populated