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

client.Charges.Get(ctx, id, query) (*ChargeV1, error)

GET/v1/charges/{id}

Update a charge

client.Charges.Update(ctx, id, params) (*ChargeV1, error)

PUT/v1/charges/{id}

Create a charge

client.Charges.New(ctx, params) (*ChargeV1, error)

POST/v1/charges

Hold a charge

client.Charges.Hold(ctx, id, params) (*ChargeV1, error)

PUT/v1/charges/{id}/hold

Release a charge

client.Charges.Release(ctx, id, params) (*ChargeV1, error)

PUT/v1/charges/{id}/release

Cancel a charge

client.Charges.Cancel(ctx, id, params) (*ChargeV1, error)

PUT/v1/charges/{id}/cancel

Get a charge by id.

client.Charges.Unmask(ctx, id, query) (*ChargeUnmaskResponse, error)

GET/v1/charges/{id}/unmask

ModelsExpand Collapse

type ChargeV1 struct{…}

Data ChargeV1Data

ID string

Unique identifier for the charge.

formatuuid

Amount int64

The amount of the charge in cents.

formatint32

Config ChargeV1DataConfig

Configuration options for the charge.

BalanceCheck string

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

One of the following:

const ChargeV1DataConfigBalanceCheckRequired ChargeV1DataConfigBalanceCheck = "required"

const ChargeV1DataConfigBalanceCheckEnabled ChargeV1DataConfigBalanceCheck = "enabled"

const ChargeV1DataConfigBalanceCheckDisabled ChargeV1DataConfigBalanceCheck = "disabled"

AutoHold booloptional

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

AutoHoldMessage stringoptional

The reason the charge is being automatically held on creation.

SandboxOutcome stringoptional

Payment will simulate processing if not Standard.

One of the following:

const ChargeV1DataConfigSandboxOutcomeStandard ChargeV1DataConfigSandboxOutcome = "standard"

const ChargeV1DataConfigSandboxOutcomePaid ChargeV1DataConfigSandboxOutcome = "paid"

const ChargeV1DataConfigSandboxOutcomeOnHoldDailyLimit ChargeV1DataConfigSandboxOutcome = "on_hold_daily_limit"

const ChargeV1DataConfigSandboxOutcomeCancelledForFraudRisk ChargeV1DataConfigSandboxOutcome = "cancelled_for_fraud_risk"

const ChargeV1DataConfigSandboxOutcomeCancelledForBalanceCheck ChargeV1DataConfigSandboxOutcome = "cancelled_for_balance_check"

const ChargeV1DataConfigSandboxOutcomeFailedInsufficientFunds ChargeV1DataConfigSandboxOutcome = "failed_insufficient_funds"

const ChargeV1DataConfigSandboxOutcomeReversedInsufficientFunds ChargeV1DataConfigSandboxOutcome = "reversed_insufficient_funds"

const ChargeV1DataConfigSandboxOutcomeFailedCustomerDispute ChargeV1DataConfigSandboxOutcome = "failed_customer_dispute"

const ChargeV1DataConfigSandboxOutcomeReversedCustomerDispute ChargeV1DataConfigSandboxOutcome = "reversed_customer_dispute"

const ChargeV1DataConfigSandboxOutcomeFailedClosedBankAccount ChargeV1DataConfigSandboxOutcome = "failed_closed_bank_account"

const ChargeV1DataConfigSandboxOutcomeReversedClosedBankAccount ChargeV1DataConfigSandboxOutcome = "reversed_closed_bank_account"

ConsentType string

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:

const ChargeV1DataConsentTypeInternet ChargeV1DataConsentType = "internet"

const ChargeV1DataConsentTypeSigned ChargeV1DataConsentType = "signed"

CreatedAt Time

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

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

IPAddress 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

ExternalID string

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

FundingIDs []string

Funding Ids

Paykey string

Value of the paykey used for the charge.

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.

formatdate

Status string

The current status of the charge.

