API Reference

Payments

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Search payments

client.Payments.List(ctx, params) (*PageNumberSchema[PaymentSummaryPagedV1Data], error)

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

CustomerID param.Field[string]optional

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

formatuuid

DefaultPageSize param.Field[int64]optional

Query param

formatint32

DefaultSort param.Field[PaymentListParamsDefaultSort]optional

Query param: The field to sort the results by.

const PaymentListParamsDefaultSortCreatedAt PaymentListParamsDefaultSort = "created_at"

const PaymentListParamsDefaultSortPaymentDate PaymentListParamsDefaultSort = "payment_date"

const PaymentListParamsDefaultSortEffectiveAt PaymentListParamsDefaultSort = "effective_at"

const PaymentListParamsDefaultSortID PaymentListParamsDefaultSort = "id"

const PaymentListParamsDefaultSortAmount PaymentListParamsDefaultSort = "amount"

DefaultSortOrder param.Field[PaymentListParamsDefaultSortOrder]optional

Query param

const PaymentListParamsDefaultSortOrderAsc PaymentListParamsDefaultSortOrder = "asc"

const PaymentListParamsDefaultSortOrderDesc PaymentListParamsDefaultSortOrder = "desc"

ExternalID param.Field[string]optional

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

FundingID param.Field[string]optional

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

formatuuid

IncludeMetadata param.Field[bool]optional

Query param: Include the metadata for payments in the returned data.

MaxAmount param.Field[int64]optional

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

formatint32

MaxCreatedAt param.Field[Time]optional

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

formatdate-time

MaxEffectiveAt param.Field[Time]optional

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

formatdate-time

MaxPaymentDate param.Field[Time]optional

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

formatdate

MinAmount param.Field[int64]optional

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

formatint32

MinCreatedAt param.Field[Time]optional

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

formatdate-time

MinEffectiveAt param.Field[Time]optional

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

formatdate-time

MinPaymentDate param.Field[Time]optional

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

formatdate

PageNumber param.Field[int64]optional

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

formatint32

PageSize param.Field[int64]optional

Query param: Results page size. Max value: 1000

formatint32

Paykey param.Field[string]optional

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

PaykeyID param.Field[string]optional

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

formatuuid

PaymentID param.Field[string]optional

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

formatuuid

PaymentStatus param.Field[[]string]optional

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

const PaymentListParamsPaymentStatusCreated PaymentListParamsPaymentStatus = "created"

const PaymentListParamsPaymentStatusScheduled PaymentListParamsPaymentStatus = "scheduled"

const PaymentListParamsPaymentStatusFailed PaymentListParamsPaymentStatus = "failed"

const PaymentListParamsPaymentStatusCancelled PaymentListParamsPaymentStatus = "cancelled"

const PaymentListParamsPaymentStatusOnHold PaymentListParamsPaymentStatus = "on_hold"

const PaymentListParamsPaymentStatusPending PaymentListParamsPaymentStatus = "pending"

const PaymentListParamsPaymentStatusPaid PaymentListParamsPaymentStatus = "paid"

const PaymentListParamsPaymentStatusReversed PaymentListParamsPaymentStatus = "reversed"

const PaymentListParamsPaymentStatusValidating PaymentListParamsPaymentStatus = "validating"

PaymentType param.Field[[]string]optional

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

const PaymentListParamsPaymentTypeCharge PaymentListParamsPaymentType = "charge"

const PaymentListParamsPaymentTypePayout PaymentListParamsPaymentType = "payout"

SearchText param.Field[string]optional

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

SortBy param.Field[PaymentListParamsSortBy]optional

Query param: The field to sort the results by.

const PaymentListParamsSortByCreatedAt PaymentListParamsSortBy = "created_at"

const PaymentListParamsSortByPaymentDate PaymentListParamsSortBy = "payment_date"

const PaymentListParamsSortByEffectiveAt PaymentListParamsSortBy = "effective_at"

const PaymentListParamsSortByID PaymentListParamsSortBy = "id"

const PaymentListParamsSortByAmount PaymentListParamsSortBy = "amount"

SortOrder param.Field[PaymentListParamsSortOrder]optional

Query param

const PaymentListParamsSortOrderAsc PaymentListParamsSortOrder = "asc"

const PaymentListParamsSortOrderDesc PaymentListParamsSortOrder = "desc"

StatusReason param.Field[[]string]optional

Query param: Reason for latest payment status change.

const PaymentListParamsStatusReasonInsufficientFunds PaymentListParamsStatusReason = "insufficient_funds"

const PaymentListParamsStatusReasonClosedBankAccount PaymentListParamsStatusReason = "closed_bank_account"

const PaymentListParamsStatusReasonInvalidBankAccount PaymentListParamsStatusReason = "invalid_bank_account"

const PaymentListParamsStatusReasonInvalidRouting PaymentListParamsStatusReason = "invalid_routing"

const PaymentListParamsStatusReasonDisputed PaymentListParamsStatusReason = "disputed"

