Paykeys are a cornerstone of Straddle’s Pay by Bank stack. They are secure tokens that represent a customer’s verified identity and their bank account. The creation of a Paykey involves advanced identity matching through Straddle’s proprietary name matching algorithm (WALDO). This algorithm compares the customer’s known identity (obtained via Straddle ID) with the account ownership details retrieved from the customer’s financial institution through open banking. This ensures that the individual initiating the payment is the legitimate owner of the bank account, significantly reducing the risk of fraud. This guide explores how Paykeys work, the security measures in place, and how they integrate with other components of the Straddle ecosystem to facilitate secure payments.

Real-Time Identity Matching

Verifies that the customer connecting the bank account is its legitimate owner

Advanced Data Handling

Manages variations in PII, such as typos, nicknames, and cultural naming conventions

Fraud Detection

Identifies and prevents potential fraudulent activities before they occur.

Always Compliant

Embeds regulatory compliance checks into the bank verification process

How Bridge Creates Paykeys

Bridge is Straddle’s connectivity platform that securely links customers’ bank accounts to your application. When a customer connects their bank account through Bridge, a Paykey is generated to securely represent this connection. Here’s how the process works:

Customer Identity Verification

Before connecting a bank account, the customer is onboarded and their identity is verified using Straddle ID. This ensures compliance with KYC (Know Your Customer) and AML (Anti-Money Laundering) regulations.

Bank Account Connection via Bridge

Bridge Widget

Third-Party Tokens

Alternatively, Bridge accepts existing tokens from providers like Plaid, MX, or Finicity, leveraging customers’ pre-existing bank connections.

Manual Bank Entry

Paykeys name matching is also possible with manual bank entry.

Identity Matching with WALDO

is Bridge’s proprietary algorithm for verifying bank account ownership.

Data Comparison

WALDO compares the customer’s verified identity with the bank account ownership details

Handling Variations

The algorithm accounts for minor discrepancies, such as nicknames, middle names, typos, and cultural naming conventions.

Fraud Prevention

Prevent fraudulent activities and unauthorized access to bank accounts.

Real-Time Processing

The verification occurs instantly in the API response

Paykey Generation and Status Assignment

Unique Identifier Creation

A Universally Unique Identifier (UUID) is generated to represent the link between the customer and their bank account.

Hashing and Encoding

The UUID is hashed using a cryptographic hash function (BLAKE3) to ensure it cannot be reverse-engineered. The hashed value is encoded (e.g., Base64 or URL-safe encoding) to produce the Paykey.

Paykey Structure

The result is a secure, unique token (the Paykey) that represents the customer-bank account linkage.

Status Determination

Based on WALDO’s verification results, the paykey is assigned an initial status:

active
rejected
review (requires manual review)

Secure Delivery of the Paykey

The Paykey object is securely returned to your application. It includes the paykey, masked bank account details, the available balance, and the current verification status.

Storage and Usage

Secure Storage

Your application never has to transmit PII or bank account details to Straddle.

Payment Initiation

The Paykey authorizes payments without exposing sensitive details.

By integrating Bridge and utilizing the WALDO algorithm to create Paykeys, you provide a secure and efficient way to process payments, enhancing both security and user experience.

Paykey Object Definition

The Paykey object represents a secure, tokenized link between a customer and their bank account. It is used to authorize payments without exposing sensitive financial information.

Paykey Attributes

Field	Type	Description
`id`	string	Unique identifier for the paykey, generated by Straddle.
`customer_id`	string	Unique identifier of the customer associated with this paykey.
`label`	string	Human-readable label for the paykey, often including the bank name and masked account number.
`source`	string	Method used to create the paykey (e.g., `bank_account`, `plaid`, `mx`, `straddle`).
`institution_name`	string	Name of the financial institution associated with the paykey.
`status`	string	Current status of the paykey (`pending`, `active`, `inactive`, `rejected`, `review`).
`status_details`	object	Additional information about the paykey’s status.
↳ `message`	string	A human-readable description of the current status.
↳ `reason`	string	A machine-readable identifier for the specific status.
↳ `source`	string	Identifies the origin of the status change (e.g., ‘bank_decline’, ‘system’).
`paykey`	string	The tokenized paykey value used for transactions.
`bank_data`	object	Masked bank account details associated with the paykey.
↳ `routing_number`	string	The bank’s routing number.
↳ `account_number`	string	The masked bank account number (e.g., “******1234”).
↳ `account_type`	string	The type of bank account (e.g., “checking” or “savings”).
`balance`	integer	The available balance of the linked account in cents, if available.
`metadata`	object	User-defined key-value pairs for storing additional information about the paykey.
`expires_at`	datetime	Expiration date and time of the paykey, if applicable.
`created_at`	datetime	Timestamp of when the paykey was created.
`updated_at`	datetime	Timestamp of the most recent update to the paykey.

Verification Results

On paykey creation, we perform name matching and determine whether the bank account is open and ready for transactions. The verification data we use to evaluate each paykey can be retrieved from the /paykeys/{id}/review endpoint. Use these insights to help you decide whether to accept or reject paykeys in review status, or to cancel active paykeys if needed.

Review Attributes

Field	Type	Description
`id`	string	Unique identifier for this verification record.
`decision`	string	Overall verification decision (`accept`, `review`, or `reject`).
`messages`	object	Key-value pairs of verification codes and their human-readable descriptions.
`breakdown`	object	Detailed results for each verification check performed.
↳ `name_match`	object	Results from comparing the customer name to the matched name on the account. *These fields will be null when an account is linked using account and routing number only.
↳ `names_on_account`	array	List of account holder names retrieved from the bank.
↳ `matched_name`	string	The name from the account that was compared to the customer name.
↳ `customer_name`	string	The customer’s name.
↳ `correlation_score`	number	Numerical score representing name similarity (0-100).
↳ `decision`	string	Decision for this check (`accept`, `review`, or `reject`).
↳ `reason`	string	Human-readable explanation for the decision.
↳ `codes`	array	List of verification codes related to this check (e.g., `NM01`).
↳ `account_validation`	object	Results from account validation checks. *These fields will be null when open banking tokens are used.
↳ `decision`	string	Decision for this check (`accept`, `review`, or `reject`).
↳ `reason`	string	Human-readable explanation for the decision (empty if accepted).
↳ `codes`	array	List of verification codes related to this check.
↳ `created_at`	datetime	Timestamp of when the verification was performed.
↳ `updated_at`	datetime	Timestamp of the most recent update to the verification record.
`meta`	object	Request metadata.
↳ `api_request_id`	string	Unique identifier for this API request.
↳ `api_request_timestamp`	datetime	Timestamp of when the API request was processed.
`response_type`	string	Type of response returned (typically `object`).

Paykey Status Details

Status	Description
`pending`	Initial status when the paykey is created and awaiting verification, or when reprocessing is triggered.
`active`	Paykey has been verified and is ready for use in transactions.
`review`	Paykey requires manual review due to verification issues (e.g., name variations).
`inactive`	Paykey is no longer active and cannot be used for transactions.
`rejected`	Paykey failed verification or was rejected by the financial institution.

Notes

The account_number in the bank_data object is always masked for security reasons. Use the unmasked paykey data endpoint to access the full account number when necessary and authorized.
The balance field is only available for certain integration types and may not always be present.
The source field indicates the method used to create the paykey, which can affect the available features and verification process.
The metadata object can contain up to 20 key-value pairs, each with a maximum length of 40 characters for keys and 500 characters for values.
The created_at and updated_at fields are automatically managed by Straddle and cannot be modified directly.
The expires_at field is only applicable for certain types of paykeys and integration methods.
Paykeys in review status can be manually approved or rejected via PATCH /paykeys/{id}/review.
Use GET /paykeys/{id}/review (or confirm if different endpoint) to retrieve verification details.

Example Paykey Object

{
  "id": "pk_1234567890abcdef",
  "customer_id": "cus_9876543210fedcba",
  "label": "Chase Checking (...1234)",
  "source": "bank_account",
  "institution_name": "Chase",
  "status": "active",
  "status_details": {
    "message": "Paykey is active and ready for use",
    "reason": "verified",
    "source": "system"
  },
  "expires_at": "2024-12-31T23:59:59Z",
  "created_at": "2023-06-15T10:30:00Z",
  "updated_at": "2023-06-15T10:30:00Z",
  "paykey": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
  "bank_data": {
    "routing_number": "123456789",
    "account_number": "******1234",
    "account_type": "checking"
  },
  "metadata": {
    "user_id": "user_5678",
    "account_nickname": "My Primary Checking"
  }
}

Paykey Verification and Manual Review

When a paykey is created, it goes through an automated verification process that can result in one of three decisions:

