Guide10 min

Create Your First Customer

Learn how to create a customer record, understand KYC verification states, and manage the customer lifecycle.

Prerequisites

Hyperscale SDK installed
API key configured using Docs → Credentials
Completed the quickstart

Create a Customer

Create a customer by providing basic identity information. The customer will be created in a pending KYC state until verification completes.

create-customer.ts

typescript

1import { Hyperscale } from '@hyperscale/sdk';
2
3const hyperscale = new Hyperscale({
4  apiKey: process.env.HYPERSCALE_API_KEY,
5  product: 'my-neobank',
6});
7
8// Create a new customer
9const customer = await hyperscale.customers.create({
10  // Required fields
11  nationalId: '1234567890',
12  email: 'ahmed@example.com',
13  phone: '+966501234567',
14
15  // Optional profile
16  firstName: 'Ahmed',
17  lastName: 'Al-Rashid',
18  dateOfBirth: '1990-05-15',
19  nationality: 'SA',
20});
21
22console.log('Customer ID:', customer.id);
23console.log('KYC Status:', customer.kycStatus);

Required Fields

nationalId

Saudi ID or Iqama number

email

Valid email address

phone

Phone with country code

Understand KYC States

Customers progress through KYC verification states. Monitor these states to know when a customer can access financial services.

pending

Awaiting verification

in_review

Manual review needed

verified

Ready for services

rejected

Verification failed

Retrieve Customer

Retrieve a customer by ID to check their current status and KYC verification state.

get-customer.ts

typescript

1// Retrieve customer by ID
2const customer = await hyperscale.customers.retrieve('cus_abc123');
3
4console.log('Status:', customer.status);
5console.log('KYC Status:', customer.kycStatus);
6console.log('Created:', customer.createdAt);

Update Customer

Update customer profile information. Note that changing certain fields may trigger re-verification.

update-customer.ts

typescript

1// Update customer profile
2const updated = await hyperscale.customers.update('cus_abc123', {
3  email: 'new.email@example.com',
4  phone: '+966509876543',
5});
6
7console.log('Updated:', updated.updatedAt);

Next Steps

Issue a Virtual Card

Issue cards linked to customer accounts

Process a Payment

Accept and transfer funds

1import { Hyperscale } from '@hyperscale/sdk'; 2 3const hyperscale = new Hyperscale({ 4 apiKey: process.env.HYPERSCALE_API_KEY, 5 product: 'my-neobank', 6}); 7 8// Create a new customer 9const customer = await hyperscale.customers.create({ 10 // Required fields 11 nationalId: '1234567890', 12 email: 'ahmed@example.com', 13 phone: '+966501234567', 14 15 // Optional profile 16 firstName: 'Ahmed', 17 lastName: 'Al-Rashid', 18 dateOfBirth: '1990-05-15', 19 nationality: 'SA', 20}); 21 22console.log('Customer ID:', customer.id); 23console.log('KYC Status:', customer.kycStatus);

1// Retrieve customer by ID 2const customer = await hyperscale.customers.retrieve('cus_abc123'); 3 4console.log('Status:', customer.status); 5console.log('KYC Status:', customer.kycStatus); 6console.log('Created:', customer.createdAt);

1// Update customer profile 2const updated = await hyperscale.customers.update('cus_abc123', { 3 email: 'new.email@example.com', 4 phone: '+966509876543', 5}); 6 7console.log('Updated:', updated.updatedAt);