One of the following:

const ChargeV1DataStatusCreated ChargeV1DataStatus = "created"

const ChargeV1DataStatusScheduled ChargeV1DataStatus = "scheduled"

const ChargeV1DataStatusFailed ChargeV1DataStatus = "failed"

const ChargeV1DataStatusCancelled ChargeV1DataStatus = "cancelled"

const ChargeV1DataStatusOnHold ChargeV1DataStatus = "on_hold"

const ChargeV1DataStatusPending ChargeV1DataStatus = "pending"

const ChargeV1DataStatusPaid ChargeV1DataStatus = "paid"

const ChargeV1DataStatusReversed ChargeV1DataStatus = "reversed"

const ChargeV1DataStatusValidating ChargeV1DataStatus = "validating"

StatusDetails StatusDetailsV1

Additional details about the current status of the charge.

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.

StatusHistory []ChargeV1DataStatusHistory

Status history.

ChangedAt Time

The time the status change occurred.

formatdate-time

Message string

A human-readable description of the status.

Reason string

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

One of the following:

const ChargeV1DataStatusHistoryReasonInsufficientFunds ChargeV1DataStatusHistoryReason = "insufficient_funds"

const ChargeV1DataStatusHistoryReasonClosedBankAccount ChargeV1DataStatusHistoryReason = "closed_bank_account"

const ChargeV1DataStatusHistoryReasonInvalidBankAccount ChargeV1DataStatusHistoryReason = "invalid_bank_account"

const ChargeV1DataStatusHistoryReasonInvalidRouting ChargeV1DataStatusHistoryReason = "invalid_routing"

const ChargeV1DataStatusHistoryReasonDisputed ChargeV1DataStatusHistoryReason = "disputed"

const ChargeV1DataStatusHistoryReasonPaymentStopped ChargeV1DataStatusHistoryReason = "payment_stopped"

const ChargeV1DataStatusHistoryReasonOwnerDeceased ChargeV1DataStatusHistoryReason = "owner_deceased"

const ChargeV1DataStatusHistoryReasonFrozenBankAccount ChargeV1DataStatusHistoryReason = "frozen_bank_account"

const ChargeV1DataStatusHistoryReasonRiskReview ChargeV1DataStatusHistoryReason = "risk_review"

const ChargeV1DataStatusHistoryReasonFraudulent ChargeV1DataStatusHistoryReason = "fraudulent"

const ChargeV1DataStatusHistoryReasonDuplicateEntry ChargeV1DataStatusHistoryReason = "duplicate_entry"

const ChargeV1DataStatusHistoryReasonInvalidPaykey ChargeV1DataStatusHistoryReason = "invalid_paykey"

const ChargeV1DataStatusHistoryReasonPaymentBlocked ChargeV1DataStatusHistoryReason = "payment_blocked"

const ChargeV1DataStatusHistoryReasonAmountTooLarge ChargeV1DataStatusHistoryReason = "amount_too_large"

const ChargeV1DataStatusHistoryReasonTooManyAttempts ChargeV1DataStatusHistoryReason = "too_many_attempts"

const ChargeV1DataStatusHistoryReasonInternalSystemError ChargeV1DataStatusHistoryReason = "internal_system_error"

const ChargeV1DataStatusHistoryReasonUserRequest ChargeV1DataStatusHistoryReason = "user_request"

const ChargeV1DataStatusHistoryReasonOk ChargeV1DataStatusHistoryReason = "ok"

const ChargeV1DataStatusHistoryReasonOtherNetworkReturn ChargeV1DataStatusHistoryReason = "other_network_return"

const ChargeV1DataStatusHistoryReasonPayoutRefused ChargeV1DataStatusHistoryReason = "payout_refused"

const ChargeV1DataStatusHistoryReasonCancelRequest ChargeV1DataStatusHistoryReason = "cancel_request"

const ChargeV1DataStatusHistoryReasonFailedVerification ChargeV1DataStatusHistoryReason = "failed_verification"

