## 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. ### Parameters - `customer_id: Optional[str]` Search using the `customer_id` of a `charge` or `payout`. - `default_page_size: Optional[int]` - `default_sort: Optional[Literal["created_at", "payment_date", "effective_at", 2 more]]` The field to sort the results by. - `"created_at"` - `"payment_date"` - `"effective_at"` - `"id"` - `"amount"` - `default_sort_order: Optional[Literal["asc", "desc"]]` - `"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`. - `include_metadata: Optional[bool]` Include the metadata for payments in the returned data. - `max_amount: Optional[int]` Search using a maximum `amount` of a `charge` or `payout`. - `max_created_at: Optional[Union[str, datetime]]` Search using the latest `created_at` date of a `charge` or `payout`. - `max_effective_at: Optional[Union[str, datetime]]` Search using the latest `effective_date` of a `charge` or `payout`. - `max_payment_date: Optional[Union[null, null]]` Search using the latest `payment_date` of a `charge` or `payout`. - `min_amount: Optional[int]` Search using the minimum `amount of a`charge`or`payout`. - `min_created_at: Optional[Union[str, datetime]]` Search using the earliest `created_at` date of a `charge` or `payout`. - `min_effective_at: Optional[Union[str, datetime]]` Search using the earliest `effective_date` of a `charge` or `payout`. - `min_payment_date: Optional[Union[null, null]]` Search using the earliest ``of a `charge` or `payout`. - `page_number: Optional[int]` Results page number. Starts at page 1. - `page_size: Optional[int]` Results page size. Max value: 1000 - `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`. - `payment_id: Optional[str]` Search using the `id` of a `charge` or `payout`. - `payment_status: Optional[List[Literal["created", "scheduled", "failed", 6 more]]]` Search by the status of a `charge` or `payout`. - `"created"` - `"scheduled"` - `"failed"` - `"cancelled"` - `"on_hold"` - `"pending"` - `"paid"` - `"reversed"` - `"validating"` - `payment_type: Optional[List[Literal["charge", "payout"]]]` Search by the type of a `charge` or `payout`. - `"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. - `"created_at"` - `"payment_date"` - `"effective_at"` - `"id"` - `"amount"` - `sort_order: Optional[Literal["asc", "desc"]]` - `"asc"` - `"desc"` - `status_reason: Optional[List[Literal["insufficient_funds", "closed_bank_account", "invalid_bank_account", 24 more]]]` Reason for latest payment status change. - `"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"` - `status_source: Optional[List[Literal["watchtower", "bank_decline", "customer_dispute", 2 more]]]` Source of latest payment status change. - `"watchtower"` - `"bank_decline"` - `"customer_dispute"` - `"user_action"` - `"system"` - `correlation_id: Optional[str]` - `request_id: Optional[str]` - `straddle_account_id: Optional[str]` ### Returns - `Data` - `id: str` Unique identifier for the `charge` or `payout`. - `amount: int` The amount of the `charge` or `payout` in cents. - `created_at: datetime` The time the `charge` or `payout` was created. - `currency: str` The currency of the `charge` or `payout`. Only USD is supported. - `description: Optional[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. - `payment_type: Literal["charge", "payout"]` The type of payment. Valid values are `charge` or `payout`. - `"charge"` - `"payout"` - `status: Literal["created", "scheduled", "failed", 6 more]` The current status of the `charge` or `payout`. - `"created"` - `"scheduled"` - `"failed"` - `"cancelled"` - `"on_hold"` - `"pending"` - `"paid"` - `"reversed"` - `"validating"` - `status_details: StatusDetailsV1` Details about the current status of the `charge` or `payout`. - `changed_at: datetime` The time the status change occurred. - `message: str` A human-readable description of the current status. - `reason: Literal["insufficient_funds", "closed_bank_account", "invalid_bank_account", 24 more]` A machine-readable identifier for the specific status, useful for programmatic handling. - `"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"` - `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. - `"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. - `customer_details: Optional[CustomerDetailsV1]` Information about the customer associated with the charge or payout. - `id: str` Unique identifier for the customer - `customer_type: Literal["individual", "business"]` The type of customer - `"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. - `funding_id: Optional[str]` Unique identifier for the funding event associated with the `charge` or `payout`. - `metadata: Optional[Dict[str, str]]` Metadata for payment - only included if requested. - `paykey_details: Optional[PaykeyDetailsV1]` Information about the paykey used for the `charge` or `payout`. - `id: str` Unique identifier for the paykey. - `customer_id: str` Unique identifier for the customer associated with the paykey. - `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. ### Example ```python import os from straddle import Straddle client = Straddle( api_key=os.environ.get("STRADDLE_API_KEY"), # This is the default and can be omitted ) page = client.payments.list() page = page.data[0] print(page.id) ``` #### Response ```json { "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", "metadata": { "foo": "string" }, "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" } ```