Skip to content
straddle API Docs
Get started
API Reference
Embed

Accounts

Accounts represent businesses using Straddle through your platform. Each account must complete automated verification before processing payments. Use accounts to manage your users' payment capabilities, track verification status, and control access to features. Accounts can be instantly created in sandbox and require additional verification for production access.

Lookup an account
AccountV1 Embed.Accounts.Get(AccountGetParamsparameters, CancellationTokencancellationToken = default)
GET/v1/accounts/{account_id}
Update an account
AccountV1 Embed.Accounts.Update(AccountUpdateParamsparameters, CancellationTokencancellationToken = default)
PUT/v1/accounts/{account_id}
Create an account
AccountV1 Embed.Accounts.Create(AccountCreateParamsparameters, CancellationTokencancellationToken = default)
POST/v1/accounts
List accounts
AccountPagedV1 Embed.Accounts.List(AccountListParams?parameters, CancellationTokencancellationToken = default)
GET/v1/accounts
Onboard an account
AccountV1 Embed.Accounts.Onboard(AccountOnboardParamsparameters, CancellationTokencancellationToken = default)
POST/v1/accounts/{account_id}/onboard
Simulate status transitions for a sandbox account
AccountV1 Embed.Accounts.Simulate(AccountSimulateParamsparameters, CancellationTokencancellationToken = default)
POST/v1/accounts/{account_id}/simulate
ModelsExpand Collapse
class AccountPagedV1:
required IReadOnlyList<Data> Data
required string ID

Unique identifier for the account.

formatuuid
required AccessLevel AccessLevel

The access level granted to the account. This is determined by your platform configuration. Use standard unless instructed otherwise by Straddle.

One of the following:
"standard"Standard
"managed"Managed
required string OrganizationID

The unique identifier of the organization this account belongs to.

formatuuid
required Status Status

The current status of the account (e.g., 'active', 'inactive', 'pending').

One of the following:
"created"Created
"onboarding"Onboarding
"active"Active
"rejected"Rejected
"inactive"Inactive
required StatusDetail StatusDetail
required string Code

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

required string Message

A human-readable message describing the current status.

required Reason Reason

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

One of the following:
"unverified"Unverified
"in_review"InReview
"pending"Pending
"stuck"Stuck
"verified"Verified
"failed_verification"FailedVerification
"disabled"Disabled
"terminated"Terminated
"new"New
required Source Source

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

required Type Type

The type of account (e.g., 'individual', 'business').

BusinessProfileV1 BusinessProfile
required string Name

The operating or trade name of the business.

required string Website

URL of the business's primary marketing website.

formaturi
AddressV1? Address

The address object is optional. If provided, it must be a valid address.

required string? City

City, district, suburb, town, or village.

required string? Line1

Primary address line (e.g., street, PO Box).

required string? PostalCode

Postal or ZIP code.

required string? State

Two-letter state code.

string? Country

The country of the address, in ISO 3166-1 alpha-2 format.

string? Line2

Secondary address line (e.g., apartment, suite, unit, or building).

string? Description

A brief description of the business and its products or services.

IndustryV1 Industry
string? Category

The general category of the industry. Required if not providing MCC.

string? Mcc

The Merchant Category Code (MCC) that best describes the business. Optional.

string? Sector

The specific sector within the industry category. Required if not providing MCC.

The official registered name of the business.

string? Phone

The primary contact phone number for the business.

SupportChannelsV1 SupportChannels
string? Email

The email address for customer support inquiries.

formatemail
string? Phone

The phone number for customer support.

string? Url

The URL of the business's customer support page or contact form.

formaturi
string? TaxID

The business's tax identification number (e.g., EIN in the US).

string? UseCase

A description of how the business intends to use Straddle's services.

Capabilities Capabilities

Whether the internet payment authorization capability is enabled for the account.

One of the following:

Whether the signed agreement payment authorization capability is enabled for the account.

One of the following:
required CustomerTypes CustomerTypes
required CapabilityV1 Businesses
required CapabilityStatus CapabilityStatus
One of the following:
"active"Active
"inactive"Inactive
required CapabilityV1 Individuals
required CapabilityStatus CapabilityStatus
One of the following:
"active"Active
"inactive"Inactive
required PaymentTypes PaymentTypes
required CapabilityV1 Charges
required CapabilityStatus CapabilityStatus
One of the following:
"active"Active
"inactive"Inactive
required CapabilityV1 Payouts
required CapabilityStatus CapabilityStatus
One of the following:
"active"Active
"inactive"Inactive
DateTimeOffset? CreatedAt

