Charges

Lookup a charge

client.charges.get(, ?, ?): ChargeV1 { data, meta, response_type }

get/v1/charges/{id}

Update a charge

client.charges.update(, , ?): ChargeV1 { data, meta, response_type }

put/v1/charges/{id}

Create a charge

client.charges.create(, ?): ChargeV1 { data, meta, response_type }

post/v1/charges

Hold a charge

client.charges.hold(, ?, ?): ChargeV1 { data, meta, response_type }

put/v1/charges/{id}/hold

Release a charge

client.charges.release(, ?, ?): ChargeV1 { data, meta, response_type }

put/v1/charges/{id}/release

Cancel a charge

client.charges.cancel(, ?, ?): ChargeV1 { data, meta, response_type }

put/v1/charges/{id}/cancel

Get a charge by id.

client.charges.unmask(, ?, ?): ChargeUnmaskResponse { data, meta, response_type }

get/v1/charges/{id}/unmask

ModelsExpand Collapse

ChargeV1 { data, meta, response_type }

data: Data { id, amount, config, 19 more }

id: string

Unique identifier for the charge.

formatuuid

amount: number

The amount of the charge in cents.

formatint32

config: Config { balance_check, sandbox_outcome }

Configuration options for the charge.

balance_check: "required" | "enabled" | "disabled"

Defines whether to check the customer's balance before processing the charge.

Accepts one of the following:

"required"

"enabled"

"disabled"

sandbox_outcome?: "standard" | "paid" | "on_hold_daily_limit" | 8 more

Payment will simulate processing if not Standard.

Accepts one of the following:

"standard"

"paid"

"on_hold_daily_limit"

"cancelled_for_fraud_risk"

"cancelled_for_balance_check"

"failed_insufficient_funds"

"reversed_insufficient_funds"

"failed_customer_dispute"

"reversed_customer_dispute"

"failed_closed_bank_account"

"reversed_closed_bank_account"

consent_type: "internet" | "signed"

The channel or mechanism through which the payment was authorized. Use internet for payments made online or through a mobile app and signed for signed agreements where there is a consent form or contract. Use signed for PDF signatures.

Accepts one of the following:

"internet"

"signed"

created_at: string | null

Timestamp of when the charge was created.

formatdate-time

currency: string

The currency of the charge. Only USD is supported.

description: string

An arbitrary description for the charge.

device: DeviceInfoV1 { ip_address }

Information about the device used when the customer authorized the payment.

ip_address: string

The IP address of the device used when the customer authorized the charge or payout. Use 0.0.0.0 to represent an offline consent interaction.

formatipv4

external_id: string

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

funding_ids: Array<string>

Funding Ids

paykey: string

Value of the paykey used for the charge.

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.

formatdate

status: "created" | "scheduled" | "failed" | 5 more

The current status of the charge.

Accepts one of the following:

"created"

"scheduled"

"failed"

"cancelled"

"on_hold"

"pending"

"paid"

"reversed"

status_details: StatusDetailsV1 { changed_at, message, reason, 2 more }

Additional details about the current status of the charge.

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.

status_history: Array<StatusHistory>

Status history.

changed_at: string

The time the status change occurred.

formatdate-time

message: string

A human-readable description of the 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"

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"

code?: string | null

The status code if applicable.

updated_at: string | null

Timestamp of when the charge was last updated.

formatdate-time

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

Information about the customer associated with the charge.

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

Timestamp of when the charge was effective in the customer's bank account, otherwise known as the date on which the customer is debited.

formatdate-time

metadata?: Record<string, string> | null

Up to 20 additional user-defined key-value pairs. Useful for storing additional information about the charge in a structured format.

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

Information about the paykey used for the charge.

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

payment_rail?: "ach"

The payment rail that the charge will be processed through.

Accepts one of the following:

"ach"

processed_at?: string | null

Timestamp of when the charge was processed by Straddle and originated to the payment rail.

formatdate-time

meta: ResponseMetadata { api_request_id, api_request_timestamp }

Metadata about the API request, including an identifier and timestamp.

api_request_id: string

Unique identifier for this API request, useful for troubleshooting.

formatuuid

api_request_timestamp: string

Timestamp for this API request, useful for troubleshooting.

formatdate-time

response_type: "object" | "array" | "error" | "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.

Accepts one of the following:

"object"

"array"

"error"

"none"