Skip to content
straddle API Docs
Get started
API Reference
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.

ParametersExpand Collapse
--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 chargeorpayout`.

--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.

ReturnsExpand Collapse
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.

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"

Search payments

straddle payments list \
  --api-key 'My API Key'
{
  "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"
}
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",
      "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"
}