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_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

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"

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

Getting Started

Concepts

KYC

KYC

Why KYC?

Creating a KYC Application

Required Fields

Address Object

Optional Fields

Occupation Codes

Salary Ranges

Monthly Volume Ranges

Account Purpose

Response

Application Statuses

KYC Flow

Checking Application Status

Completion Link

Webhooks

Next Steps

Customers

Cards

​KYC

​Why KYC?

​Creating a KYC Application

​Required Fields

​Address Object

​Optional Fields

​Occupation Codes

​Salary Ranges

​Monthly Volume Ranges

​Account Purpose

​Response

​Application Statuses

​KYC Flow

​Checking Application Status

​Completion Link

​Webhooks

​Next Steps

Customers

Cards

KYC

Why KYC?

Creating a KYC Application

Required Fields

Address Object

Optional Fields

Occupation Codes

Salary Ranges

Monthly Volume Ranges

Account Purpose

Response

Application Statuses

KYC Flow

Checking Application Status

Completion Link

Webhooks

Next Steps