Timestamp of when the account was created.

formatdate-time
string? ExternalID

Unique identifier for the account in your database, used for cross-referencing between Straddle and your systems.

IReadOnlyDictionary<string, string>? Metadata

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

Settings Settings
required Charges Charges
required Int DailyAmount

The maximum dollar amount of charges in a calendar day.

formatint32
required FundingTime FundingTime

The amount of time it takes for a charge to be funded. This value is defined by Straddle.

One of the following:
"immediate"Immediate
"next_day"NextDay
"one_day"OneDay
"two_day"TwoDay
"three_day"ThreeDay
"four_day"FourDay
"five_day"FiveDay
required string LinkedBankAccountID

The unique identifier of the linked bank account associated with charges. This value is defined by Straddle.

formatuuid
required Int MaxAmount

The maximum amount of a single charge.

formatint32
required Int MonthlyAmount

The maximum dollar amount of charges in a calendar month.

formatint32
required Int MonthlyCount

The maximum number of charges in a calendar month.

formatint32
required Payouts Payouts
required Int DailyAmount

The maximum dollar amount of payouts in a day.

formatint32
required FundingTime FundingTime

The amount of time it takes for a payout to be funded. This value is defined by Straddle.

One of the following:
"immediate"Immediate
"next_day"NextDay
"one_day"OneDay
"two_day"TwoDay
"three_day"ThreeDay
"four_day"FourDay
"five_day"FiveDay
required string LinkedBankAccountID

The unique identifier of the linked bank account to use for payouts.

formatuuid
required Int MaxAmount

The maximum amount of a single payout.

formatint32
required Int MonthlyAmount

The maximum dollar amount of payouts in a month.

formatint32
required Int MonthlyCount

The maximum number of payouts in a month.

formatint32
TermsOfServiceV1 TermsOfService
required DateTimeOffset AcceptedDate

The datetime of when the terms of service were accepted, in ISO 8601 format.

formatdate-time
required AgreementType AgreementType

The type or version of the agreement accepted. Use embedded unless your platform was specifically enabled for direct agreements.

One of the following:
"embedded"Embedded
"direct"Direct
required string? AgreementUrl

The URL where the full text of the accepted agreement can be found.

string? AcceptedIP

The IP address from which the terms of service were accepted.

string? AcceptedUserAgent

The user agent string of the browser or application used to accept the terms.

DateTimeOffset? UpdatedAt

Timestamp of the most recent update to the account.

formatdate-time
required PagedResponseMetadata Meta

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

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

Total number of items returned in this response.

formatint32
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
class AccountV1:
required Data Data
required string ID

Unique identifier for the account.

formatuuid
required AccessLevel AccessLevel

The access level granted to the account. This is determined by your platform configuration. Use standard unless instructed otherwise by Straddle.

One of the following:
"standard"Standard
"managed"Managed
required string OrganizationID

The unique identifier of the organization this account belongs to.

formatuuid
required Status Status

The current status of the account (e.g., 'active', 'inactive', 'pending').

One of the following:
"created"Created
"onboarding"Onboarding
"active"Active
"rejected"Rejected
"inactive"Inactive
required StatusDetail StatusDetail
required string Code

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

required string Message

A human-readable message describing the current status.

required Reason Reason

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

One of the following:
"unverified"Unverified
"in_review"InReview
"pending"Pending
"stuck"Stuck
"verified"Verified
"failed_verification"FailedVerification
"disabled"Disabled
"terminated"Terminated
"new"New
required Source Source

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

required Type Type

The type of account (e.g., 'individual', 'business').

BusinessProfileV1 BusinessProfile
required string Name

The operating or trade name of the business.

required string Website

URL of the business's primary marketing website.

formaturi
AddressV1? Address

The address object is optional. If provided, it must be a valid address.

required string? City

City, district, suburb, town, or village.

required string? Line1

Primary address line (e.g., street, PO Box).

required string? PostalCode

Postal or ZIP code.

required string? State

Two-letter state code.

string? Country

The country of the address, in ISO 3166-1 alpha-2 format.

string? Line2

Secondary address line (e.g., apartment, suite, unit, or building).

string? Description

A brief description of the business and its products or services.

IndustryV1 Industry
string? Category

The general category of the industry. Required if not providing MCC.

