Skip to content
straddle API Docs
Get started
API Reference

Payments

Payments provide endpoints to filter both Charges and Payouts with multiple different parameters.

Search payments
PaymentSummaryPagedV1 Payments.List(PaymentListParams?parameters, CancellationTokencancellationToken = default)
GET/v1/payments
ModelsExpand Collapse
class PaymentSummaryPagedV1:
required IReadOnlyList<Data> Data
required string ID

Unique identifier for the charge or payout.

formatuuid
required Int Amount

The amount of the charge or payout in cents.

formatint32
required DateTimeOffset CreatedAt

The time the charge or payout was created.

formatdate-time
required string Currency

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

required string? Description

An arbitrary description for the charge or payout.

required string ExternalID

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

required IReadOnlyList<string> FundingIds

Funding ids.

required Boolean HasRefund

Has the payment been refunded by an associated payout (only applicable to charges).

required Boolean HasResubmit

Has the payment been resubmitted.

required Boolean IsRefund

Is the payment a refund of an original charge (only applicable to payouts).

required Boolean IsResubmit

Is the payment a resubmit of an original payment.

required string Paykey

Value of the paykey used for the charge or payout.

required DateOnly PaymentDate

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
required PaymentType PaymentType

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

One of the following:
"charge"Charge
"payout"Payout
required Status Status

The current status of the charge or payout.

One of the following:
"created"Created
"scheduled"Scheduled
"failed"Failed
"cancelled"Cancelled
"on_hold"OnHold
"pending"Pending
"paid"Paid
"reversed"Reversed
"validating"Validating
required StatusDetailsV1 StatusDetails

Details about the current status of the charge or payout.

required DateTimeOffset ChangedAt

The time the status change occurred.

formatdate-time
required string Message

A human-readable description of the current status.

required Reason Reason

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

One of the following:
"insufficient_funds"InsufficientFunds
"closed_bank_account"ClosedBankAccount
"invalid_bank_account"InvalidBankAccount
"invalid_routing"InvalidRouting
"disputed"Disputed
"payment_stopped"PaymentStopped
"owner_deceased"OwnerDeceased
"frozen_bank_account"FrozenBankAccount
"risk_review"RiskReview
"fraudulent"Fraudulent
"duplicate_entry"DuplicateEntry
"invalid_paykey"InvalidPaykey
"payment_blocked"PaymentBlocked
"amount_too_large"AmountTooLarge
"too_many_attempts"TooManyAttempts
"internal_system_error"InternalSystemError
"user_request"UserRequest
"ok"Ok
"other_network_return"OtherNetworkReturn
"payout_refused"PayoutRefused
"cancel_request"CancelRequest
"failed_verification"FailedVerification
"require_review"RequireReview
"blocked_by_system"BlockedBySystem
"watchtower_review"WatchtowerReview
"validating"Validating
"auto_hold"AutoHold
required Source Source

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

One of the following:
"watchtower"Watchtower
"bank_decline"BankDecline
"customer_dispute"CustomerDispute
"user_action"UserAction
"system"System
string? Code

The status code if applicable.

required IReadOnlyDictionary<string, string> TraceIds

Trace ids.

required DateTimeOffset UpdatedAt

The time the charge or payout was last updated.

formatdate-time
CustomerDetailsV1 CustomerDetails

Information about the customer associated with the charge or payout.

required string ID

Unique identifier for the customer

formatuuid
required CustomerType CustomerType

The type of customer

One of the following:
"individual"Individual
"business"Business
required string Email

The customer's email address

required string Name

The name of the customer

required string Phone

The customer's phone number in E.164 format

DateTimeOffset? EffectiveAt

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
string? FundingID

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

formatuuid
IReadOnlyDictionary<string, string>? Metadata

Metadata for payment - only included if requested.

PaykeyDetailsV1 PaykeyDetails

Information about the paykey used for the charge or payout.

required string ID

Unique identifier for the paykey.

formatuuid
required string CustomerID

Unique identifier for the customer associated with the paykey.

formatuuid
required string Label

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

Int? Balance

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

formatint32

Payments related to this one (e.g. refunds, resubmissions), mapped by payment ID to relationship type.

The ID of the related payment.

formatuuid

The type of payment.

One of the following:
One of the following:
required Meta Meta
required string ApiRequestID

Unique identifier for this API request, useful for troubleshooting.

formatuuid
required DateTimeOffset ApiRequestTimestamp

Timestamp for this API request, useful for troubleshooting.

formatdate-time
required Int MaxPageSize

Maximum allowed page size for this endpoint.

formatint32
required Int PageNumber

Page number for paginated results.

formatint32
required Int PageSize

Number of items per page in this response.

formatint32
required string SortBy

The field that the results were sorted by.

required SortOrder SortOrder
One of the following:
"asc"Asc
"desc"Desc
required Int TotalItems
required Int TotalPages

The number of pages available.

formatint32
required ResponseType ResponseType

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.
One of the following:
"object"Object
"array"Array
"error"Error
"none"None