List Payments

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

string

Filter by payment status.

Available values: pending, captured, settled, failed
Example: status=settled

string

Cursor for fetching records before a specific position.

Use for backward pagination
Example: before=pay_123xyz

string

Cursor for fetching records after a specific position.

Use for forward pagination
Example: after=pay_456abc

integer

default:"15"

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

Example: limit=25

string

Filter payments created after this timestamp (ISO 8601).

Example: created_after=2024-01-01T00:00:00Z

string

Filter payments created before this timestamp (ISO 8601).

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

Response Format

Payment[]

Array of payment objects. Each payment object contains:

Show Payment Object

string

Unique payment identifier

integer

Payment amount in minor units

string

Three-letter currency code

string

Payment status (pending, captured, settled, failed)

object

Customer details including name, email, and billing address

object

Payment method details and type

string

Payment creation timestamp

object

Additional payment order

object

string

Cursor for the previous page

string

Cursor for the next page

integer

Number of records per page

Examples

Basic List Request

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

const response = await fetch('https://api.spendjuice.com/payments?limit=2', {
  headers: {
    'Authorization': ' YOUR_API_KEY'
  }
});

import requests

response = requests.get(
    'https://api.spendjuice.com/payments',
    params={'limit': 2},
    headers={'Authorization': ' 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",
        "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
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid query parameters",
    "details": {
      "limit": ["Must be between 1 and 100"]
    }
  }
}

Pagination

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

Initial request: Specify limit (default: 15)
Subsequent requests: Use the after cursor from the previous response
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

Status-based Filtering

# Get all settled payments
GET /payments?status=settled

# Get failed payments from last 24 hours
GET /payments?status=failed&created_after=2024-03-14T00:00:00Z

Date Range Filtering

# Get payments for March 2024
GET /payments?created_after=2024-03-01T00:00:00Z&created_before=2024-03-31T23:59:59Z

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

Efficient Filtering
- Use filters to reduce response size
- Combine filters for precise results
- Cache frequently accessed data
Pagination Handling
- Store cursors temporarily for navigation
- Implement infinite scroll for large lists
- Show loading states during fetches
Error Handling
- Implement proper retry logic
- Handle rate limits gracefully
- Log pagination errors

Need Help?

For additional assistance:

Review our Error Handling Guide
Contact support@juicyway.com

Home

Customers

Payments

Payment Transactions

Transfers

Exchange

Wallet As A Service

Overview

Query Parameters

Response Format

Examples

Basic List Request

Response Examples

Filtering Tips

Rate Limits

Best Practices

Need Help?

​Overview

​Query Parameters

​Response Format

​Examples

​Basic List Request

​Response Examples

​Pagination

​Filtering Tips

​Rate Limits

​Best Practices

Need Help?

Overview

Query Parameters

Response Format

Examples

Basic List Request

Response Examples

Pagination

Filtering Tips

Rate Limits

Best Practices