---
title: "Search payments"
method: GET
path: "/v1/payments"
tags: ["Payments"]
---

# Search payments

`GET /v1/payments`

Search for payments, including `charges` and `payouts`, using a variety of criteria. This endpoint supports advanced sorting and filtering options.

## Query parameters

- `page_number` integer — Results page number. Starts at page 1.
- `page_size` integer — Results page size. Max value: 1000
- `sort_by` 'created_at' | 'payment_date' | 'effective_at' | 'id' | 'amount' — The field to sort the results by.
- `sort_order` 'asc' | 'desc'
- `payment_type` PaymentTypeV1[] — Payment type.
- `payment_status` PaymentStatusV1[] — Payment status.
- `payment_id` string, uuid — Payment id.
- `external_id` string — External id.
- `customer_id` string, uuid — Customer id.
- `paykey_id` string, uuid — Paykey id.
- `paykey` string — Paykey.
- `min_amount` integer — Minimum amount.
- `max_amount` integer — Maximum amount.
- `min_payment_date` string, date — Minimum payment date.
- `max_payment_date` string, date — Maximum payment date.
- `min_created_at` string, date-time — Minimum created at.
- `max_created_at` string, date-time — Maximum created at.
- `min_effective_at` string, date-time — Minimum effective at.
- `max_effective_at` string, date-time — Maximum effective at.
- `funding_id` string, uuid — Funding id.
- `search_text` string — Search text.
- `default_page_size` integer
- `default_sort` 'created_at' | 'payment_date' | 'effective_at' | 'id' | 'amount' — The field to sort the results by.
- `default_sort_order` 'asc' | 'desc'
- `status_reason` StatusReasonV1[] — Reason for latest payment status change.
- `status_source` StatusSourceV1[] — Source of latest payment status change.
- `include_metadata` boolean — Include the metadata for payments in the returned data.

## Headers

- `Straddle-Account-Id` string, uuid
- `Request-Id` string
- `Correlation-Id` string

## Response `200`

OK

- PaymentSummaryV1PagedResponse
  - `meta` PagedResponseMetadata2, required
    - `api_request_id` string, uuid, required — Unique identifier for this API request, useful for troubleshooting.
    - `api_request_timestamp` string, date-time, required — Timestamp for this API request, useful for troubleshooting.
    - `total_items` integer, required
    - `page_number` integer, required — Page number for paginated results.
    - `page_size` integer, required — Number of items per page in this response.
    - `max_page_size` integer, required — Maximum allowed page size for this endpoint.
    - `sort_by` string, required — The field that the results were sorted by.
    - `sort_order` 'asc' | 'desc', required
    - `total_pages` integer, required — The number of pages available.
  - `response_type` 'object' | 'array' | 'error' | 'none', required — Indicates the structure of the returned content. - "object" means the `data` field contains a single JSON object. - "array" means the `data` field contains an array of objects. - "error" means the `data` field contains an error object with details of the issue. - "none" means no data is returned.
  - `data` PaymentSummaryV1[], required
    - `id` string, uuid, required — Unique identifier for the `charge` or `payout`.
    - `payment_type` 'charge' | 'payout', required — The type of payment.
    - `payment_date` string, date, required — The desired date on which the payment should be occur. For charges, this means the date you want the customer to be debited on. For payouts, this means the date you want the funds to be sent from your bank account.
    - `effective_at` string, date-time, nullable — The actual date on which the payment occurred. For charges, this is the date the customer was debited. For payouts, this is the date the funds were sent from your bank account.
    - `description` string, nullable, required — An arbitrary description for the `charge` or `payout`.
    - `external_id` string, required — Unique identifier for the `charge` or `payout` in your database. This value must be unique across all charges or payouts.
    - `amount` integer, required — The amount of the `charge` or `payout` in cents.
    - `currency` string, required — The currency of the `charge` or `payout`. Only USD is supported.
    - `customer_details` CustomerDetailsV1 — Information about the customer associated with the charge or payout.
      - `id` string, uuid, required — Unique identifier for the customer
      - `name` string, required — The name of the customer
      - `customer_type` 'individual' | 'business', required
      - `email` string, required — The customer's email address
      - `phone` string, required — The customer's phone number in E.164 format
    - `paykey` string, required — Value of the `paykey` used for the `charge` or `payout`.
    - `paykey_details` PaykeyDetailsV1
      - `id` string, uuid, required — Unique identifier for the paykey.
      - `customer_id` string, uuid, required — Unique identifier for the customer associated with the paykey.
      - `label` string, required — Human-readable label that combines the bank name and masked account number to help easility represent this paykey in a UI
      - `balance` integer, nullable — The most recent balance of the bank account associated with the paykey in dollars.
    - `status` 'created' | 'scheduled' | 'failed' | 'cancelled' | 'on_hold' | 'pending' | 'paid' | 'reversed' | 'validating', required — The current status of the `charge` or `payout`.
    - `status_details` StatusDetailsV11, required
      - `message` string, required — A human-readable description of the current status.
      - `reason` 'insufficient_funds' | 'closed_bank_account' | 'invalid_bank_account' | 'invalid_routing' | 'disputed' | 'payment_stopped' | 'owner_deceased' | 'frozen_bank_account' | 'risk_review' | 'fraudulent' | 'duplicate_entry' | 'invalid_paykey' | 'payment_blocked' | 'amount_too_large' | 'too_many_attempts' | 'internal_system_error' | 'user_request' | 'ok' | 'other_network_return' | 'payout_refused' | 'cancel_request' | 'failed_verification' | 'require_review' | 'blocked_by_system' | 'watchtower_review' | 'validating' | 'auto_hold', required
      - `source` 'watchtower' | 'bank_decline' | 'customer_dispute' | 'user_action' | 'system', required
      - `changed_at` string, date-time, required — The time the status change occurred.
      - `code` string, nullable — The status code if applicable.
    - `funding_id` string, uuid, nullable — Unique identifier for the funding event associated with the `charge` or `payout`.
    - `created_at` string, date-time, required — The time the `charge` or `payout` was created.
    - `updated_at` string, date-time, required — The time the `charge` or `payout` was last updated.
    - `funding_ids` string[], required — Funding ids.
    - `trace_ids` object, required — Trace ids.
    - `metadata` object, nullable — Metadata for payment - only included if requested.
    - `related_payments` object, nullable — Related payments.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Failed
- `500` — Server Error

---

[API](https://skmtc.net/straddleio/apis/straddle-api.md) · [All operations](https://skmtc.net/straddleio/apis/straddle-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/straddleio/straddle-api/revisions/6e13cd88cda9/schema)