Skip to content
straddle API Docs
  • Auto
  • Light
  • Dark
Get started
API Reference
Payments
View as Markdown
Copy Markdown
Open in Claude
Open in ChatGPT

Search payments

payments.list(PaymentListParams**kwargs) -> SyncPageNumberSchema[Data]
get/v1/payments

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

ParametersExpand Collapse
customer_id: Optional[str]

Search using the customer_id of a charge or payout.

formatuuid
default_page_size: Optional[int]
default_sort: Optional[Literal["created_at", "payment_date", "effective_at", 2 more]]

The field to sort the results by.

Accepts one of the following:
"created_at"
"payment_date"
"effective_at"
"id"
"amount"
default_sort_order: Optional[Literal["asc", "desc"]]
Accepts one of the following:
"asc"
"desc"
external_id: Optional[str]

Search using the external_id of a charge or payout.

funding_id: Optional[str]

Search using the funding_id of a charge or payout.

formatuuid
max_amount: Optional[int]

Search using a maximum amount of a charge or payout.

formatint32
max_created_at: Optional[Union[str, datetime]]

Search using the latest created_at date of a charge or payout.

formatdate-time
max_effective_at: Optional[Union[str, datetime]]

Search using the latest effective_date of a charge or payout.

formatdate-time
max_payment_date: Optional[Union[null, null]]

Search using the latest payment_date of a charge or payout.

formatdate
min_amount: Optional[int]

