Search payments

client.payments.list(?, ?): PageNumberSchema<Data { id, amount, created_at, 15 more } >

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

params: PaymentListParams { customer_id, default_page_size, default_sort, 26 more }

customer_id?: string

Query param: Search using the customer_id of a charge or payout.

formatuuid

default_page_size?: number

Query param:

formatint32

default_sort?: "created_at" | "payment_date" | "effective_at" | 2 more

Query param: The field to sort the results by.

Accepts one of the following:

"created_at"

"payment_date"

"effective_at"

"id"

"amount"

default_sort_order?: "asc" | "desc"

Query param:

Accepts one of the following:

"asc"

"desc"

external_id?: string

Query param: Search using the external_id of a charge or payout.

funding_id?: string

Query param: Search using the funding_id of a charge or payout.

formatuuid

max_amount?: number

Query param: Search using a maximum amount of a charge or payout.

formatint32

max_created_at?: string

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

formatdate-time

max_effective_at?: string

Query param: Search using the latest effective_date of a charge or payout.

formatdate-time

max_payment_date?: string

Query param: Search using the latest payment_date of a charge or payout.

formatdate

min_amount?: number

Query param: Search using the minimum amount of a chargeorpayout`.

formatint32

min_created_at?: string

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

formatdate-time

min_effective_at?: string

Query param: Search using the earliest effective_date of a charge or payout.

formatdate-time

min_payment_date?: string

Query param: Search using the earliest of a charge or payout.

formatdate

page_number?: number

Query param: Results page number. Starts at page 1.

formatint32

page_size?: number

Query param: Results page size. Max value: 1000

formatint32

paykey?: string

Query param: Search using the paykey of a charge or payout.

paykey_id?: string

Query param: Search using the paykey_id of a charge or payout.

formatuuid

payment_id?: string

Query param: Search using the id of a charge or payout.

formatuuid

payment_status?: Array<"created" | "scheduled" | "failed" | 5 more>

Query param: 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?: Array<"charge" | "payout">

Query param: Search by the type of a charge or payout.

Accepts one of the following:

"charge"

"payout"

search_text?: string

Query param: Search using a text string associated with a charge or payout.

sort_by?: "created_at" | "payment_date" | "effective_at" | 2 more

Query param: The field to sort the results by.

Accepts one of the following:

"created_at"

"payment_date"

"effective_at"

"id"

"amount"

sort_order?: "asc" | "desc"

Query param:

Accepts one of the following:

"asc"

"desc"

status_reason?: Array<"insufficient_funds" | "closed_bank_account" | "invalid_bank_account" | 17 more>

Query param: 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?: Array<"watchtower" | "bank_decline" | "customer_dispute" | 2 more>

Query param: Source of latest payment status change.

Accepts one of the following:

"watchtower"

"bank_decline"

"customer_dispute"

"user_action"

"system"

correlationID?: string

Header param: Optional client generated identifier to trace and debug a series of requests.

requestID?: string

Header param: Optional client generated identifier to trace and debug a request.

straddleAccountID?: string

Header param: For use by platforms to specify an account id and set scope of a request.

formatuuid

ReturnsExpand Collapse

Data { id, amount, created_at, 15 more }

id: string

Unique identifier for the charge or payout.

formatuuid

amount: number

The amount of the charge or payout in cents.

formatint32

created_at: string

The time the charge or payout was created.

formatdate-time

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

formatdate

payment_type: "charge" | "payout"

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

Accepts one of the following:

"charge"

"payout"

status: "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 { 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.

formatdate-time

message: string

A human-readable description of the current status.

reason: "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: "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?: string | null

The status code if applicable.

trace_ids: Record<string, string>

Trace ids.

updated_at: string

The time the charge or payout was last updated.

formatdate-time

customer_details?: CustomerDetailsV1 { id, customer_type, email, 2 more }

Information about the customer associated with the charge or payout.

id: string

Unique identifier for the customer

formatuuid

customer_type: "individual" | "business"

The type of customer

Accepts one of the following:

"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?: string | null

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?: string | null

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

formatuuid

paykey_details?: PaykeyDetailsV1 { id, customer_id, label, balance }

Information about the paykey used for the charge or payout.

id: string

Unique identifier for the paykey.

formatuuid

customer_id: string

Unique identifier for the customer associated with the paykey.

formatuuid

label: string

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

balance?: number | null

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

formatint32

Search payments

import Straddle from '@straddlecom/straddle';

const client = new Straddle({
  apiKey: 'My API Key',
});

// Automatically fetches more pages as needed.
for await (const payment of client.payments.list()) {
  console.log(payment.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"
}