api.customers approvals

Three reads describing what a customer is cleared to do. Only rows with status: "approved" can be acted on today; everything else is a stage of review. Each list is narrowed to the currencies and rails your organization is approved for.

const [payIn, payout, virtualAccounts] = await Promise.all([
  api.customers.payInApprovals("2f10…"),
  api.customers.payoutApprovals("2f10…"),
  api.customers.virtualAccountApprovals("2f10…"),
]);
 
// Narrow a funding-method picker to what will actually quote.
const fundingOptions = payIn
  .filter((a) => a.status === "approved")
  .map((a) => ({ currency: a.currency, rail: a.rail }));
 
// Payout rows are country-specific when `country` is set.
const canPayMxnViaSpei = payout.some(
  (a) =>
    a.status === "approved" && a.currency === "MXN" && a.rail === "spei",
);
 
for (const account of virtualAccounts) {
  if (account.status !== "approved") continue;
  console.log(account.currency, account.bank, account.maintenance_fee);
}

status: one of "approved", "pending", "action_required", "rejected", "not_started" (what each means). Typed as string rather than a union so a state added later doesn't fail parsing on an older client — branch on "approved" and treat anything else as not-yet-usable. status_detail is an optional finer-grained hint and is not a fixed set.

rail uses the same names as GET /rails, so a value read here can be passed straight back when creating an account or a quote.

Throws: ApiError with status: 404 (unknown customer, or one belonging to a different org) or status: 503 (unavailable on this environment).

A row that reads "not_started" because the customer was onboarded before that account type became available can be started with api.customers.syncApprovals(id) — the client method for POST /customers/:id/kyc/sync-approvals. It files the saved profile with every verification check the customer has not started yet, leaves existing checks untouched, and returns the customer's state envelope; expect RFIs by email and a customer.kyc.status_changed / customer.kyb.status_changed webhook when the review concludes — if the customer was already approved and the cleared check only expanded what they can do, the event fires with the status unchanged and expanded: true.

REST endpoints: GET /customers/:id/pay-in-approvals, GET /customers/:id/payout-approvals, GET /customers/:id/virtual-account-approvals.