KYC

Know Your Customer verification for card issuance

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": "[e-mail]",
      "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_ENGINEER
• PRODUCT_MANAGER
• BUSINESS_OWNER
• ACCOUNTANT
• CONSULTANT
• OTHER

Salary Ranges

• 0_24999
• 25000_49999
• 50000_99999
• 100000_149999
• 150000_249999
• 250000_499999
• 500000_PLUS

Monthly Volume Ranges

• 0_999
• 1000_4999
• 5000_9999
• 10000_24999
• 25000_49999
• 50000_PLUS

Account Purpose

• PERSONAL_SPENDING
• BUSINESS_EXPENSES
• PAYROLL
• VENDOR_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

1. Create Customer

   Create a customer record via POST /v1/customers

2. Submit KYC Application

   Submit application with all required identity fields

3. Check Status

   Response indicates if additional verification is needed

4. Complete Verification

   If needsVerification, direct customer to completionLink to upload ID documents

5. Wait for Approval

   Poll status or receive webhook when application is approved

6. 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"

Response:

{
  "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

Customers

Learn about customer management

Cards

Issue cards after KYC approval