Customers
Your users, by reference. Unirail keeps an id that maps back to yours and nothing it doesn't need.
A customer (cus_…) is one of your users as Unirail sees them. It exists so accounts, link sessions and payments can belong to someone, and it maps back to your user through externalId.
const customer = await unirail.customers.create(
{ externalId: user.id, name: user.name, email: user.email, country: "GB", metadata: { plan: "pro" } },
{ context: { idempotencyKey: `customer:${user.id}` } },
);externalId is unique per environment, so creating a customer for a user who already has one returns the existing customer. Store customer.id on your user record and pass it to link sessions and accounts.
What stays yours
Your users, their KYC and CDD standing, and how you approve their payments stay in your platform. Unirail holds the customer reference, the accounts and links attached to it, and the payments made between them. It processes personal data such as names and account identifiers on your behalf.
Finding customers
const { data } = await unirail.customers.list({ externalId: user.id });
const same = await unirail.customers.retrieve({ id: "cus_…" });Lists page with limit (up to 100) and after, the id of the last customer you saw. hasMore tells you whether to ask again.
Metadata
Every object that takes metadata accepts up to 20 string keys (40 characters each) with string values up to 500 characters. Use it to find objects again from your side, for example your own payment id. Don't put secrets or account numbers in it.