​
Overview

This endpoint retrieves a list of payment transactions with support for pagination, filtering, and sorting. Results are ordered by creation date in descending order by default.

GET /payments

​
Query Parameters

​
status
string

Filter by payment status.

  • Available values: pending, captured, settled, failed
  • Example: status=settled
​
before
string

Cursor for fetching records before a specific position.

  • Use for backward pagination
  • Example: before=pay_123xyz
​
after
string

Cursor for fetching records after a specific position.

  • Use for forward pagination
  • Example: after=pay_456abc
​
limit
integer
default:"15"

Number of records to return per page (max: 100).

  • Example: limit=25
​
created_after
string

Filter payments created after this timestamp (ISO 8601).

  • Example: created_after=2024-01-01T00:00:00Z
​
created_before
string

Filter payments created before this timestamp (ISO 8601).

  • Example: created_before=2024-03-31T23:59:59Z

​
Response Format

​
data
Payment[]

Array of payment objects. Each payment object contains:

​
pagination
object
​
before
string

Cursor for the previous page

​
after
string

Cursor for the next page

​
limit
integer

Number of records per page

​
Examples

​
Basic List Request

curl -X GET "https://api.spendjuice.com/payments?limit=2" \
-H "Authorization: Bearer YOUR_API_KEY"

​
Response Examples

{
  "data": [
    {
      "auth_type": "3ds",
      "expires_at": "2024-03-01T08:43:08.110470Z",
      "links": {},
      "message": "Successful",
      "payment": {
        "amount": 50000,
        "cancellation_reason": null,
        "correlation_id": "2549dcf4-d743-11ee-9d95-c6d49632367b",
        "currency": "NGN",
        "customer": {
          "billing_address": {
            "city": "Awolowo Road",
            "country": "NG",
            "line1": "Opposite Sasa Estate",
            "line2": null,
            "state": "Kwara",
            "zip_code": "23401"
          },
          "email": "asajuenitan@gmail.com",
          "first_name": "Enitan",
          "id": "d05e51df-809e-498a-ac3f-7acfc0b5d35d",
          "last_name": "Michael",
          "phone_number": "+2348036120313"
        },
        "date": "2024-02-29T20:43:08.344264Z",
        "description": "Deposit",
        "id": "2549c96c-d743-11ee-aa4d-c6d49632367b",
        "metadata": {
          "order": {
            "identifier": "dbf99bd0-262a-46bd-8339-3c741d040dbb",
            "items": [
              {
                "name": "Deposit",
                "type": "digital"
              }
            ]
          }
        },
        "mode": "live",
        "payment_method": {
          "card_number": "417396******9621",
          "expiry_month": 6,
          "expiry_year": 2024,
          "id": "5e21efda-c526-4057-92f6-1b94ee210b47",
          "type": "card"
        },
        "reference": "85d53ab5-92b8-4151-9f8f-a4f12863a911",
        "status": "settled"
      },
      "status": "settled"
    }
  ],
  "pagination": {
    "after": "2549c96c-d743-11ee-aa4d-c6d49632367b",
    "before": null,
    "limit": 2
  }
}

​
Pagination

The API uses cursor-based pagination to handle large collections of payments:

  1. Initial request: Specify limit (default: 15)
  2. Subsequent requests: Use the after cursor from the previous response
  3. Previous page: Use the before cursor if available

For optimal performance:

  • Use reasonable page sizes (15-50 records)
  • Cache results when possible
  • Implement progressive loading in your UI

​
Filtering Tips

​
Rate Limits

This endpoint has the following rate limits:

  • 1000 requests per hour per API key
  • Maximum of 100 records per request
  • Burst limit: 100 requests per minute

​
Best Practices

  1. Efficient Filtering

    • Use filters to reduce response size
    • Combine filters for precise results
    • Cache frequently accessed data

  2. Pagination Handling

    • Store cursors temporarily for navigation
    • Implement infinite scroll for large lists
    • Show loading states during fetches

  3. Error Handling

    • Implement proper retry logic
    • Handle rate limits gracefully
    • Log pagination errors

Need Help?

For additional assistance: