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 the intricacies of Paykeys, explaining how they 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 by comparing verified identity data with bank account details.

Advanced Data Handling

Manages variations in personal information, such as typos, nicknames, and cultural differences in naming conventions.

Fraud Detection

Identifies and prevents potential fraudulent activities before they occur.

Always Compliant

Embeds regulatory compliance checks into the identity verification process, reducing the compliance burden on your organization.

​
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:
1

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.
2

Bank Account Connection via Bridge

3

Identity Matching with WALDO

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

Data Comparison

WALDO compares the customer’s verified identity from Straddle ID with the bank account ownership details retrieved during the bank connection.

Handling Variations

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

Fraud Prevention

By confirming legitimate ownership, WALDO helps prevent fraudulent activities and unauthorized access to bank accounts.

Real-Time Processing

The verification occurs instantly, ensuring a seamless user experience without added delays.
4

Paykey Generation

5

Secure Delivery of the Paykey

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

Storage and Usage

Secure Storage

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

Payment Initiation

The Paykey is used to initiate payments via Straddle’s Payments API. It authorizes payments without exposing sensitive PII or bank account 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

FieldTypeDescription
idstringUnique identifier for the paykey, generated by Straddle.
customer_idstringUnique identifier of the customer associated with this paykey.
labelstringHuman-readable label for the paykey, often including the bank name and masked account number.
sourcestringMethod used to create the paykey (e.g., bank_account, plaid, mx, straddle).
institution_namestringName of the financial institution associated with the paykey.
statusstringCurrent status of the paykey (pending, active, inactive, rejected).
status_detailsobjectAdditional information about the paykey’s status.
↳ messagestringA human-readable description of the current status.
↳ reasonstringA machine-readable identifier for the specific status.
↳ sourcestringIdentifies the origin of the status change (e.g., ‘bank_decline’, ‘system’).
paykeystringThe tokenized paykey value used for transactions.
bank_dataobjectMasked bank account details associated with the paykey.
↳ routing_numberstringThe bank’s routing number.
↳ account_numberstringThe masked bank account number (e.g., “******1234”).
↳ account_typestringThe type of bank account (e.g., “checking” or “savings”).
balanceintegerThe available balance of the linked account in cents, if available.
metadataobjectUser-defined key-value pairs for storing additional information about the paykey.
expires_atdatetimeExpiration date and time of the paykey, if applicable.
created_atdatetimeTimestamp of when the paykey was created.
updated_atdatetimeTimestamp of the most recent update to the paykey.

​
Paykey Status Details

StatusDescription
pendingInitial status when the paykey is created and awaiting verification.
activePaykey has been verified and is ready for use in transactions.
inactivePaykey is no longer active and cannot be used for transactions.
rejectedPaykey failed verification or was rejected by the financial institution.

​
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"
  }
}

​
Using Paykey

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:

​
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.

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.

Privacy

Ensure personal data is handled securely and used appropriately.

Confidence

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

​
Further Reading