List paykeys

client.paykeys.list(?, ?): PageNumberSchema<Data { id, config, created_at, 12 more } >

get/v1/paykeys

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

ParametersExpand Collapse

params: PaykeyListParams { customer_id, page_number, page_size, 8 more }

customer_id?: string

Query param: Filter paykeys by related customer ID.

formatuuid

page_number?: number

Query param: Page number for paginated results. Starts at 1.

formatint32

page_size?: number

Query param: Number of results per page. Maximum: 1000.

formatint32

sort_by?: "institution_name" | "expires_at" | "created_at"

Query param:

Accepts one of the following:

"institution_name"

"expires_at"

"created_at"

sort_order?: "asc" | "desc"

Query param:

Accepts one of the following:

"asc"

"desc"

source?: Array<"bank_account" | "straddle" | "mx" | 3 more>

Query param: Filter paykeys by their source.

Accepts one of the following:

"bank_account"

"straddle"

"mx"

"plaid"

"tan"

"quiltt"

status?: Array<"pending" | "active" | "inactive" | 3 more>

Query param: Filter paykeys by their current status.

Accepts one of the following:

"pending"

"active"

"inactive"

"rejected"

"review"

"blocked"

unblock_eligible?: boolean

Query param: 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.

correlationID?: string

Header param: Optional client generated identifier to trace and debug a series of requests.

requestID?: string

Header param: Optional client generated identifier to trace and debug a request.

straddleAccountID?: string

Header param: For use by platforms to specify an account id and set scope of a request.

formatuuid

ReturnsExpand Collapse

Data { id, config, created_at, 12 more }

id: string

Unique identifier for the paykey.

formatuuid

config: Config { processing_method, sandbox_outcome }

processing_method?: "inline" | "background" | "skip"

Accepts one of the following:

"inline"

"background"

"skip"

sandbox_outcome?: "standard" | "active" | "rejected" | "review"

Accepts one of the following:

"standard"

"active"

"rejected"

"review"

created_at: string

Timestamp of when the paykey was created.

formatdate-time

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" | "straddle" | "mx" | 3 more

Accepts one of the following:

"bank_account"

"straddle"

"mx"

"plaid"

"tan"

"quiltt"

status: "pending" | "active" | "inactive" | 3 more

Accepts one of the following:

"pending"

"active"

"inactive"

"rejected"

"review"

"blocked"

updated_at: string

Timestamp of the most recent update to the paykey.

formatdate-time

bank_data?: BankData { 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" | "savings"

Accepts one of the following:

"checking"

"savings"

routing_number: string

The routing number of the bank account.

minLength9

maxLength9

customer_id?: string | null

Unique identifier of the related customer object.

formatuuid

expires_at?: string | null

Expiration date and time of the paykey, if applicable.

formatdate-time

external_id?: string | null

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

institution_name?: string | null

Name of the financial institution.

status_details?: StatusDetails { changed_at, message, reason, 2 more }

changed_at: string

The time the status change occurred.

formatdate-time

message: string

A human-readable description of the current status.

reason: "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: "watchtower" | "bank_decline" | "customer_dispute" | 2 more

Accepts one of the following:

"watchtower"

"bank_decline"

"customer_dispute"

"user_action"

"system"

code?: string | null

The status code if applicable.

unblock_eligible?: boolean | null

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

import Straddle from '@straddlecom/straddle';

const client = new Straddle({
  apiKey: 'My API Key',
});

// Automatically fetches more pages as needed.
for await (const paykey of client.paykeys.list()) {
  console.log(paykey.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"
}