Skip to main content
This method is for testing only and will not work in production. Always test your integration thoroughly before going live.

​
Method Signature

align.customers.simulateCustomer(
  data: SimulateCustomerRequest
): Promise<SimulateCustomerResponse>

​
Parameters

​
customer_id
string
required
The unique customer identifier (UUID format)
​
action
string
required
The simulation action to perform. Currently supported: - kyc.status.approve
  • Approve the customer’s KYC verification

​
Returns

Returns an empty object {} on success.

​
Examples

​
Simulate KYC Approval

import Align from "@tolbel/align";

const align = new Align({
  apiKey: process.env.ALIGN_API_KEY!,
  environment: "sandbox", // Must be sandbox!
});

// Create a customer
const customer = await align.customers.create({
  email: "[email protected]",
  type: "individual",
  first_name: "Test",
  last_name: "User",
});

// Initiate KYC session
await align.customers.createKycSession(customer.customer_id);

// Simulate KYC approval
await align.customers.simulateCustomer({
  customer_id: customer.customer_id,
  action: "kyc.status.approve",
});

// Verify the customer is now approved
const updated = await align.customers.get(customer.customer_id);
console.log(`KYC Status: ${updated.kycs?.sub_status}`);
// KYC Status: kyc_form_submission_accepted

​
Complete Test Workflow

Here’s a complete example of testing the full customer onboarding flow: 
async function testCustomerOnboarding() {
  // 1. Create customer
  const customer = await align.customers.create({
    email: `test-${Date.now()}@example.com`,
    type: "individual",
    first_name: "Test",
    last_name: "User",
  });
  console.log("Customer created:", customer.customer_id);

  // 2. Create KYC session
  const kyc = await align.customers.createKycSession(customer.customer_id);
  console.log("KYC session created");

  // 3. Simulate KYC approval
  await align.customers.simulateCustomer({
    customer_id: customer.customer_id,
    action: "kyc.status.approve",
  });
  console.log("KYC approved");

  // 4. Create virtual account (now possible after KYC)
  const account = await align.virtualAccounts.create(customer.customer_id, {
    source_currency: "usd",
    destination_token: "usdc",
    destination_network: "polygon",
    destination_address: "0x742d35Cc6634C0532925a3b844Bc9e7595f0aB42",
  });
  console.log("Virtual account created:", account.id);

  // 5. Simulate deposit
  await align.virtualAccounts.simulate(account.id, {
    amount: "100.00",
  });
  console.log("Deposit simulated");

  console.log("\nFull onboarding flow completed!");
}

testCustomerOnboarding().catch(console.error);

​
Supported Actions

ActionDescription
kyc.status.approveApprove the customer’s KYC verification instantly
More simulation actions may be added in the future. Check the changelog for updates.

​
Error Handling

import { AlignError } from "@tolbel/align";

try {
  await align.customers.simulateCustomer({
    customer_id: "123e4567-e89b-12d3-a456-426614174000",
    action: "kyc.status.approve",
  });
} catch (error) {
  if (error instanceof AlignError) {
    if (error.status === 404) {
      console.error("Customer not found");
    } else if (error.status === 400) {
      console.error("Invalid action or customer state");
    }
  }
}
KYC simulation only works if the customer has an active KYC session. Call createKycSession first.

Create KYC Session

Initiate KYC verification

Get Customer

Check KYC status after simulation

Simulate Virtual Account

Simulate deposits