Transactions API

This document provides a comprehensive guide to fetch your transaction data from Pay Agency's API. The API allows you to retrieve both live and test transaction data.

API Endpoints

GET https://backend.pay.agency/api/v1/live-transactions

Authentication

All API requests require authentication using your secret key in the Authorization header.

Authorization: Bearer YOUR_SECRET_KEY

Query Parameters

The API supports the following query parameters to filter and paginate transaction data:

Parameter	Type	Description	Required
`transaction_start_date`	String	Start date for filtering transactions (YYYY-MM-DD format)	No
`transaction_end_date`	String	End date for filtering transactions (YYYY-MM-DD format)	No
`nextCursor`	String	Cursor for next page of results	No
`prevCursor`	String	Cursor for previous page of results	No

Example Request

curl --location 'https://backend.pay.agency/api/v1/live-transactions?transaction_start_date=2023-05-01&transaction_end_date=2023-05-15' \
--header 'Authorization: Bearer YOUR_SECRET_KEY'

Response Structure

The API response contains transaction data along with metadata for pagination.

{
  "message": "Transactions fetched successfully",
  "data": [ ... array of transaction objects ... ],
  "meta": {
    "hasNextPage": true,
    "hasPreviousPage": false,
    "nextCursor": "NTQ1",
    "prevCursor": "NTY0",
    "totalCount": 144
  }
}

Transaction Object Properties

Each transaction object in the response contains the following properties:

Property	Type	Description
`first_name`	String	First name of the customer
`last_name`	String	Last name of the customer
`converted_amount`	String	Transaction amount converted to display currency
`converted_currency`	String	Currency code for the converted amount
`transaction_id`	String	Unique identifier for the transaction
`amount`	String	Original transaction amount
`currency`	String	Original currency code
`status`	String	Status of the transaction (SUCCESS, FAILED, etc.)
`card_type`	String	Type of card used (VISA, MASTERCARD, etc.)
`card_number`	String	Masked card number
`transaction_type`	String	Type of transaction (CARD, APM, etc.)
`order_id`	String	Unique order ID (if provided)
`country`	String	Country code of the transaction origin
`email`	String	Customer email address
`created_at`	String	Transaction creation timestamp
`transaction_date`	String	Transaction processing timestamp
`chargeback_date`	String	Chargeback date (if applicable)
`refund_date`	String	Refund date (if applicable)
`suspicious_date`	String	Date when transaction was marked suspicious (if any)
`merchant_connector`	Object	Information about the payment processor
`user`	Object	Merchant user information

Example Response

{
  "message": "Transactions fetched successfully",
  "data": [
    {
      "first_name": "James",
      "last_name": "Karlo",
      "converted_amount": "200",
      "converted_currency": "USD",
      "transaction_id": "PA3060287394219373",
      "amount": "200",
      "currency": "USD",
      "status": "SUCCESS",
      "card_type": null,
      "card_number": null,
      "transaction_type": "APM",
      "order_id": null,
      "country": "IN",
      "email": "james.karlo@gmail.com",
      "created_at": "2025-05-13T10:03:22.878Z",
      "transaction_date": "2025-05-13T10:03:22.886Z",
      "chargeback_date": null,
      "refund_date": null,
      "suspicious_date": null,
      "merchant_connector": {
        "name": "test MID"
      },
      "user": {
        "name": "James dean",
        "user_kyc": {
          "name": "James dean"
        }
      }
    },
     // ...more transactions...
  ],
  "meta": {
    "hasNextPage": true,
    "hasPreviousPage": false,
    "nextCursor": "NTQ1",
    "prevCursor": "NTY0",
    "totalCount": 144
  }
}

Pagination

The API response includes pagination metadata that can be used to fetch additional pages of transaction data:

hasNextPage: Boolean indicating if there are more transactions available after this page
hasPreviousPage: Boolean indicating if there are transactions available before this page
nextCursor: Cursor string to fetch the next page of results (use with nextCursor parameter)
prevCursor: Cursor string to fetch the previous page of results (use with prevCursor parameter)
totalCount: Total number of transactions matching the current filter criteria

Example: Fetching the Next Page

const nextPageUrl = 'https://backend.pay.agency/api/v1/live-transactions?nextCursor=NTQ1';
 
fetch(nextPageUrl, {
  headers: {
    'Authorization': 'Bearer YOUR_SECRET_KEY'
  }
})
.then(response => response.json())
.then(data => console.log(data));

Error Responses

The API may return the following error responses:

{
  "message": "Authentication token is missing or invalid."
}

{
  "message": "Authentication Secret Key is missing."
}

{
  "message": "Invalid Live Secret Key."
}

Transactions API

On this page