const PaymentListParamsStatusReasonPaymentStopped PaymentListParamsStatusReason = "payment_stopped"

const PaymentListParamsStatusReasonOwnerDeceased PaymentListParamsStatusReason = "owner_deceased"

const PaymentListParamsStatusReasonFrozenBankAccount PaymentListParamsStatusReason = "frozen_bank_account"

const PaymentListParamsStatusReasonRiskReview PaymentListParamsStatusReason = "risk_review"

const PaymentListParamsStatusReasonFraudulent PaymentListParamsStatusReason = "fraudulent"

const PaymentListParamsStatusReasonDuplicateEntry PaymentListParamsStatusReason = "duplicate_entry"

const PaymentListParamsStatusReasonInvalidPaykey PaymentListParamsStatusReason = "invalid_paykey"

const PaymentListParamsStatusReasonPaymentBlocked PaymentListParamsStatusReason = "payment_blocked"

const PaymentListParamsStatusReasonAmountTooLarge PaymentListParamsStatusReason = "amount_too_large"

const PaymentListParamsStatusReasonTooManyAttempts PaymentListParamsStatusReason = "too_many_attempts"

const PaymentListParamsStatusReasonInternalSystemError PaymentListParamsStatusReason = "internal_system_error"

const PaymentListParamsStatusReasonUserRequest PaymentListParamsStatusReason = "user_request"

const PaymentListParamsStatusReasonOk PaymentListParamsStatusReason = "ok"

const PaymentListParamsStatusReasonOtherNetworkReturn PaymentListParamsStatusReason = "other_network_return"

const PaymentListParamsStatusReasonPayoutRefused PaymentListParamsStatusReason = "payout_refused"

const PaymentListParamsStatusReasonCancelRequest PaymentListParamsStatusReason = "cancel_request"

const PaymentListParamsStatusReasonFailedVerification PaymentListParamsStatusReason = "failed_verification"

const PaymentListParamsStatusReasonRequireReview PaymentListParamsStatusReason = "require_review"

const PaymentListParamsStatusReasonBlockedBySystem PaymentListParamsStatusReason = "blocked_by_system"

const PaymentListParamsStatusReasonWatchtowerReview PaymentListParamsStatusReason = "watchtower_review"

const PaymentListParamsStatusReasonValidating PaymentListParamsStatusReason = "validating"

const PaymentListParamsStatusReasonAutoHold PaymentListParamsStatusReason = "auto_hold"

StatusSource param.Field[[]string]optional

Query param: Source of latest payment status change.

const PaymentListParamsStatusSourceWatchtower PaymentListParamsStatusSource = "watchtower"

const PaymentListParamsStatusSourceBankDecline PaymentListParamsStatusSource = "bank_decline"

const PaymentListParamsStatusSourceCustomerDispute PaymentListParamsStatusSource = "customer_dispute"

const PaymentListParamsStatusSourceUserAction PaymentListParamsStatusSource = "user_action"

const PaymentListParamsStatusSourceSystem PaymentListParamsStatusSource = "system"

CorrelationID param.Field[string]optional

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

RequestID param.Field[string]optional

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

StraddleAccountID param.Field[string]optional

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

formatuuid

ReturnsExpand Collapse

type PaymentSummaryPagedV1Data struct{…}

ID string

Unique identifier for the charge or payout.

formatuuid

Amount int64

The amount of the charge or payout in cents.

formatint32

CreatedAt Time

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.

ExternalID string

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

FundingIDs []string

Funding ids.

Paykey string

Value of the paykey used for the charge or payout.

PaymentDate Time

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

PaymentType string

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

One of the following:

const PaymentSummaryPagedV1DataPaymentTypeCharge PaymentSummaryPagedV1DataPaymentType = "charge"

const PaymentSummaryPagedV1DataPaymentTypePayout PaymentSummaryPagedV1DataPaymentType = "payout"

Status string

The current status of the charge or payout.

One of the following:

const PaymentSummaryPagedV1DataStatusCreated PaymentSummaryPagedV1DataStatus = "created"

const PaymentSummaryPagedV1DataStatusScheduled PaymentSummaryPagedV1DataStatus = "scheduled"

const PaymentSummaryPagedV1DataStatusFailed PaymentSummaryPagedV1DataStatus = "failed"

const PaymentSummaryPagedV1DataStatusCancelled PaymentSummaryPagedV1DataStatus = "cancelled"

const PaymentSummaryPagedV1DataStatusOnHold PaymentSummaryPagedV1DataStatus = "on_hold"

const PaymentSummaryPagedV1DataStatusPending PaymentSummaryPagedV1DataStatus = "pending"

const PaymentSummaryPagedV1DataStatusPaid PaymentSummaryPagedV1DataStatus = "paid"

const PaymentSummaryPagedV1DataStatusReversed PaymentSummaryPagedV1DataStatus = "reversed"

const PaymentSummaryPagedV1DataStatusValidating PaymentSummaryPagedV1DataStatus = "validating"

StatusDetails StatusDetailsV1

Details about the current status of the charge or payout.

