Configuring Customers

Customers must complete identity verification before processing conversions. The required information varies based on your platform’s regulatory status.

Regulated Platforms

Regulated platforms have lighter KYC requirements since they handle compliance verification internally.

The KYC/KYB flow allows you to onboard customers through direct API calls.Regulated financial institutions can:

Direct API Onboarding: Create customers directly via API calls with minimal verification
Internal KYC/KYB: Handle identity verification through your own compliance systems
Reduced Documentation: Only provide essential customer information required by your payment counterparty or service provider.
Faster Onboarding: Streamlined process for known, verified customers

Creating Customers via Direct API

For regulated platforms, you can create customers directly through the API without requiring external KYC verification:To register a new customer in the system, use the POST /customers endpoint:

curl -X POST "https://api.lightspark.com/grid/2025-10-13/customers" \
  -H "Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "platformCustomerId": "customer_12345",
    "customerType": "INDIVIDUAL",
    "fullName": "Jane Doe",
    "birthDate": "1992-03-25",
    "nationality": "US",
    "address": {
      "line1": "123 Pine Street",
      "city": "Seattle",
      "state": "WA",
      "postalCode": "98101",
      "country": "US"
    },
    "bankAccountInfo": {
      "accountType": "US_ACCOUNT",
      "accountNumber": "123450000",
      "routingNumber": "000123456",
      "accountCategory": "CHECKING",
      "bankName": "Chase Bank"
    }
  }'

The API allows creating a customer with minimal PII.Here is an example of a customer creation request body bankAccountInfo is always required:

{
  "platformCustomerId": "9f84e0c2a72c4fa",
  "customerType": "INDIVIDUAL",
  "bankAccountInfo": {
      "accountType": "US_ACCOUNT",
      "accountNumber": "123450000",
      "routingNumber": "000123456",
      "accountCategory": "CHECKING",
      "bankName": "Chase Bank"
    }
}

The examples below show a more comprehensive set of data. Not all fields are strictly required by the API for customer creation itself, but become necessary based on currency and UMA provider requirements if using UMA.

Individual customer
Business Customer

{
  "platformCustomerId": "9f84e0c2a72c4fa",
  "customerType": "INDIVIDUAL",
  "fullName": "John Sender",
  "birthDate": "1985-06-15",
  "address": {
    "line1": "Paseo de la Reforma 222",
    "line2": "Piso 15",
    "city": "Ciudad de México",
    "state": "Ciudad de México",
    "postalCode": "06600",
    "country": "MX"
  },
  "bankAccountInfo": {
    "accountType": "CLABE",
    "clabeNumber": "123456789012345678",
    "bankName": "Banco de México"
  }
}

Unregulated Platforms

Unregulated platforms require full KYC/KYB verification of customers through hosted flows.

Unregulated platforms must:

Hosted KYC Flow: Use the hosted KYC link for complete identity verification
Extended Review: Customers may require manual review and approval in some cases

Hosted KYC Link Flow

The hosted KYC flow provides a secure, hosted interface where customers can complete their identity verification and onboarding process.

Generate KYC Link

curl -X GET "https://api.lightspark.com/grid/2025-10-13/customers/kyc-link?redirectUri=https://yourapp.com/onboarding-complete&platformCustomerId=019542f5-b3e7-1d02-0000-000000000001" \
  -H "Authorization: Basic $GRID_CLIENT_ID:$GRID_CLIENT_SECRET"

Response:

{
  "kycUrl": "https://kyc.lightspark.com/onboard/abc123def456",
  "platformCustomerId": "019542f5-b3e7-1d02-0000-000000000001"
}

Complete KYC Process

Generate KYC Link

Call the /customers/kyc-link endpoint with your redirectUri parameter to generate a hosted KYC URL for your customer.

The redirectUri parameter is embedded in the generated KYC URL and will be used to automatically redirect the customer back to your application after they complete verification.

Redirect Customer

Redirect your customer to the returned kycUrl where they can complete their identity verification in the hosted interface.

The KYC link is single-use and expires after a limited time period for security.

Customer Completes Verification

The customer completes the identity verification process in the hosted KYC interface, providing required documents and information.

The hosted interface handles document collection, verification checks, and compliance requirements automatically.

After verification processing, you’ll receive a KYC status webhook notification indicating the final verification result.

Automatic Redirect

Upon successful KYC completion, the customer is automatically redirected to your specified redirectUri URL.

The customer account will be automatically created by the system upon successful KYC completion. You can identify the new customer using your platformCustomerId or other identifiers.

Handle Completion

On your redirect page, handle the completed KYC flow and integrate the new customer into your application.