Accept

Immediate ApprovalThe paykey passes all verification checks and is ready for use in payments immediately.

Review

Manual Review RequiredThe paykey has verification issues (e.g., name variations) that require human review before approval.

Reject

Verification FailedThe paykey fails verification due to significant issues and cannot be used for payments.

Verification Codes and their Meaning

A paykey’s verification decision and status are determined by the codes it receives during processing. If any rejection code is present, the paykey will be rejected regardless of other successful verification results. Other codes result in the paykey status being transitioned to review. Paykeys that pass verification will become active.

Paykeys must be in review status to have their verification outcome modified.

Review Codes

Straddle Code	Meaning
NM01	Account Holder is not a match for Customer.

Rejection Codes

Straddle Code	Meaning
BR101	The bank account is either closed, invalid, or in a negative status
BR102	The bank account is either ineligible for debit activity or deemed to have a high probability of return
BR104	The bank account owner’s information does not match with the information provided
BR105	The bank account requested for verification has not been contributed by the participant bank
BR106	The bank account has been closed as a result of unacceptable use by the customer
BR107	The bank account has been removed from the Contributor’s source
BR108	The bank account will not accept any debit activity
BR109	The bank account has been closed and removed from the Contributor’s source
BR110	The bank account is closed in the last processing cycle
BR111	The bank account has a history of available balance being less than zero
BR112	The bank account provided is not a demand deposit account (non-DDA account)
BR113	The bank account has a high probability of return
BR114	Likely an invalid account number/routing number
BR115	Bank account owner information does not match with the information provided (open banking)
BR116	Bank Data Provider returned invalid owner information error
BR117	Bank Data Provider returned invalid length for account number and routing number error
BR119	The bank account owner’s DOB doesn’t match with the bank data provider
BR120	The bank account owner’s SSN or tax ID doesn’t match with the bank data provider

Manual Review Process

Manual paykey review gives you control over verification decisions. When a paykey has a review status, you can evaluate verification details and make informed decisions about whether to approve or reject the paykey—either through the dashboard or programmatically. This helps you prevent fraudulent accounts, manage risk, and ensure only legitimate payment methods are activated on your platform. You can view all paykeys requiring review at the bottom of the Overview page, or update their status programmatically using the review endpoint:

Review Details: Access detailed verification information that may include names on the bank account and matched name in the dashboard or retrieve it from the review endpoint.
Manual Decision: Resolve the paykey status by setting it to active or rejected.
Retry Verification: Optionally refresh the verification process to re-evaluate the paykey.

The review process ensures that edge cases and minor discrepancies don’t automatically reject legitimate paykeys, while maintaining security standards.

Payment Processing During Paykey Review Payments are held while paykeys are under review. All transactions associated with a paykey in review status will be held until the paykey is either approved or rejected. Review paykeys promptly to avoid payment backlogs. Delayed reviews can cause multiple payments to queue up and process simultaneously once the paykey is approved. This can result in unexpected batch processing of charges or payouts for a single account. Paykey Review Response Sample responses from the /paykeys/{id}/review endpoint.

Accounts linked via open banking will show null for account validation details because validation is performed by the open banking provider. However, the same validation checks are still conducted—they’re just handled upstream by the provider rather than Straddle.

        {
          "data": {
            "paykey_details": {...},
            "verification_details": {
              "id": "019a1743-d6db-7771-8f7f-09e43a08d1c8",
              "decision": "accept",
              "messages": {},
              "breakdown": {
                "name_match": {
                  "decision": "accept",
                  "reason": "Successfully matched account holder with customer.",
                  "codes": [],
                  "matched_name": "John Michael Doe",
                  "customer_name": "John Doe",
                  "correlation_score": 0.95,
                  "names_on_account": [
                    "John Michael Doe",
                    "Jane Doe"
                  ]
                },
                "account_validation": {
                  ...
                }
              },
              ...
            }
          }
        }

Reject

An account that is linked using account and routing number will have a null name match object since this data is not returned by the provider. We recommend using an open banking login where possible.

        {
          "data": {
            "paykey_details": {...},
            "verification_details": {
              "id": "01995295-954b-73cd-bd55-74dfff6ef4c6",
              "decision": "reject",
              "codes": ["BR101"],
              "messages": {
                "BR101": "The bank account is either closed, invalid, or in a negative status."
              },
              "breakdown": {
                "name_match": {...},
                "account_validation": {
                  "decision": "reject",
                  "reason": "The bank account is either closed, invalid, or in a negative status. Derived using the routing number and account number.",
                  "codes": ["BR101"]
                }
              },
              ...
            }
          }
        }

