Sign up and create an organization

Go to app.sandbox.vortex.nyc, sign up, and create an organization. The dashboard issues a sandbox API key immediately — production keys follow account activation.

The key is shown once. Store it now:

export VORTEX_API_KEY="vp_test_..."

Keys carry their environment: vp_test_ keys hit the sandbox, vp_live_ keys hit production. There is no environment switch to set — or to forget. See Sandbox & environments for why.

If you are wiring signup into your own product, POST /v1/signup (session auth) returns the new organization, its environment, and the plaintext key:

{
  "organizationId": "org_...",
  "environment": "sandbox",
  "apiKey": "vp_test_..."
}

Agents and integrators can also self-serve: POST /v1/signup accepts an unauthenticated body ({ "name": "...", "environment": "sandbox" }) and mints a vp_test_ key plus a claimUrl — no invite required. Anonymous signup is sandbox-only; environment: "live" is rejected, and production organizations are created from an authenticated account. Unclaimed sandbox keys expire when the claim window closes.

Install the SDK

pnpm add @vortex-api/vortex

npm install @vortex-api/vortex

yarn add @vortex-api/vortex

The package is published to the public npm registry as @vortex-api/vortex. No .npmrc registry override. Python and Go SDKs are also available, and the SDK quickstart walks all three languages.

Run the CLI onboarding quickstart

The vortex CLI drives the full sandbox path without handcrafting REST calls. After you have an API key, run the one-shot merchant onboarding flow from the repo:

# In the repo root
pnpm cli quickstart onboarding \
  --environment sandbox \
  --display-name "My First Merchant" \
  --signee-name "Avery Test" \
  --signee-title "CEO"

The quickstart creates a merchant account, patches the merchant profile, submits onboarding, signs any pending PCI compliance forms, and prints the merchant state. The final ok: true means payoutReadiness is ready and the merchant can accept payments.

The JSON output contains the IDs you need for the next steps:

{
  "ok": true,
  "environment": "sandbox",
  "merchantAccountId": "ma_...",
  "onboardingSessionId": "onb_...",
  "payoutReadiness": "ready",
  "canAcceptPayments": true
}

If the quickstart returns ok: false, the JSON also contains failedStep and the full response for that step, so you can retry the individual command (see below) or inspect the merchant state in the dashboard.

You can also add a customer and a payment-method setup session automatically with the --collect flag. The --setup-token must be a real tokenization result (a TK... token produced by the hosted payment form or the Vortex Payments SDK in a browser). In local tests with SIMULATE_PAYMENTS_PROVIDER=true, a simulator token such as tok_sim_card_1 can be used instead:

pnpm cli quickstart onboarding \
  --environment sandbox \
  --display-name "My First Merchant" \
  --collect \
  --setup-token "TK_..."

The CLI and individual commands use the same public API as the SDKs; they are a convenience for integration work, not a separate interface.

Individual onboarding commands

If the quickstart stops on a step, or you want to replay a single step, use the individual commands:

# Submit onboarding for an existing merchant
pnpm cli payments merchant-accounts onboarding-submit \
  --merchant-account-id ma_... \
  --submitted-by-ref "operator:my-user-id"

# List requirements
pnpm cli payments merchant-accounts onboarding-requirements \
  --merchant-account-id ma_... \
  --onboarding-session-id onb_...

# Sign a PCI compliance requirement
pnpm cli payments merchant-accounts onboarding-sign \
  --merchant-account-id ma_... \
  --onboarding-session-id onb_... \
  --requirement-id "ma_...:compliance_form:..." \
  --signee-name "Avery Test" \
  --signee-title "CEO"

# Check merchant state
pnpm cli payments merchant-accounts state \
  --merchant-account-id ma_...

# Create a customer, a setup session, and a payment intent
pnpm cli payments merchant-accounts customers create \
  --merchant-account-id ma_... \
  --name "Pat Buyer" \
  --email "pat@example.com"

pnpm cli payments payment-method-setup create \
  --merchant-account-id ma_... \
  --owner-id cprof_... \
  --owner-type customer

# After collecting the real setup token (`TK...`) from the hosted form or SDK:
pnpm cli payments payment-methods attach \
  --merchant-account-id ma_... \
  --setup-session-id pmset_... \
  --setup-token "TK_..."

pnpm cli payments payment-intents create \
  --merchant-account-id ma_... \
  --payment-method-id pm_... \
  --customer-profile-id cprof_... \
  --amount 3100

Create your first merchant

Every charge belongs to a merchant account. Create one in the sandbox:

import {
  createMerchantAccount,
  createVortex,
} from "@vortex-api/vortex/2026-08";

const vortex = createVortex({ apiKey: process.env.VORTEX_API_KEY });

const { data, error } = await createMerchantAccount({
  client: vortex,
  body: {
    environment: "sandbox",
    externalMerchantRef: "my-first-merchant",
    displayName: "My First Merchant",
    legalEntityType: "CORPORATION",
    merchantMode: "processing",
    country: "USA",
    defaultCurrency: "USD",
  },
});
if (error) throw new Error(JSON.stringify(error));
console.log(data.data.id); // ma_...

Or with curl:

curl "https://api.sandbox.vortex.nyc/v1/merchant-accounts" \
  -X POST \
  -H "Authorization: Bearer $VORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-merchant-1" \
  -d '{
    "environment": "sandbox",
    "externalMerchantRef": "my-first-merchant",
    "displayName": "My First Merchant",
    "legalEntityType": "CORPORATION",
    "merchantMode": "processing",
    "country": "USA",
    "defaultCurrency": "USD"
  }'

The response contains the merchant account id (ma_...). Keep it; the next step uses it.

Onboard the merchant

A merchant must complete onboarding before it can process or settle. Create a hosted onboarding link and send it to the merchant (or open it yourself in sandbox):

import {
  createMerchantOnboardingLink,
  createVortex,
} from "@vortex-api/vortex/2026-08";

const vortex = createVortex({ apiKey: process.env.VORTEX_API_KEY });

const merchantAccountId = "ma_...";

const { data, error } = await createMerchantOnboardingLink({
  client: vortex,
  path: { merchantAccountId },
  body: {
    environment: "sandbox",
    createdByRef: "operator:my-user-id",
  },
});
if (error) throw new Error(JSON.stringify(error));
console.log(data.data.hostedMerchantOnboardingUrl);

The hosted page shows the merchant the onboarding session, open requirements, and status. In sandbox the approval is usually fast. See Merchant onboarding for the full underwriting data model and requirement lifecycle.

Check onboarding status

Refresh the hosted onboarding page to see the session move from draft → submitted → under_review → approved. You can also watch the merchant account status in the dashboard.

When the session reaches approved, the merchant can process payments. If it lands on action_required, the page lists the open requirements; provide the requested documents or data and refresh.