Monitor verification status

After a customer completes the KYC/KYB verification process, you’ll receive webhook notifications about their KYC status. These notifications are sent to your configured webhook endpoint.

For regulated platforms, customers are created with APPROVED KYC status by default.

Webhook Payload (sent to your endpoint):

{
  "webhookId": "Webhook:019542f5-b3e7-1d02-0000-000000000020",
  "type": "KYC_STATUS",
  "timestamp": "2023-07-21T17:32:28Z",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000001",
  "kycStatus": "APPROVED",
  "platformCustomerId": "1234567"
}

Webhook Headers:

Content-Type: application/json
X-Webhook-Signature: sha256=abc123...

customerId

string

required

System-generated unique identifier of the customer whose KYC status has changed.

kycStatus

string

required

Final KYC verification status. Webhooks are only sent for final states:

APPROVED: Customer verification completed successfully
REJECTED: Customer verification was rejected
EXPIRED: KYC verification has expired and needs renewal
CANCELED: Verification process was canceled
MANUALLY_APPROVED: Customer was manually approved by platform
MANUALLY_REJECTED: Customer was manually rejected by platform

Intermediate states like PENDING_REVIEW do not trigger webhook notifications. Only final resolution states will send webhook notifications.

Webhook Implementation Example

// Example webhook handler for KYC status updates
// Note: Only final states trigger webhook notifications
app.post('/webhooks/kyc-status', (req, res) => {
  const { customerId, kycStatus } = req.body;
  
  switch (kycStatus) {
    case 'APPROVED':
      // Activate customer account
      await activateCustomer(customerId);
      await sendWelcomeEmail(customerId);
      break;
      
    case 'REJECTED':
      // Notify support and customer
      await notifySupport(customerId, 'KYC_REJECTED');
      await sendRejectionEmail(customerId);
      break;
      
    case 'MANUALLY_APPROVED':
      // Handle manual approval
      await activateCustomer(customerId);
      await sendWelcomeEmail(customerId);
      break;
      
    case 'MANUALLY_REJECTED':
      // Handle manual rejection
      await notifySupport(customerId, 'KYC_MANUALLY_REJECTED');
      await sendRejectionEmail(customerId);
      break;
      
    case 'EXPIRED':
      // Handle expired KYC
      await notifyCustomerForReKyc(customerId);
      break;
      
    case 'CANCELED':
      // Handle canceled verification
      await logKycCancelation(customerId);
      break;
      
    default:
      // Log unexpected statuses
      console.log(`Unexpected KYC status ${kycStatus} for customer ${customerId}`);
  }
  
  res.status(200).send('OK');
});

Only customers with APPROVED status can create quotes and process conversions.

Customer types

Individual customers

For personal conversions and consumer wallets.Required fields: fullName, email, birthDate, address

curl -X POST 'https://api.lightspark.com/grid/2025-10-13/customers' \
  -u "$GRID_CLIENT_ID:$GRID_API_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "platformCustomerId": "user_12345",
    "customerType": "INDIVIDUAL",
    "fullName": "Alice Johnson",
    "email": "alice@example.com",
    "birthDate": "1990-01-15",
    "address": {...}
  }'

Business customers

For corporate conversions and business accounts.Required fields: businessName, email, taxId, address

curl -X POST 'https://api.lightspark.com/grid/2025-10-13/customers' \
  -u "$GRID_CLIENT_ID:$GRID_API_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "platformCustomerId": "biz_67890",
    "customerType": "BUSINESS",
    "businessName": "Acme Corporation",
    "email": "finance@acme.com",
    "taxId": "12-3456789",
    "address": {...}
  }'

Next steps

Internal Accounts

Fund crypto for off-ramp conversions

External Accounts

Set up wallet destinations

Fiat-to-Crypto

Build conversion flows

API Reference

Complete customer API docs

Onboarding

Managing Accounts

Conversion Flows

Platform Tools

Creating Customers via Direct API

Hosted KYC Link Flow

Generate KYC Link

Complete KYC Process

Monitor verification status

Customer types

Next steps

Internal Accounts

External Accounts

Fiat-to-Crypto

API Reference

Onboarding

Managing Accounts

Conversion Flows

Platform Tools

​Creating Customers via Direct API

​Hosted KYC Link Flow

​Generate KYC Link

​Complete KYC Process

​Monitor verification status

​Customer types

​Next steps

Internal Accounts

External Accounts

Fiat-to-Crypto

API Reference

Creating Customers via Direct API

Hosted KYC Link Flow

Generate KYC Link

Complete KYC Process

Monitor verification status

Customer types

Next steps