Skip to content
straddle API Docs
Get started
API Reference

Paykeys

Paykeys are secure tokens that link verified customer identities to their bank accounts. Each Paykey includes built-in balance checking, fraud detection through LSTM machine learning models, and can be reused for subscriptions and recurring payments without storing sensitive data. Paykeys eliminate fraud by ensuring the person initiating payment owns the funding account.

Lookup a paykey
$ straddle paykeys get
GET/v1/paykeys/{id}
Unmask a paykey
$ straddle paykeys unmasked
GET/v1/paykeys/{id}/unmasked
List paykeys
$ straddle paykeys list
GET/v1/paykeys
Retrieve an unmasked paykey token
$ straddle paykeys reveal
GET/v1/paykeys/{id}/reveal
Cancel
$ straddle paykeys cancel
PUT/v1/paykeys/{id}/cancel
Update a paykey's balance
$ straddle paykeys update-balance
PUT/v1/paykeys/{id}/refresh_balance
ModelsExpand Collapse
paykeySummaryPagedV1: object { data, meta, response_type }
data: array of object { id, config, created_at, 12 more }
id: string

Unique identifier for the paykey.

config: object { processing_method, sandbox_outcome }
processing_method: optional "inline" or "background" or "skip"
"inline"
"background"
"skip"
sandbox_outcome: optional "standard" or "active" or "rejected" or "review"
"standard"
"active"
"rejected"
"review"
created_at: string

Timestamp of when the paykey was created.

label: string

Human-readable label that combines the bank name and masked account number to help easility represent this paykey in a UI

paykey: string

The tokenized paykey value. This value is used to create payments and should be stored securely.

source: "bank_account" or "straddle" or "mx" or 3 more
"bank_account"
"straddle"
"mx"
"plaid"
"tan"
"quiltt"
status: "pending" or "active" or "inactive" or 3 more
"pending"
"active"
"inactive"
"rejected"
"review"
"blocked"
updated_at: string

Timestamp of the most recent update to the paykey.

bank_data: optional object { account_number, account_type, routing_number }
account_number: string

Bank account number. This value is masked by default for security reasons. Use the /unmask endpoint to access the unmasked value.

account_type: "checking" or "savings"
"checking"
"savings"
routing_number: string

The routing number of the bank account.

customer_id: optional string

Unique identifier of the related customer object.

expires_at: optional string

Expiration date and time of the paykey, if applicable.

external_id: optional string

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

institution_name: optional string

Name of the financial institution.

status_details: optional object { changed_at, message, reason, 2 more }
changed_at: string

The time the status change occurred.

message: string

A human-readable description of the current status.

reason: "insufficient_funds" or "closed_bank_account" or "invalid_bank_account" or 24 more
"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"
"cancel_request"
"failed_verification"
"require_review"
"blocked_by_system"
"watchtower_review"
"validating"
"auto_hold"
source: "watchtower" or "bank_decline" or "customer_dispute" or 2 more
"watchtower"
"bank_decline"
"customer_dispute"
"user_action"
"system"
code: optional string

The status code if applicable.

unblock_eligible: optional boolean

Indicates whether this paykey is eligible for client-initiated unblocking. Only present for blocked paykeys. True when blocked due to R29 returns and not previously unblocked, false otherwise. Null when paykey is not blocked.

meta: object { api_request_id, api_request_timestamp, max_page_size, 6 more }
api_request_id: string

Unique identifier for this API request, useful for troubleshooting.

api_request_timestamp: string

Timestamp for this API request, useful for troubleshooting.

max_page_size: number

Maximum allowed page size for this endpoint.

page_number: number

Page number for paginated results.

page_size: number

Number of items per page in this response.

sort_by: string

The field that the results were sorted by.

sort_order: "asc" or "desc"
"asc"
"desc"
total_items: number
total_pages: number

The number of pages available.

response_type: "object" or "array" or "error" or "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.
"object"
"array"
"error"
"none"
paykeyUnmaskedV1: object { data, meta, response_type }
data: object { id, config, created_at, 13 more }
id: string

Unique identifier for the paykey.

config: object { processing_method, sandbox_outcome }
processing_method: optional "inline" or "background" or "skip"
"inline"
"background"
"skip"
sandbox_outcome: optional "standard" or "active" or "rejected" or "review"
"standard"
"active"
"rejected"
"review"
created_at: string

Timestamp of when the paykey was created.

label: string

Human-readable label used to represent this paykey in a UI.

paykey: string

The tokenized paykey value. This value is used to create payments and should be stored securely.

source: "bank_account" or "straddle" or "mx" or 3 more
"bank_account"
"straddle"
"mx"
"plaid"
"tan"
"quiltt"
status: "pending" or "active" or "inactive" or 3 more
"pending"
"active"
"inactive"
"rejected"
"review"
"blocked"
updated_at: string

