KYC
KYC (Know Your Customer) verification is required before customers can issue cards. Proxy handles identity verification through Rain’s KYC infrastructure to comply with financial regulations.
Why KYC?
Card issuance is a regulated activity. Before a customer can:
- Issue virtual cards
- Fund their account
- Make transactions
They must complete identity verification to prevent fraud and money laundering.
Creating a KYC Application
Submit a KYC application with the customer’s identity information:
curl -X POST https://api.useproxy.ai/v1/kyc/applications \
-H "Authorization: Bearer sk_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"customerId": "cus_xxx",
"application": {
"firstName": "John",
"lastName": "Doe",
"birthDate": "1990-01-15",
"nationalId": "123456789",
"countryOfIssue": "US",
"email": "john@example.com",
"address": {
"line1": "123 Main St",
"city": "San Francisco",
"state": "CA",
"postalCode": "94102",
"country": "US"
},
"ipAddress": "1.2.3.4",
"occupation": "SOFTWARE_ENGINEER",
"annualSalary": "100000_149999",
"accountPurpose": "PERSONAL_SPENDING",
"expectedMonthlyVolume": "1000_4999",
"isTermsOfServiceAccepted": true,
"phoneCountryCode": "1",
"phoneNumber": "5551234567"
}
}'
Required Fields
| Field | Type | Description |
|---|
firstName | string | Customer’s first name (max 50 chars) |
lastName | string | Customer’s last name (max 50 chars) |
birthDate | string | Date of birth in YYYY-MM-DD format |
nationalId | string | National ID (9-digit SSN for US customers) |
countryOfIssue | string | 2-letter country code for national ID |
email | string | Customer’s email address |
address | object | Customer’s physical address |
ipAddress | string | Customer’s IP address |
occupation | string | Customer’s occupation code |
annualSalary | string | Annual salary range |
accountPurpose | string | Purpose of account |
expectedMonthlyVolume | string | Expected monthly spend range |
isTermsOfServiceAccepted | boolean | Must be true |
phoneCountryCode | string | Phone country code (e.g., “1” for US) |
phoneNumber | string | Phone number without country code |
Address Object
| Field | Type | Description |
|---|
line1 | string | Street address |
line2 | string | Apartment, suite, etc. (optional) |
city | string | City |
state | string | State/province code |
postalCode | string | Postal/ZIP code |
country | string | 2-letter country code |
Optional Fields
| Field | Type | Description |
|---|
walletAddress | string | EVM wallet address (auto-created if not provided) |
solanaAddress | string | Solana wallet address (auto-created if not provided) |
You don’t need to provide a wallet address. Proxy automatically creates a secure server-managed wallet for each customer during KYC.
Occupation Codes
Common values:
SOFTWARE_ENGINEERPRODUCT_MANAGERBUSINESS_OWNERACCOUNTANTCONSULTANTOTHER
Salary Ranges
0_2499925000_4999950000_99999100000_149999150000_249999250000_499999500000_PLUS
Monthly Volume Ranges
0_9991000_49995000_999910000_2499925000_4999950000_PLUS
Account Purpose
PERSONAL_SPENDINGBUSINESS_EXPENSESPAYROLLVENDOR_PAYMENTS
Response
{
"id": "app_xxx",
"customerId": "cus_xxx",
"status": "pending",
"reason": null,
"completionLink": "https://verify.example.com/complete/xyz789"
}
| Field | Description |
|---|
id | Application ID |
customerId | Your customer ID |
status | Current application status |
reason | Reason if status is not approved |
completionLink | URL for customer to complete additional verification |
Application Statuses
| Status | Description |
|---|
pending | Application submitted, under review |
approved | Verified, customer can issue cards |
needsInformation | Additional info required |
needsVerification | Identity verification needed - send customer to completionLink |
manualReview | Flagged for manual review |
denied | Application rejected |
locked | Account locked |
KYC Flow
Create Customer
Create a customer record via POST /v1/customers
Submit KYC Application
Submit application with all required identity fields
Check Status
Response indicates if additional verification is needed
Complete Verification
If needsVerification, direct customer to completionLink to upload ID documents
Wait for Approval
Poll status or receive webhook when application is approved
Issue Cards
Once approved, customer can issue virtual cards
Checking Application Status
curl https://api.useproxy.ai/v1/kyc/applications/app_xxx \
-H "Authorization: Bearer sk_live_xxx"
{
"id": "app_xxx",
"customerId": "cus_xxx",
"status": "needsVerification",
"reason": "Identity verification required",
"completionLink": "https://verify.example.com/complete/xyz789"
}
Completion Link
When status is needsInformation or needsVerification, the response includes a completionLink. Direct your customer to this URL to complete the verification process (e.g., upload government ID).
Completion links expire after 24 hours. Request a new application status to get a fresh link if needed.
Webhooks
Subscribe to KYC events for real-time updates:
| Event | Description |
|---|
kyc.approved | Customer approved for card issuance |
kyc.rejected | Application was rejected |
Next Steps
