# Payments ## Search payments `$ straddle payments list` **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 string` Query param: Search using the `customer_id` of a `charge` or `payout`. - `--default-page-size: optional number` Query param - `--default-sort: optional "created_at" or "payment_date" or "effective_at" or 2 more` Query param: The field to sort the results by. - `--default-sort-order: optional "asc" or "desc"` Query param - `--external-id: optional string` Query param: Search using the `external_id` of a `charge` or `payout`. - `--funding-id: optional string` Query param: Search using the `funding_id` of a `charge` or `payout`. - `--include-metadata: optional boolean` Query param: Include the metadata for payments in the returned data. - `--max-amount: optional number` Query param: Search using a maximum `amount` of a `charge` or `payout`. - `--max-created-at: optional string` Query param: Search using the latest `created_at` date of a `charge` or `payout`. - `--max-effective-at: optional string` Query param: Search using the latest `effective_date` of a `charge` or `payout`. - `--max-payment-date: optional string` Query param: Search using the latest `payment_date` of a `charge` or `payout`. - `--min-amount: optional number` Query param: Search using the minimum `amount of a`charge`or`payout`. - `--min-created-at: optional string` Query param: Search using the earliest `created_at` date of a `charge` or `payout`. - `--min-effective-at: optional string` Query param: Search using the earliest `effective_date` of a `charge` or `payout`. - `--min-payment-date: optional string` Query param: Search using the earliest ``of a `charge` or `payout`. - `--page-number: optional number` Query param: Results page number. Starts at page 1. - `--page-size: optional number` Query param: Results page size. Max value: 1000 - `--paykey: optional string` Query param: Search using the `paykey` of a `charge` or `payout`. - `--paykey-id: optional string` Query param: Search using the `paykey_id` of a `charge` or `payout`. - `--payment-id: optional string` Query param: Search using the `id` of a `charge` or `payout`. - `--payment-status: optional array of "created" or "scheduled" or "failed" or 6 more` Query param: Search by the status of a `charge` or `payout`. - `--payment-type: optional array of "charge" or "payout"` Query param: Search by the type of a `charge` or `payout`. - `--search-text: optional string` Query param: Search using a text string associated with a `charge` or `payout`. - `--sort-by: optional "created_at" or "payment_date" or "effective_at" or 2 more` Query param: The field to sort the results by. - `--sort-order: optional "asc" or "desc"` Query param - `--status-reason: optional array of "insufficient_funds" or "closed_bank_account" or "invalid_bank_account" or 24 more` Query param: Reason for latest payment status change. - `--status-source: optional array of "watchtower" or "bank_decline" or "customer_dispute" or 2 more` Query param: Source of latest payment status change. - `--correlation-id: optional string` Header param: Optional client generated identifier to trace and debug a series of requests. - `--request-id: optional string` Header param: Optional client generated identifier to trace and debug a request. - `--straddle-account-id: optional string` Header param: For use by platforms to specify an account id and set scope of a request. ### Returns - `paymentSummaryPagedV1: object { data, meta, response_type }` - `data: array of object { id, amount, created_at, 17 more }` - `id: string` Unique identifier for the `charge` or `payout`. - `amount: number` The amount of the `charge` or `payout` in cents. - `created_at: string` The time the `charge` or `payout` was created. - `currency: string` The currency of the `charge` or `payout`. Only USD is supported. - `description: string` An arbitrary description for the `charge` or `payout`. - `external_id: string` Unique identifier for the `charge` or `payout` in your database. This value must be unique across all charges or payouts. - `funding_ids: array of string` Funding ids. - `paykey: string` Value of the `paykey` used for the `charge` or `payout`. - `payment_date: string` 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: "charge" or "payout"` The type of payment. Valid values are `charge` or `payout`. - `"charge"` - `"payout"` - `status: "created" or "scheduled" or "failed" or 6 more` The current status of the `charge` or `payout`. - `"created"` - `"scheduled"` - `"failed"` - `"cancelled"` - `"on_hold"` - `"pending"` - `"paid"` - `"reversed"` - `"validating"` - `status_details: object { changed_at, message, reason, 2 more }` Details about the current status of the `charge` or `payout`. - `changed_at: string` The time the status change occurred. - `message: string` A human-readable description of the current status. - `reason: "insufficient_funds" or "closed_bank_account" or "invalid_bank_account" or 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: "watchtower" or "bank_decline" or "customer_dispute" or 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 string` The status code if applicable. - `trace_ids: map[string]` Trace ids. - `updated_at: string` The time the `charge` or `payout` was last updated. - `customer_details: optional object { id, customer_type, email, 2 more }` Information about the customer associated with the charge or payout. - `id: string` Unique identifier for the customer - `customer_type: "individual" or "business"` The type of customer - `"individual"` - `"business"` - `email: string` The customer's email address - `name: string` The name of the customer - `phone: string` The customer's phone number in E.164 format - `effective_at: optional string` 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 string` Unique identifier for the funding event associated with the `charge` or `payout`. - `metadata: optional map[string]` Metadata for payment - only included if requested. - `paykey_details: optional object { id, customer_id, label, balance }` Information about the paykey used for the `charge` or `payout`. - `id: string` Unique identifier for the paykey. - `customer_id: string` Unique identifier for the customer associated with the paykey. - `label: string` Human-readable label that combines the bank name and masked account number to help easility represent this paykey in a UI - `balance: optional number` The most recent balance of the bank account associated with the paykey in dollars. - `related_payments: optional map["original" or "resubmit" or "refund"]` Related payments. - `"original"` - `"resubmit"` - `"refund"` - `meta: object { api_request_id, api_request_timestamp, max_page_size, 6 more }` - `api_request_id: string` Unique identifier for this API request, useful for troubleshooting. - `api_request_timestamp: string` Timestamp for this API request, useful for troubleshooting. - `max_page_size: number` Maximum allowed page size for this endpoint. - `page_number: number` Page number for paginated results. - `page_size: number` Number of items per page in this response. - `sort_by: string` The field that the results were sorted by. - `sort_order: "asc" or "desc"` - `"asc"` - `"desc"` - `total_items: number` - `total_pages: number` The number of pages available. - `response_type: "object" or "array" or "error" or "none"` 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. - `"object"` - `"array"` - `"error"` - `"none"` ### Example ```cli straddle payments list \ --api-key 'My API Key' ``` #### 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 }, "related_payments": { "foo": "original" } } ], "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" } ``` ## Domain Types ### Payment Summary Paged V1 - `paymentSummaryPagedV1: object { data, meta, response_type }` - `data: array of object { id, amount, created_at, 17 more }` - `id: string` Unique identifier for the `charge` or `payout`. - `amount: number` The amount of the `charge` or `payout` in cents. - `created_at: string` The time the `charge` or `payout` was created. - `currency: string` The currency of the `charge` or `payout`. Only USD is supported. - `description: string` An arbitrary description for the `charge` or `payout`. - `external_id: string` Unique identifier for the `charge` or `payout` in your database. This value must be unique across all charges or payouts. - `funding_ids: array of string` Funding ids. - `paykey: string` Value of the `paykey` used for the `charge` or `payout`. - `payment_date: string` 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: "charge" or "payout"` The type of payment. Valid values are `charge` or `payout`. - `"charge"` - `"payout"` - `status: "created" or "scheduled" or "failed" or 6 more` The current status of the `charge` or `payout`. - `"created"` - `"scheduled"` - `"failed"` - `"cancelled"` - `"on_hold"` - `"pending"` - `"paid"` - `"reversed"` - `"validating"` - `status_details: object { changed_at, message, reason, 2 more }` Details about the current status of the `charge` or `payout`. - `changed_at: string` The time the status change occurred. - `message: string` A human-readable description of the current status. - `reason: "insufficient_funds" or "closed_bank_account" or "invalid_bank_account" or 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: "watchtower" or "bank_decline" or "customer_dispute" or 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 string` The status code if applicable. - `trace_ids: map[string]` Trace ids. - `updated_at: string` The time the `charge` or `payout` was last updated. - `customer_details: optional object { id, customer_type, email, 2 more }` Information about the customer associated with the charge or payout. - `id: string` Unique identifier for the customer - `customer_type: "individual" or "business"` The type of customer - `"individual"` - `"business"` - `email: string` The customer's email address - `name: string` The name of the customer - `phone: string` The customer's phone number in E.164 format - `effective_at: optional string` 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 string` Unique identifier for the funding event associated with the `charge` or `payout`. - `metadata: optional map[string]` Metadata for payment - only included if requested. - `paykey_details: optional object { id, customer_id, label, balance }` Information about the paykey used for the `charge` or `payout`. - `id: string` Unique identifier for the paykey. - `customer_id: string` Unique identifier for the customer associated with the paykey. - `label: string` Human-readable label that combines the bank name and masked account number to help easility represent this paykey in a UI - `balance: optional number` The most recent balance of the bank account associated with the paykey in dollars. - `related_payments: optional map["original" or "resubmit" or "refund"]` Related payments. - `"original"` - `"resubmit"` - `"refund"` - `meta: object { api_request_id, api_request_timestamp, max_page_size, 6 more }` - `api_request_id: string` Unique identifier for this API request, useful for troubleshooting. - `api_request_timestamp: string` Timestamp for this API request, useful for troubleshooting. - `max_page_size: number` Maximum allowed page size for this endpoint. - `page_number: number` Page number for paginated results. - `page_size: number` Number of items per page in this response. - `sort_by: string` The field that the results were sorted by. - `sort_order: "asc" or "desc"` - `"asc"` - `"desc"` - `total_items: number` - `total_pages: number` The number of pages available. - `response_type: "object" or "array" or "error" or "none"` 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. - `"object"` - `"array"` - `"error"` - `"none"`