Review

        {
          "data": {
            "paykey_details": {...},
            "verification_details": {
              "id": "456e7890-e89b-12d3-a456-426614174001",
              "decision": "review",
              "messages": {
                "NM01": "Account Holder is not a match for Customer."
              },
              "breakdown": {
                "name_match": {
                  "decision": "review",
                  "reason": "Account Holder is not a match for Customer.",
                  "matched_name": "John Smith",
                  "correlation_score": 0.10,
                  "names_on_account": ["John Smith", "Jane Smith"]
                },
                "account_validation": {...}
              },
              ...
            }
          }
        }

Account Balance Updates

For accounts linked using an open banking token or Bridge, you can receive balance updates when the following events occur:

When a new Paykey is created
When the new refresh endpoint is explicitly called, at most once per hour
When a charge or payout is created

You will receive the balance update within a Paykey webhook event. Manually trigger balance updates: You can also trigger a balance refresh by calling our new /paykeys/{id}/refresh_balance endpoint.

Using Paykeys

Paykeys are used in place of customer and bank account details when creating charges or payouts. Here’s an example of creating a charge using a paykey:

curl -X POST https://sandbox.straddle.com/v1/charges \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paykey": "a1b2c3***.02.******x9y8z7",
    "amount": 1000,
    "currency": "usd",
    "description": "Monthly subscription fee",
    "payment_date": "2023-06-01",
    "consent_type": "internet",
    "device": {
      "ip_address": "192.168.1.1"
    },
    "external_id": "charge_123",
    "config": {
      "balance_check": "enabled"
    }
  }'

Ongoing Management & Unblocking

When a Paykey is blocked (e.g., R29), your customer can’t pay or get paid until it’s fixed. Unblock in the Dashboard once they’ve updated their bank settings—no support wait—so they can use the Paykey again quickly. View blocked Paykeys in the Overview tab or manage them directly from the specific Customer page.

Use the new PATCH /v1/paykeys/{id}/unblock endpoint to programmatically reactivate eligible Paykeys.

Handling R29 Returns

Corporate “positive pay” blocks often cause R29 returns; you can now confirm the customer has added your ACH identifier to their approved list and click “Unblock Paykey” in the Dashboard.

Benefits of Paykeys

For Businesses

Reduced Fraud Losses

Prevent unauthorized account use and save on potential fraud-related losses.

Regulatory Compliance

Simplify adherence to KYC and AML regulations.

Operational Efficiency

Automate identity matching, reducing the need for manual reviews while providing human oversight for edge cases.

Improved Customer Trust

Enhance reputation by ensuring secure transactions.

For Customers

Security

Protect customers from unauthorized use of their bank accounts.

Convenience

Eliminate the need for additional verification steps in most cases.

Privacy

Ensure personal data is handled securely and used appropriately.

Confidence

Build trust in the platform’s ability to protect financial information.

Real-Time Identity Matching

Advanced Data Handling

Fraud Detection

Always Compliant

​How Bridge Creates Paykeys

Data Comparison

Handling Variations

Fraud Prevention

Real-Time Processing

Secure Storage

Payment Initiation

​Paykey Object Definition

​Paykey Attributes

​Verification Results

​Review Attributes

​Paykey Status Details

​Example Paykey Object

​Paykey Verification and Manual Review

Accept

Review

Reject

​Verification Codes and their Meaning

​Manual Review Process

​Account Balance Updates

​Using Paykeys

​Ongoing Management & Unblocking

​Handling R29 Returns

​Benefits of Paykeys

​For Businesses

Reduced Fraud Losses

Regulatory Compliance

Operational Efficiency

Improved Customer Trust

​For Customers

Security

Convenience

Privacy

Confidence

​Further Reading

How Bridge Creates Paykeys

Paykey Object Definition

Paykey Attributes

Verification Results

Review Attributes

Paykey Status Details

Example Paykey Object

Paykey Verification and Manual Review

Verification Codes and their Meaning

Manual Review Process

Account Balance Updates

Using Paykeys

Ongoing Management & Unblocking

Handling R29 Returns

Benefits of Paykeys

For Businesses

For Customers

Further Reading