Quickstart5 min

Build your first integration

Get up and running with Hyperscale in minutes. This guide walks you through installing the SDK, creating a customer, opening an account, and issuing a virtual card.

Prerequisites

Node.js 18+ or Bun runtime
Hyperscale API key (follow Docs → Credentials)
Basic TypeScript/JavaScript knowledge

Open credentials guide

Install the SDK

Add the Hyperscale SDK to your project using your preferred package manager.

$npm install @hyperscale/sdk

Initialize the client

Create a Hyperscale client instance with your API key. The product parameter identifies your application for routing and analytics.

hyperscale.ts

typescript

1import { Hyperscale } from '@hyperscale/sdk';
2
3const hyperscale = new Hyperscale({
4  apiKey: process.env.HYPERSCALE_API_KEY,
5  product: 'my-neobank',
6});

Security: Never expose your API key in client-side code. Use environment variables and server-side API routes.

Create a customer

Create a customer record and initiate KYC verification. Hyperscale handles the KYC flow with the appropriate provider based on your configuration.

create-customer.ts

typescript

1// Create a customer with KYC verification
2const customer = await hyperscale.customers.create({
3  nationalId: '1234567890',
4  email: 'customer@example.com',
5  phone: '+966501234567',
6});
7
8console.log('Customer ID:', customer.id);
9// customer.kycStatus will be 'pending' | 'verified' | 'rejected'

Open an account

Once the customer is verified, open a current account. The account includes a unique IBAN for receiving transfers.

create-account.ts

typescript

1// Open a current account for the customer
2const account = await hyperscale.accounts.create({
3  customerId: customer.id,
4  type: 'CURRENT',
5  currency: 'SAR',
6});
7
8console.log('IBAN:', account.iban);
9console.log('Balance:', account.balance.amount);

Issue a virtual card

Issue a virtual debit card linked to the account. Virtual cards are created instantly and can be used immediately for online purchases.

issue-card.ts

typescript

1// Issue a virtual debit card
2const card = await hyperscale.cards.issue({
3  accountId: account.id,
4  type: 'VIRTUAL',
5  brand: 'VISA',
6});
7
8console.log('Card last 4:', card.last4);
9console.log('Status:', card.status);

What's next?

Understand the Architecture

Learn how Hyperscale routes requests to providers

Process Payments

Accept payments and transfer funds

Set Up Webhooks

Get notified about account events

Try the Sandbox

Interactive API playground

1// Create a customer with KYC verification 2const customer = await hyperscale.customers.create({ 3 nationalId: '1234567890', 4 email: 'customer@example.com', 5 phone: '+966501234567', 6}); 7 8console.log('Customer ID:', customer.id); 9// customer.kycStatus will be 'pending' | 'verified' | 'rejected'

1// Open a current account for the customer 2const account = await hyperscale.accounts.create({ 3 customerId: customer.id, 4 type: 'CURRENT', 5 currency: 'SAR', 6}); 7 8console.log('IBAN:', account.iban); 9console.log('Balance:', account.balance.amount);

1// Issue a virtual debit card 2const card = await hyperscale.cards.issue({ 3 accountId: account.id, 4 type: 'VIRTUAL', 5 brand: 'VISA', 6}); 7 8console.log('Card last 4:', card.last4); 9console.log('Status:', card.status);