Skip to main content

​
Working with External User IDs

The externalUserId is your user identifier from your own database. You use it consistently across all API calls for the same user:
Think of externalUserId as the bridge between your system and Karma’s. It’s how you tell the API “this is user_123 from my health app.”
const myUserId = "user_123"; // From your database

// Step 1: Create end-user record (API calls this "holder")
await fetch('https://api.karmapay.xyz/v0/end-users', {
  method: 'POST',
  body: JSON.stringify({
    externalUserId: myUserId  // Your user ID
  })
});

// Step 2: Create virtual account for the same user
await fetch('https://api.karmapay.xyz/v0/virtual-accounts', {
  method: 'POST',
  body: JSON.stringify({
    externalUserId: myUserId,  // Same ID
    source: { currency: "usd" },
    destination: { /* ... */ }
  })
});

// Step 3: Get all accounts for this user
await fetch('https://api.karmapay.xyz/v0/virtual-accounts', {
  method: 'GET',
  body: JSON.stringify({
    externalUserId: myUserId  // Same ID
  })
});
Key point: Always use the same externalUserId for the same user across all API calls. This is how the API knows which accounts, transactions, and KYC data belong to which of your users.

​
Response Data Wrapper

All successful responses wrap data in a data property: 
// Single resource
{ data: { id: "123", name: "John" } }

// Multiple resources (like listing accounts)
{ data: [{ id: "1" }, { id: "2" }] }

// Success confirmation
{ data: { success: true } }
This means when you make an API call, always access the response data via .data: 
const response = await fetch('https://api.karmapay.xyz/v0/end-users', {
  method: 'POST',
  body: JSON.stringify({ externalUserId: "user_123" })
});

const result = await response.json();
const endUserData = result.data; // ← Always access via .data

console.log(endUserData.id); // The end-user's ID in Karma's system
console.log(endUserData.externalUserId); // Your user ID ("user_123")