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

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:

Show Payment Object

string

Unique payment identifier

amount

integer

Payment amount in minor units

currency

string

Three-letter currency code

status

string

Payment status (pending, captured, settled, failed)

customer

object

Customer details including name, email, and billing address

payment_method

object

Payment method details and type

date

string

Payment creation timestamp

order

object

Additional payment order

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:  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
  }
}

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

Date Range Filtering

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:

Check our Error Handling Guide
Contact Support

On this page

Overview
Query Parameters
Response Format
Examples
Basic List Request
Response Examples
Pagination
Filtering Tips
Rate Limits
Best Practices

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:

Show Payment Object

string

Unique payment identifier

amount

integer

Payment amount in minor units

currency

string

Three-letter currency code

status

string

Payment status (pending, captured, settled, failed)

customer

object

Customer details including name, email, and billing address

payment_method

object

Payment method details and type

date

string

Payment creation timestamp

order

object

Additional payment order

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:  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
  }
}

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

Date Range Filtering

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:

Check our Error Handling Guide
Contact Support

On this page

Overview
Query Parameters
Response Format
Examples
Basic List Request
Response Examples
Pagination
Filtering Tips
Rate Limits
Best Practices

Overview

Query Parameters

Response Format

Examples

Basic List Request

Response Examples

Filtering Tips

Rate Limits

Best Practices

Need Help?

exchange

payouts

payments

List Payments

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?

exchange

payouts

payments

​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

Overview

Query Parameters

Response Format

Examples

Basic List Request

Response Examples

Pagination

Filtering Tips

Rate Limits

Best Practices