string? Mcc

The Merchant Category Code (MCC) that best describes the business. Optional.

string? Sector

The specific sector within the industry category. Required if not providing MCC.

The official registered name of the business.

string? Phone

The primary contact phone number for the business.

SupportChannelsV1 SupportChannels
string? Email

The email address for customer support inquiries.

formatemail
string? Phone

The phone number for customer support.

string? Url

The URL of the business's customer support page or contact form.

formaturi
string? TaxID

The business's tax identification number (e.g., EIN in the US).

string? UseCase

A description of how the business intends to use Straddle's services.

Capabilities Capabilities

Whether the internet payment authorization capability is enabled for the account.

One of the following:

Whether the signed agreement payment authorization capability is enabled for the account.

One of the following:
required CustomerTypes CustomerTypes
required CapabilityV1 Businesses
required CapabilityStatus CapabilityStatus
One of the following:
"active"Active
"inactive"Inactive
required CapabilityV1 Individuals
required CapabilityStatus CapabilityStatus
One of the following:
"active"Active
"inactive"Inactive
required PaymentTypes PaymentTypes
required CapabilityV1 Charges
required CapabilityStatus CapabilityStatus
One of the following:
"active"Active
"inactive"Inactive
required CapabilityV1 Payouts
required CapabilityStatus CapabilityStatus
One of the following:
"active"Active
"inactive"Inactive
DateTimeOffset? CreatedAt

Timestamp of when the account was created.

formatdate-time
string? ExternalID

Unique identifier for the account in your database, used for cross-referencing between Straddle and your systems.

IReadOnlyDictionary<string, string>? Metadata

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

Settings Settings
required Charges Charges
required Int DailyAmount

The maximum dollar amount of charges in a calendar day.

formatint32
required FundingTime FundingTime

The amount of time it takes for a charge to be funded. This value is defined by Straddle.

One of the following:
"immediate"Immediate
"next_day"NextDay
"one_day"OneDay
"two_day"TwoDay
"three_day"ThreeDay
"four_day"FourDay
"five_day"FiveDay
required string LinkedBankAccountID

The unique identifier of the linked bank account associated with charges. This value is defined by Straddle.

formatuuid
required Int MaxAmount

The maximum amount of a single charge.

formatint32
required Int MonthlyAmount

The maximum dollar amount of charges in a calendar month.

formatint32
required Int MonthlyCount

The maximum number of charges in a calendar month.

formatint32
required Payouts Payouts
required Int DailyAmount

The maximum dollar amount of payouts in a day.

formatint32
required FundingTime FundingTime

The amount of time it takes for a payout to be funded. This value is defined by Straddle.

One of the following:
"immediate"Immediate
"next_day"NextDay
"one_day"OneDay
"two_day"TwoDay
"three_day"ThreeDay
"four_day"FourDay
"five_day"FiveDay
required string LinkedBankAccountID

The unique identifier of the linked bank account to use for payouts.

formatuuid
required Int MaxAmount

The maximum amount of a single payout.

formatint32
required Int MonthlyAmount

The maximum dollar amount of payouts in a month.

formatint32
required Int MonthlyCount

The maximum number of payouts in a month.

formatint32
TermsOfServiceV1 TermsOfService
required DateTimeOffset AcceptedDate

The datetime of when the terms of service were accepted, in ISO 8601 format.

formatdate-time
required AgreementType AgreementType

The type or version of the agreement accepted. Use embedded unless your platform was specifically enabled for direct agreements.

One of the following:
"embedded"Embedded
"direct"Direct
required string? AgreementUrl

The URL where the full text of the accepted agreement can be found.

string? AcceptedIP

The IP address from which the terms of service were accepted.

string? AcceptedUserAgent

The user agent string of the browser or application used to accept the terms.

DateTimeOffset? UpdatedAt

Timestamp of the most recent update to the account.

formatdate-time
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
class AddressV1:

The address object is optional. If provided, it must be a valid address.

required string? City

City, district, suburb, town, or village.

required string? Line1

Primary address line (e.g., street, PO Box).

required string? PostalCode

Postal or ZIP code.

required string? State

Two-letter state code.

string? Country

The country of the address, in ISO 3166-1 alpha-2 format.

string? Line2

Secondary address line (e.g., apartment, suite, unit, or building).

class BusinessProfileV1:
required string Name

The operating or trade name of the business.

required string Website

URL of the business's primary marketing website.