ChangedAt Time

The time the status change occurred.

formatdate-time

Message string

A human-readable description of the current status.

Reason StatusDetailsV1Reason

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

One of the following:

const StatusDetailsV1ReasonInsufficientFunds StatusDetailsV1Reason = "insufficient_funds"

const StatusDetailsV1ReasonClosedBankAccount StatusDetailsV1Reason = "closed_bank_account"

const StatusDetailsV1ReasonInvalidBankAccount StatusDetailsV1Reason = "invalid_bank_account"

const StatusDetailsV1ReasonInvalidRouting StatusDetailsV1Reason = "invalid_routing"

const StatusDetailsV1ReasonDisputed StatusDetailsV1Reason = "disputed"

const StatusDetailsV1ReasonPaymentStopped StatusDetailsV1Reason = "payment_stopped"

const StatusDetailsV1ReasonOwnerDeceased StatusDetailsV1Reason = "owner_deceased"

const StatusDetailsV1ReasonFrozenBankAccount StatusDetailsV1Reason = "frozen_bank_account"

const StatusDetailsV1ReasonRiskReview StatusDetailsV1Reason = "risk_review"

const StatusDetailsV1ReasonFraudulent StatusDetailsV1Reason = "fraudulent"

const StatusDetailsV1ReasonDuplicateEntry StatusDetailsV1Reason = "duplicate_entry"

const StatusDetailsV1ReasonInvalidPaykey StatusDetailsV1Reason = "invalid_paykey"

const StatusDetailsV1ReasonPaymentBlocked StatusDetailsV1Reason = "payment_blocked"

const StatusDetailsV1ReasonAmountTooLarge StatusDetailsV1Reason = "amount_too_large"

const StatusDetailsV1ReasonTooManyAttempts StatusDetailsV1Reason = "too_many_attempts"

const StatusDetailsV1ReasonInternalSystemError StatusDetailsV1Reason = "internal_system_error"

const StatusDetailsV1ReasonUserRequest StatusDetailsV1Reason = "user_request"

const StatusDetailsV1ReasonOk StatusDetailsV1Reason = "ok"

const StatusDetailsV1ReasonOtherNetworkReturn StatusDetailsV1Reason = "other_network_return"

const StatusDetailsV1ReasonPayoutRefused StatusDetailsV1Reason = "payout_refused"

const StatusDetailsV1ReasonCancelRequest StatusDetailsV1Reason = "cancel_request"

const StatusDetailsV1ReasonFailedVerification StatusDetailsV1Reason = "failed_verification"

const StatusDetailsV1ReasonRequireReview StatusDetailsV1Reason = "require_review"

const StatusDetailsV1ReasonBlockedBySystem StatusDetailsV1Reason = "blocked_by_system"

const StatusDetailsV1ReasonWatchtowerReview StatusDetailsV1Reason = "watchtower_review"

const StatusDetailsV1ReasonValidating StatusDetailsV1Reason = "validating"

const StatusDetailsV1ReasonAutoHold StatusDetailsV1Reason = "auto_hold"

Source StatusDetailsV1Source

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:

const StatusDetailsV1SourceWatchtower StatusDetailsV1Source = "watchtower"

const StatusDetailsV1SourceBankDecline StatusDetailsV1Source = "bank_decline"

const StatusDetailsV1SourceCustomerDispute StatusDetailsV1Source = "customer_dispute"

const StatusDetailsV1SourceUserAction StatusDetailsV1Source = "user_action"

const StatusDetailsV1SourceSystem StatusDetailsV1Source = "system"

Code stringoptional

The status code if applicable.

TraceIDs map[string, string]

Trace ids.

UpdatedAt Time

The time the charge or payout was last updated.

formatdate-time

CustomerDetails CustomerDetailsV1optional

Information about the customer associated with the charge or payout.

ID string

Unique identifier for the customer

formatuuid

CustomerType CustomerDetailsV1CustomerType

The type of customer

One of the following:

const CustomerDetailsV1CustomerTypeIndividual CustomerDetailsV1CustomerType = "individual"

const CustomerDetailsV1CustomerTypeBusiness CustomerDetailsV1CustomerType = "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

EffectiveAt Timeoptional

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

FundingID stringoptional

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

formatuuid

Metadata map[string, string]optional

Metadata for payment - only included if requested.

PaykeyDetails PaykeyDetailsV1optional

Information about the paykey used for the charge or payout.

ID string

Unique identifier for the paykey.

formatuuid

CustomerID 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 int64optional

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

formatint32

Search payments

Go

HTTP

TypeScript

Python

Go

Ruby

CLI Tool

C#

package main

import (
  "context"
  "fmt"

  "github.com/straddleio/straddle-go"
  "github.com/straddleio/straddle-go/option"
)

func main() {
  client := straddle.NewClient(
    option.WithAPIKey("My API Key"),
  )
  page, err := client.Payments.List(context.TODO(), straddle.PaymentListParams{

  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}

200 example

{
  "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"
}

Returns Examples

200 example

{
  "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"
}