Paykeys
A new kind of token for secure account-to-account payments
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:
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
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.
Paykey Generation
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.
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
| 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). |
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. |
Paykey Status Details
| Status | Description |
|---|---|
pending | Initial status when the paykey is created and awaiting verification. |
active | Paykey has been verified and is ready for use in transactions. |
inactive | Paykey is no longer active and cannot be used for transactions. |
rejected | Paykey 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.