formaturi
AddressV1? Address

The address object is optional. If provided, it must be a valid address.

required string? City

City, district, suburb, town, or village.

required string? Line1

Primary address line (e.g., street, PO Box).

required string? PostalCode

Postal or ZIP code.

required string? State

Two-letter state code.

string? Country

The country of the address, in ISO 3166-1 alpha-2 format.

string? Line2

Secondary address line (e.g., apartment, suite, unit, or building).

string? Description

A brief description of the business and its products or services.

IndustryV1 Industry
string? Category

The general category of the industry. Required if not providing MCC.

string? Mcc

The Merchant Category Code (MCC) that best describes the business. Optional.

string? Sector

The specific sector within the industry category. Required if not providing MCC.

The official registered name of the business.

string? Phone

The primary contact phone number for the business.

SupportChannelsV1 SupportChannels
string? Email

The email address for customer support inquiries.

formatemail
string? Phone

The phone number for customer support.

string? Url

The URL of the business's customer support page or contact form.

formaturi
string? TaxID

The business's tax identification number (e.g., EIN in the US).

string? UseCase

A description of how the business intends to use Straddle's services.

class CapabilityV1:
required CapabilityStatus CapabilityStatus
One of the following:
"active"Active
"inactive"Inactive
class IndustryV1:
string? Category

The general category of the industry. Required if not providing MCC.

string? Mcc

The Merchant Category Code (MCC) that best describes the business. Optional.

string? Sector

The specific sector within the industry category. Required if not providing MCC.

class SupportChannelsV1:
string? Email

The email address for customer support inquiries.

formatemail
string? Phone

The phone number for customer support.

string? Url

The URL of the business's customer support page or contact form.

formaturi
class TermsOfServiceV1:
required DateTimeOffset AcceptedDate

The datetime of when the terms of service were accepted, in ISO 8601 format.

formatdate-time
required AgreementType AgreementType

The type or version of the agreement accepted. Use embedded unless your platform was specifically enabled for direct agreements.

One of the following:
"embedded"Embedded
"direct"Direct
required string? AgreementUrl

The URL where the full text of the accepted agreement can be found.

string? AcceptedIP

The IP address from which the terms of service were accepted.

string? AcceptedUserAgent

The user agent string of the browser or application used to accept the terms.

AccountsCapability Requests

Capabilities enable specific features and services for an Account. Use capability requests to unlock higher processing limits, new payment types, or additional platform features as your users' businesses grow. Track approval status and manage documentation requirements through a single interface.

Request a capability
CapabilityRequestPagedV1 Embed.Accounts.CapabilityRequests.Create(CapabilityRequestCreateParamsparameters, CancellationTokencancellationToken = default)
POST/v1/accounts/{account_id}/capability_requests
List capability requests
CapabilityRequestPagedV1 Embed.Accounts.CapabilityRequests.List(CapabilityRequestListParamsparameters, CancellationTokencancellationToken = default)
GET/v1/accounts/{account_id}/capability_requests
ModelsExpand Collapse
class CapabilityRequestPagedV1:
required IReadOnlyList<Data> Data
required string ID

Unique identifier for the capability request.

formatuuid
required string AccountID

The unique identifier of the account associated with this capability request.

formatuuid
required Category Category

The category of the requested capability. Use payment_type for charges and payouts, customer_type to define individuals or businesses, and consent_type for signed_agreement or internet payment authorization.

One of the following:
"payment_type"PaymentType
"customer_type"CustomerType
"consent_type"ConsentType
required DateTimeOffset CreatedAt

Timestamp of when the capability request was created.

formatdate-time
required Boolean Enable

Whether this capability request is to enable or disable the capability.

required Status Status

The current status of the capability request.

One of the following:
"active"Active
"inactive"Inactive
"in_review"InReview
"rejected"Rejected
"approved"Approved
"reviewing"Reviewing
required Type Type

The specific type of capability being requested within the category.

One of the following:
"charges"Charges
"payouts"Payouts
"individuals"Individuals
"businesses"Businesses
"signed_agreement"SignedAgreement
"internet"Internet
required DateTimeOffset UpdatedAt

Timestamp of the most recent update to the capability request.

formatdate-time
IReadOnlyDictionary<string, JsonElement>? Settings

Any specific settings or configurations related to the requested capability.

required PagedResponseMetadata Meta

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

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

Total number of items returned in this response.

formatint32
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