Search using the minimum amount of a chargeorpayout`.

formatint32
min_created_at: Optional[Union[str, datetime]]

Search using the earliest created_at date of a charge or payout.

formatdate-time
min_effective_at: Optional[Union[str, datetime]]

Search using the earliest effective_date of a charge or payout.

formatdate-time
min_payment_date: Optional[Union[null, null]]

Search using the earliest of a charge or payout.

formatdate
page_number: Optional[int]

Results page number. Starts at page 1.

formatint32
page_size: Optional[int]

Results page size. Max value: 1000

formatint32
paykey: Optional[str]

Search using the paykey of a charge or payout.

paykey_id: Optional[str]

Search using the paykey_id of a charge or payout.

formatuuid
payment_id: Optional[str]

Search using the id of a charge or payout.

formatuuid
payment_status: Optional[List[Literal["created", "scheduled", "failed", 5 more]]]

Search by the status of a charge or payout.

Accepts one of the following:
"created"
"scheduled"
"failed"
"cancelled"
"on_hold"
"pending"
"paid"
"reversed"
payment_type: Optional[List[Literal["charge", "payout"]]]

Search by the type of a charge or payout.

Accepts one of the following:
"charge"
"payout"
search_text: Optional[str]

Search using a text string associated with a charge or payout.

sort_by: Optional[Literal["created_at", "payment_date", "effective_at", 2 more]]

The field to sort the results by.

Accepts one of the following:
"created_at"
"payment_date"
"effective_at"
"id"
"amount"
sort_order: Optional[Literal["asc", "desc"]]
Accepts one of the following:
"asc"
"desc"
status_reason: Optional[List[Literal["insufficient_funds", "closed_bank_account", "invalid_bank_account", 17 more]]]

Reason for latest payment status change.

Accepts one of the following:
"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"
status_source: Optional[List[Literal["watchtower", "bank_decline", "customer_dispute", 2 more]]]

Source of latest payment status change.

Accepts one of the following:
"watchtower"
"bank_decline"
"customer_dispute"
"user_action"
"system"
correlation_id: Optional[str]
request_id: Optional[str]
straddle_account_id: Optional[str]
ReturnsExpand Collapse
Data
id: str

Unique identifier for the charge or payout.

formatuuid
amount: int

The amount of the charge or payout in cents.

formatint32
created_at: datetime

The time the charge or payout was created.

formatdate-time
currency: str

The currency of the charge or payout. Only USD is supported.

description: str

An arbitrary description for the charge or payout.

external_id: str

Unique identifier for the charge or payout in your database. This value must be unique across all charges or payouts.

funding_ids: List[str]

Funding ids.

paykey: str

Value of the paykey used for the charge or payout.

payment_date: date

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.

formatdate
payment_type: Literal["charge", "payout"]

The type of payment. Valid values are charge or payout.

Accepts one of the following:
"charge"
"payout"
status: Literal["created", "scheduled", "failed", 5 more]

The current status of the charge or payout.

Accepts one of the following:
"created"
"scheduled"
"failed"
"cancelled"
"on_hold"
"pending"
"paid"
"reversed"
status_details: StatusDetailsV1

Details about the current status of the charge or payout.

changed_at: datetime

The time the status change occurred.

formatdate-time
message: str

A human-readable description of the current status.

reason: Literal["insufficient_funds", "closed_bank_account", "invalid_bank_account", 17 more]

A machine-readable identifier for the specific status, useful for programmatic handling.

Accepts one of the following:
"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"
source: Literal["watchtower", "bank_decline", "customer_dispute", 2 more]

Identifies the origin of the status change (e.g., bank_decline, watchtower). This helps in tracking the cause of status updates.

Accepts one of the following:
"watchtower"
"bank_decline"
"customer_dispute"
"user_action"
"system"
code: Optional[str]

The status code if applicable.

trace_ids: Dict[str, str]

Trace ids.

updated_at: datetime

The time the charge or payout was last updated.

formatdate-time
customer_details: Optional[CustomerDetailsV1]

Information about the customer associated with the charge or payout.

id: str

Unique identifier for the customer

formatuuid
customer_type: Literal["individual", "business"]

The type of customer

Accepts one of the following:
"individual"
"business"
email: str

The customer's email address

name: str

The name of the customer

phone: str

The customer's phone number in E.164 format

effective_at: Optional[datetime]

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.

formatdate-time
funding_id: Optional[str]

Unique identifier for the funding event associated with the charge or payout.

formatuuid
paykey_details: Optional[PaykeyDetailsV1]

Information about the paykey used for the charge or payout.

id: str

Unique identifier for the paykey.

formatuuid
customer_id: str

Unique identifier for the customer associated with the paykey.

formatuuid
label: str

Human-readable label that combines the bank name and masked account number to help easility represent this paykey in a UI

balance: Optional[int]

The most recent balance of the bank account associated with the paykey in dollars.

formatint32
Search payments
  • HTTP
  • TypeScript
  • Python
  • Ruby
from straddle import Straddle

client = Straddle(
    api_key="My API Key",
)
page = client.payments.list()
page = page.data[0]
print(page.id)
{
  "data": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "amount": 10000,
      "created_at": "2019-12-27T18:11:19.117Z",
      "currency": "currency",
      "description": "Invoice payment for 100 widgets",
      "external_id": "external_id",
      "funding_ids": [
        "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
      ],
      "paykey": "paykey",
      "payment_date": "2019-12-27",
      "payment_type": "charge",
      "status": "created",
      "status_details": {
        "changed_at": "2019-12-27T18:11:19.117Z",
        "message": "Payment successfully created and awaiting validation.",
        "reason": "insufficient_funds",
        "source": "system",
        "code": null
      },
      "trace_ids": {
        "foo": "string"
      },
      "updated_at": "2019-12-27T18:11:19.117Z",
      "customer_details": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "customer_type": "individual",
        "email": "ron@swanson.com",
        "name": "Ron Swanson",
        "phone": "+1234567890"
      },
      "effective_at": "2019-12-27T18:11:19.117Z",
      "funding_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "paykey_details": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "customer_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "label": "Bank of America ****1234",
        "balance": 0
      }
    }
  ],
  "meta": {
    "api_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "api_request_timestamp": "2019-12-27T18:11:19.117Z",
    "max_page_size": 0,
    "page_number": 0,
    "page_size": 0,
    "sort_by": "sort_by",
    "sort_order": "asc",
    "total_items": 0,
    "total_pages": 0
  },
  "response_type": "object"
}
Returns Examples
{
  "data": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "amount": 10000,
      "created_at": "2019-12-27T18:11:19.117Z",
      "currency": "currency",
      "description": "Invoice payment for 100 widgets",
      "external_id": "external_id",
      "funding_ids": [
        "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
      ],
      "paykey": "paykey",
      "payment_date": "2019-12-27",
      "payment_type": "charge",
      "status": "created",
      "status_details": {
        "changed_at": "2019-12-27T18:11:19.117Z",
        "message": "Payment successfully created and awaiting validation.",
        "reason": "insufficient_funds",
        "source": "system",
        "code": null
      },
      "trace_ids": {
        "foo": "string"
      },
      "updated_at": "2019-12-27T18:11:19.117Z",
      "customer_details": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "customer_type": "individual",
        "email": "ron@swanson.com",
        "name": "Ron Swanson",
        "phone": "+1234567890"
      },
      "effective_at": "2019-12-27T18:11:19.117Z",
      "funding_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "paykey_details": {
        "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "customer_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
        "label": "Bank of America ****1234",
        "balance": 0
      }
    }
  ],
  "meta": {
    "api_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "api_request_timestamp": "2019-12-27T18:11:19.117Z",
    "max_page_size": 0,
    "page_number": 0,
    "page_size": 0,
    "sort_by": "sort_by",
    "sort_order": "asc",
    "total_items": 0,
    "total_pages": 0
  },
  "response_type": "object"
}