Timestamp of the most recent update to the paykey.

balance: optional object { status, account_balance, updated_at }
status: "pending" or "completed" or "failed"
"pending"
"completed"
"failed"
account_balance: optional number

Account Balance when last retrieved

updated_at: optional string

Last time account balance was updated.

bank_data: optional object { account_number, account_type, routing_number }
account_number: string

The bank account number

account_type: "checking" or "savings"
"checking"
"savings"
routing_number: string

The routing number of the bank account.

customer_id: optional string

Unique identifier of the related customer object.

expires_at: optional string

Expiration date and time of the paykey, if applicable.

external_id: optional string

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

institution_name: optional string

Name of the financial institution.

metadata: optional map[string]

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

status_details: optional object { changed_at, message, reason, 2 more }
changed_at: string

The time the status change occurred.

message: string

A human-readable description of the current status.

reason: "insufficient_funds" or "closed_bank_account" or "invalid_bank_account" or 24 more
"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"
"cancel_request"
"failed_verification"
"require_review"
"blocked_by_system"
"watchtower_review"
"validating"
"auto_hold"
source: "watchtower" or "bank_decline" or "customer_dispute" or 2 more
"watchtower"
"bank_decline"
"customer_dispute"
"user_action"
"system"
code: optional string

The status code if applicable.

meta: object { 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.

api_request_timestamp: string

Timestamp for this API request, useful for troubleshooting.

response_type: "object" or "array" or "error" or "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.
"object"
"array"
"error"
"none"
paykeyV1: object { data, meta, response_type }
data: object { id, config, created_at, 14 more }
id: string

Unique identifier for the paykey.

config: object { processing_method, sandbox_outcome }
processing_method: optional "inline" or "background" or "skip"
"inline"
"background"
"skip"
sandbox_outcome: optional "standard" or "active" or "rejected" or "review"
"standard"
"active"
"rejected"
"review"
created_at: string

Timestamp of when the paykey was created.

label: string

Human-readable label used to represent this paykey in a UI.

paykey: string

The tokenized paykey value. This value is used to create payments and should be stored securely.

source: "bank_account" or "straddle" or "mx" or 3 more
"bank_account"
"straddle"
"mx"
"plaid"
"tan"
"quiltt"
status: "pending" or "active" or "inactive" or 3 more
"pending"
"active"
"inactive"
"rejected"
"review"
"blocked"
updated_at: string

Timestamp of the most recent update to the paykey.

balance: optional object { status, account_balance, updated_at }
status: "pending" or "completed" or "failed"
"pending"
"completed"
"failed"
account_balance: optional number

Account Balance when last retrieved

updated_at: optional string

Last time account balance was updated.

bank_data: optional object { account_number, account_type, routing_number }
account_number: string

Bank account number. This value is masked by default for security reasons. Use the /unmask endpoint to access the unmasked value.

account_type: "checking" or "savings"
"checking"
"savings"
routing_number: string

The routing number of the bank account.

customer_id: optional string

Unique identifier of the related customer object.

expires_at: optional string

Expiration date and time of the paykey, if applicable.

external_id: optional string

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

institution_name: optional string

Name of the financial institution.

metadata: optional map[string]

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

status_details: optional object { changed_at, message, reason, 2 more }
changed_at: string

The time the status change occurred.

message: string

A human-readable description of the current status.

reason: "insufficient_funds" or "closed_bank_account" or "invalid_bank_account" or 24 more
"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"
"cancel_request"
"failed_verification"
"require_review"
"blocked_by_system"
"watchtower_review"
"validating"
"auto_hold"
source: "watchtower" or "bank_decline" or "customer_dispute" or 2 more
"watchtower"
"bank_decline"
"customer_dispute"
"user_action"
"system"
code: optional string

The status code if applicable.

unblock_eligible: optional boolean

Indicates whether this paykey is eligible for client-initiated unblocking. Only present for blocked paykeys. True when blocked due to R29 returns and not previously unblocked, false otherwise. Null when paykey is not blocked.

meta: object { 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.

api_request_timestamp: string

Timestamp for this API request, useful for troubleshooting.

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

PaykeysReview

Paykeys are secure tokens that link verified customer identities to their bank accounts. Each Paykey includes built-in balance checking, fraud detection through LSTM machine learning models, and can be reused for subscriptions and recurring payments without storing sensitive data. Paykeys eliminate fraud by ensuring the person initiating payment owns the funding account.

Update a paykey's status
$ straddle paykeys:review decision
PATCH/v1/paykeys/{id}/review
Get paykey review details
$ straddle paykeys:review get
GET/v1/paykeys/{id}/review
Update a paykey's identity review decision
$ straddle paykeys:review refresh-review
PUT/v1/paykeys/{id}/refresh_review