const ChargeV1DataStatusHistoryReasonRequireReview ChargeV1DataStatusHistoryReason = "require_review"

const ChargeV1DataStatusHistoryReasonBlockedBySystem ChargeV1DataStatusHistoryReason = "blocked_by_system"

const ChargeV1DataStatusHistoryReasonWatchtowerReview ChargeV1DataStatusHistoryReason = "watchtower_review"

const ChargeV1DataStatusHistoryReasonValidating ChargeV1DataStatusHistoryReason = "validating"

const ChargeV1DataStatusHistoryReasonAutoHold ChargeV1DataStatusHistoryReason = "auto_hold"

Source string

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 ChargeV1DataStatusHistorySourceWatchtower ChargeV1DataStatusHistorySource = "watchtower"

const ChargeV1DataStatusHistorySourceBankDecline ChargeV1DataStatusHistorySource = "bank_decline"

const ChargeV1DataStatusHistorySourceCustomerDispute ChargeV1DataStatusHistorySource = "customer_dispute"

const ChargeV1DataStatusHistorySourceUserAction ChargeV1DataStatusHistorySource = "user_action"

const ChargeV1DataStatusHistorySourceSystem ChargeV1DataStatusHistorySource = "system"

Status string

The current status of the charge or payout.

One of the following:

const ChargeV1DataStatusHistoryStatusCreated ChargeV1DataStatusHistoryStatus = "created"

const ChargeV1DataStatusHistoryStatusScheduled ChargeV1DataStatusHistoryStatus = "scheduled"

const ChargeV1DataStatusHistoryStatusFailed ChargeV1DataStatusHistoryStatus = "failed"

const ChargeV1DataStatusHistoryStatusCancelled ChargeV1DataStatusHistoryStatus = "cancelled"

const ChargeV1DataStatusHistoryStatusOnHold ChargeV1DataStatusHistoryStatus = "on_hold"

const ChargeV1DataStatusHistoryStatusPending ChargeV1DataStatusHistoryStatus = "pending"

const ChargeV1DataStatusHistoryStatusPaid ChargeV1DataStatusHistoryStatus = "paid"

const ChargeV1DataStatusHistoryStatusReversed ChargeV1DataStatusHistoryStatus = "reversed"

const ChargeV1DataStatusHistoryStatusValidating ChargeV1DataStatusHistoryStatus = "validating"

Code stringoptional

The status code if applicable.

TraceIDs map[string, string]

Trace Ids.

UpdatedAt Time

Timestamp of when the charge was last updated.

formatdate-time

CustomerDetails CustomerDetailsV1optional

Information about the customer associated with the charge.

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

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 map[string, string]optional

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

PaykeyDetails PaykeyDetailsV1optional

Information about the paykey used for the charge.

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

PaymentRail stringoptional

The payment rail that the charge will be processed through.

ProcessedAt Timeoptional

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

formatdate-time

RelatedPayments map[string, string]optional

Related payments.

One of the following:

const ChargeV1DataRelatedPaymentOriginal ChargeV1DataRelatedPayment = "original"

const ChargeV1DataRelatedPaymentResubmit ChargeV1DataRelatedPayment = "resubmit"

const ChargeV1DataRelatedPaymentRefund ChargeV1DataRelatedPayment = "refund"

Meta ResponseMetadata

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

APIRequestID string

Unique identifier for this API request, useful for troubleshooting.

formatuuid

APIRequestTimestamp Time

Timestamp for this API request, useful for troubleshooting.

formatdate-time

ResponseType ChargeV1ResponseType

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:

const ChargeV1ResponseTypeObject ChargeV1ResponseType = "object"

const ChargeV1ResponseTypeArray ChargeV1ResponseType = "array"

const ChargeV1ResponseTypeError ChargeV1ResponseType = "error"

const ChargeV1ResponseTypeNone ChargeV1ResponseType = "none"