List paykeys

paykeys.list() -> SyncPageNumberSchema[Data]

get/v1/paykeys

Returns a list of paykeys associated with a Straddle account. This endpoint supports advanced sorting and filtering options.

ParametersExpand Collapse

customer_id: Optional[str]

Filter paykeys by related customer ID.

formatuuid

page_number: Optional[int]

Page number for paginated results. Starts at 1.

formatint32

page_size: Optional[int]

Number of results per page. Maximum: 1000.

formatint32

sort_by: Optional[Literal["institution_name", "expires_at", "created_at"]]

Accepts one of the following:

"institution_name"

"expires_at"

"created_at"

sort_order: Optional[Literal["asc", "desc"]]

Accepts one of the following:

"asc"

"desc"

source: Optional[List[Literal["bank_account", "straddle", "mx", 3 more]]]

Filter paykeys by their source.

Accepts one of the following:

"bank_account"

"straddle"

"mx"

"plaid"

"tan"

"quiltt"

status: Optional[List[Literal["pending", "active", "inactive", 3 more]]]

Filter paykeys by their current status.

Accepts one of the following:

"pending"

"active"

"inactive"

"rejected"

"review"

"blocked"

unblock_eligible: Optional[bool]

Filter paykeys by unblock eligibility. When true, returns only blocked paykeys eligible for client-initiated unblocking (blocked due to R29 returns and not previously unblocked). When false, returns only blocked paykeys that are not eligible for unblocking.

correlation_id: Optional[str]

request_id: Optional[str]

straddle_account_id: Optional[str]

ReturnsExpand Collapse

Data

id: str

Unique identifier for the paykey.

formatuuid

config: DataConfig

processing_method: Optional[Literal["inline", "background", "skip"]]

Accepts one of the following:

"inline"

"background"

"skip"

sandbox_outcome: Optional[Literal["standard", "active", "rejected", "review"]]

Accepts one of the following:

"standard"

"active"

"rejected"

"review"

created_at: datetime

Timestamp of when the paykey was created.

formatdate-time

label: str

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

paykey: str

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

source: Literal["bank_account", "straddle", "mx", 3 more]

Accepts one of the following:

"bank_account"

"straddle"

"mx"

"plaid"

"tan"

"quiltt"

status: Literal["pending", "active", "inactive", 3 more]

Accepts one of the following:

"pending"

"active"

"inactive"

"rejected"

"review"

"blocked"

updated_at: datetime

Timestamp of the most recent update to the paykey.

formatdate-time

bank_data: Optional[DataBankData]

account_number: str

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

account_type: Literal["checking", "savings"]

Accepts one of the following:

"checking"

"savings"

routing_number: str

The routing number of the bank account.

minLength9

maxLength9

customer_id: Optional[str]

Unique identifier of the related customer object.

formatuuid

expires_at: Optional[datetime]

Expiration date and time of the paykey, if applicable.

formatdate-time

external_id: Optional[str]

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

institution_name: Optional[str]

Name of the financial institution.

status_details: Optional[DataStatusDetails]

changed_at: datetime

The time the status change occurred.

formatdate-time

message: str

A human-readable description of the current status.

reason: Literal["insufficient_funds", "closed_bank_account", "invalid_bank_account", 22 more]

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"

"cancel_request"

"failed_verification"

"require_review"

"blocked_by_system"

"watchtower_review"

source: Literal["watchtower", "bank_decline", "customer_dispute", 2 more]

Accepts one of the following:

"watchtower"

"bank_decline"

"customer_dispute"

"user_action"

"system"

code: Optional[str]

The status code if applicable.

unblock_eligible: Optional[bool]

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.

List paykeys

from straddle import Straddle

client = Straddle(
    api_key="My API Key",
)
page = client.paykeys.list()
page = page.data[0]
print(page.id)

{
  "data": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "config": {
        "processing_method": "inline",
        "sandbox_outcome": "standard"
      },
      "created_at": "2019-12-27T18:11:19.117Z",
      "label": "Bank of America ****1234",
      "paykey": "paykey",
      "source": "bank_account",
      "status": "pending",
      "updated_at": "2019-12-27T18:11:19.117Z",
      "bank_data": {
        "account_number": "****1234",
        "account_type": "checking",
        "routing_number": "021000021"
      },
      "customer_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "expires_at": "2019-12-27T18:11:19.117Z",
      "external_id": "external_id",
      "institution_name": "Bank of America",
      "status_details": {
        "changed_at": "2019-12-27T18:11:19.117Z",
        "message": "Bank account sucesfully validated",
        "reason": "insufficient_funds",
        "source": "watchtower",
        "code": "code"
      },
      "unblock_eligible": true
    }
  ],
  "meta": {
    "api_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "api_request_timestamp": "2019-12-27T18:11:19.117Z",
    "max_page_size": 0,
    "page_number": 0,
    "page_size": 0,
    "sort_by": "sort_by",
    "sort_order": "asc",
    "total_items": 0,
    "total_pages": 0
  },
  "response_type": "object"
}

Returns Examples

{
  "data": [
    {
      "id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "config": {
        "processing_method": "inline",
        "sandbox_outcome": "standard"
      },
      "created_at": "2019-12-27T18:11:19.117Z",
      "label": "Bank of America ****1234",
      "paykey": "paykey",
      "source": "bank_account",
      "status": "pending",
      "updated_at": "2019-12-27T18:11:19.117Z",
      "bank_data": {
        "account_number": "****1234",
        "account_type": "checking",
        "routing_number": "021000021"
      },
      "customer_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "expires_at": "2019-12-27T18:11:19.117Z",
      "external_id": "external_id",
      "institution_name": "Bank of America",
      "status_details": {
        "changed_at": "2019-12-27T18:11:19.117Z",
        "message": "Bank account sucesfully validated",
        "reason": "insufficient_funds",
        "source": "watchtower",
        "code": "code"
      },
      "unblock_eligible": true
    }
  ],
  "meta": {
    "api_request_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
    "api_request_timestamp": "2019-12-27T18:11:19.117Z",
    "max_page_size": 0,
    "page_number": 0,
    "page_size": 0,
    "sort_by": "sort_by",
    "sort_order": "asc",
    "total_items": 0,
    "total_pages": 0
  },
  "response_type": "object"
}