Skip to content
straddle API Docs
Get started
API Reference

Charges

Charges represent attempts to debit money from a customer's bank account using a Paykey. Each charge includes automatic balance verification, real-time fraud screening, and multi-rail optimization and detailed status tracking throughout the payment lifecycle. Use charges to accept bank payments with confidence knowing every transaction is protected.

Lookup a charge
ChargeV1 Charges.Get(ChargeGetParamsparameters, CancellationTokencancellationToken = default)
GET/v1/charges/{id}
Update a charge
ChargeV1 Charges.Update(ChargeUpdateParamsparameters, CancellationTokencancellationToken = default)
PUT/v1/charges/{id}
Create a charge
ChargeV1 Charges.Create(ChargeCreateParamsparameters, CancellationTokencancellationToken = default)
POST/v1/charges
Hold a charge
ChargeV1 Charges.Hold(ChargeHoldParamsparameters, CancellationTokencancellationToken = default)
PUT/v1/charges/{id}/hold
Release a charge
ChargeV1 Charges.Release(ChargeReleaseParamsparameters, CancellationTokencancellationToken = default)
PUT/v1/charges/{id}/release
Cancel a charge
ChargeV1 Charges.Cancel(ChargeCancelParamsparameters, CancellationTokencancellationToken = default)
PUT/v1/charges/{id}/cancel
Get a charge by id.
ChargeUnmaskResponse Charges.Unmask(ChargeUnmaskParamsparameters, CancellationTokencancellationToken = default)
GET/v1/charges/{id}/unmask
ModelsExpand Collapse
class ChargeV1:
required Data Data
required string ID

Unique identifier for the charge.

formatuuid
required Int Amount

The amount of the charge in cents.

formatint32
required Config Config

Configuration options for the charge.

required BalanceCheck BalanceCheck

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

One of the following:
"required"Required
"enabled"Enabled
"disabled"Disabled
Boolean? AutoHold

Defines whether to automatically place this charge on hold after being created.

string? AutoHoldMessage

The reason the charge is being automatically held on creation.

SandboxOutcome SandboxOutcome

Payment will simulate processing if not Standard.

One of the following:
"standard"Standard
"paid"Paid
"on_hold_daily_limit"OnHoldDailyLimit
"cancelled_for_fraud_risk"CancelledForFraudRisk
"cancelled_for_balance_check"CancelledForBalanceCheck
"failed_insufficient_funds"FailedInsufficientFunds
"reversed_insufficient_funds"ReversedInsufficientFunds
"failed_customer_dispute"FailedCustomerDispute
"reversed_customer_dispute"ReversedCustomerDispute
"failed_closed_bank_account"FailedClosedBankAccount
"reversed_closed_bank_account"ReversedClosedBankAccount

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.

One of the following:
required DateTimeOffset? CreatedAt

Timestamp of when the charge was created.

formatdate-time
required string Currency

The currency of the charge. Only USD is supported.

required string? Description

An arbitrary description for the charge.

required DeviceInfoV1 Device

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

required string IPAddress

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
required string ExternalID

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

required IReadOnlyList<string> FundingIds

Funding Ids

required string Paykey

Value of the paykey used for the charge.

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.

formatdate
required Status Status

The current status of the charge.

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

Additional details about the current status of the charge.

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 IReadOnlyList<StatusHistory> StatusHistory

Status history.

required DateTimeOffset ChangedAt

The time the status change occurred.

formatdate-time
required string Message

A human-readable description of the 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
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
string? Code

The status code if applicable.

required IReadOnlyDictionary<string, string> TraceIds

Trace Ids.

required DateTimeOffset? UpdatedAt

Timestamp of when the charge was last updated.

formatdate-time
CustomerDetailsV1 CustomerDetails

Information about the customer associated with the charge.

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

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
IReadOnlyDictionary<string, string>? Metadata

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

PaykeyDetailsV1 PaykeyDetails

Information about the paykey used for the charge.

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

The payment rail that the charge will be processed through.

DateTimeOffset? ProcessedAt

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

formatdate-time

Related payments.

One of the following:
required ResponseMetadata Meta

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

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