Customers quickstart

Every end-customer must complete KYC in the customer vault. You get a stable customer_id (pcus_*) for quotes and accepts. Banking (IBAN, ledger, sends) is a separate optional product — see Accounts. KYC alone is enough for corridor ramps.

Inline customer on quote is deprecated (still supported during migration). Use customer_id once status=approved. See Quote and accept.

Two gates (do not confuse them)

Gate	Field	Unlocks
KYC / quotes	`status` = `approved`	`customer_id` on quote and accept
Banking	`products.deposit_account.status` = `ready`	Accounts, deposit instructions, sends

KYC (required for everyone)
  requirements → create → documents → submit → approved
        │
        ├─→ Quote / accept with customer_id
        │
        └─→ (optional) deposit_account ready → Banking APIs

Auth and environments

export BASE="https://sandbox.elementpay.net/api/v1"
export API_KEY="is_test_…"

Production base: https://api.elementpay.net/api/v1 with is_live_… keys.

X-API-Key: <API_KEY>
Content-Type: application/json

Live: after submit, Element Pay reviews and approves customers. Sandbox may auto-approve — still verify status via GET or webhooks.

Status model

Status	Meaning
`incomplete`	Profile / docs still being collected
`pending_review`	Submitted; waiting for Element Pay review
`approved`	May quote / accept with `customer_id`
`rejected`	Review declined
`suspended`	Partner offboarded or blocked — cannot quote, patch, or open new banking activity

Happy path

Requirements

GET /partner/customers/requirements

Create

POST /partner/customers with profile

Documents

Upload required categories

Submit

→ typically pending_review

Wait for approved

Prefer webhooks (customer.approved); poll GET /partner/customers/{customer_id} as backup until status=approved

Quote and accept

customer_id on POST /partner/orders/quote — required path for new integrations

1. Requirements

curl -sS "$BASE/partner/customers/requirements?type=individual" \
  -H "X-API-Key: $API_KEY" | jq '.data'

curl -sS "$BASE/partner/customers/requirements?type=business&country=US" \
  -H "X-API-Key: $API_KEY" | jq '.data'

Collect the returned required_fields, required_documents, and any conditional_fields for the customer’s country.

Business nested fields: top-level required_fields lists "officers" only. Per-officer fields live under data.field_shapes.officers.item_shape. While the customer is incomplete, GET /partner/customers/{customer_id} returns missing[] with indexed paths (e.g. profile.officers[0].identity_document.number) — use that to drive your form.

Individual (always required before submit): besides name, contact, DOB, and gender, the vault package includes profile.address (line1, city, country), profile.id_number (government ID number), and profile.id_type (e.g. passport, national_id, drivers_license). Upload identity and address documents matching requirements. Business (required before submit): top-level company fields from required_fields, plus each profile.officers[] entry must include:

Area	Fields
Person	`first_name`, `last_name`, `date_of_birth`, `email`, `nationality`, `role` or `job_title`
Identity	`identity_document.type`, `identity_document.number`, `identity_document.issuing_country`
Address	`address.line1`, `address.city`, `address.country`

Uploading officer identity and address document files is required, but does not replace the ID number and address in profile JSON. profile.industry must be plain language (e.g. Payment services, fintech) — not a numeric category code like 7372. Nigeria (country_of_residence: NG): also requires profile.additional_id_type (bvn) and profile.additional_id_number (11-digit BVN). Same rules apply on sandbox and live — call requirements on each environment; do not rely on copy-paste examples alone.

2. Create customer

Idempotent on partner_customer_ref per tenant. Call requirements first for the exact required_fields / required_documents for type=individual or type=business (and country when relevant).

Individual

Illustrative shape — GET /partner/customers/requirements?type=individual is source of truth. Include id_number and id_type before submit (omitting either returns 422 with profile.id_type or profile.id_number in missing[]).

curl -sS -X POST "$BASE/partner/customers" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "partner_customer_ref": "partner-cust-001",
    "type": "individual",
    "profile": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "date_of_birth": "1990-01-15",
      "country_of_residence": "GB",
      "phone": "+447700900123",
      "gender": "f",
      "id_number": "A1234567",
      "id_type": "passport",
      "address": {
        "line1": "1 Example Street",
        "city": "London",
        "country": "GB",
        "postal_code": "E1 6AN"
      }
    }
  }' | jq '.data | {id, status, partner_customer_ref, missing}'

Business

Illustrative shape — treat requirements and missing[] as source of truth. US-incorporated businesses also need tax_id (EIN). Each officer must be complete in profile JSON before submit (see table in Requirements). This is not a full UBO/shareholder program — at least one complete officer is required; if you send multiple officers, validate each. Quote / accept note: when you pass customer_id on quote for a business, we hydrate company fields only (legal_name → business_name, registration_number → business_id, email, country). Officer details are for vault KYC / deposit banking, not corridor quote party building.

curl -sS -X POST "$BASE/partner/customers" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "partner_customer_ref": "partner-biz-001",
    "type": "business",
    "profile": {
      "legal_name": "Acme Payments Ltd",
      "email": "ops@acme.example",
      "phone": "+14155550100",
      "website": "https://acme.example",
      "business_type": "llc",
      "country_of_incorporation": "US",
      "tax_id": "123456789",
      "registration_number": "REG-001",
      "industry": "Payment services",
      "description": "B2B payments for SMEs",
      "registered_address": {
        "line1": "100 Market Street",
        "city": "San Francisco",
        "state": "CA",
        "country": "US",
        "postal_code": "94105"
      },
      "incorporation_meta": {
        "year": 2020,
        "month": 6,
        "country": "US",
        "state": "CA"
      },
      "monthly_payments_count": 100,
      "monthly_transaction_value": 250000,
      "max_transfer_amount": 50000,
      "annual_turnover": 2000000,
      "customer_types": ["b2b"],
      "funding_source": "equity",
      "officers": [
        {
          "role": "director",
          "first_name": "Ada",
          "last_name": "Lovelace",
          "date_of_birth": "1990-01-15",
          "email": "ada@acme.example",
          "nationality": "US",
          "identity_document": {
            "type": "passport",
            "number": "A1234567",
            "issuing_country": "US"
          },
          "address": {
            "line1": "200 Officer Lane",
            "city": "San Francisco",
            "state": "CA",
            "country": "US",
            "postal_code": "94105"
          }
        }
      ]
    }
  }' | jq '.data | {id, status, partner_customer_ref, missing}'

Poll completeness while status is incomplete:

curl -sS "$BASE/partner/customers/$CUSTOMER_ID" \
  -H "X-API-Key: $API_KEY" | jq '.data | {status, missing}'

Example incomplete officer → missing includes profile.officers[0].identity_document.number until PATCHed. Save data.id (pcus_*). While incomplete: PATCH /partner/customers/{customer_id} with {"profile": { … }}. List: GET /partner/customers?status=incomplete&limit=50. Lookup by your ref: GET /partner/customers?partner_customer_ref=partner-cust-001.

3. Upload documents

JSON + Base64. category must match a requirements document key.

export CUSTOMER_ID="pcus_…"

curl -sS -X POST "$BASE/partner/customers/$CUSTOMER_ID/documents" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "identity",
    "file_name": "passport.pdf",
    "content_type": "application/pdf",
    "content_base64": "<BASE64>"
  }' | jq '.data'

curl -sS -X POST "$BASE/partner/customers/$CUSTOMER_ID/documents" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "address",
    "file_name": "utility_bill.pdf",
    "content_type": "application/pdf",
    "content_base64": "<BASE64>"
  }' | jq '.data'

4. Submit

curl -sS -X POST "$BASE/partner/customers/$CUSTOMER_ID/submit" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' | jq '.data | {id, status}'

Incomplete package → 422 with data.code: package_incomplete and missing[] (e.g. profile.officers[0].identity_document.number, document.identity).

5. Wait until approved (webhooks + poll)

We send signed partner webhooks for vault lifecycle events (same key webhook_url / webhook_secret as orders). Typical events:

Event	When
`customer.submitted`	After a successful submit
`customer.approved`	Element Pay approves the case
`customer.rejected`	Review declines the case
`customer.revoked`	Partner offboarded the customer → `suspended`
`customer.updated`	Material status / product update
`customer.deposit_account.updated`	Deposit-account product status changes (e.g. `ready` for Accounts)

Treat webhooks as the primary signal for review outcomes and banking readiness. Poll GET /partner/customers/{customer_id} as a backup if a webhook is delayed or missed. Full payload shapes: Webhooks.

curl -sS "$BASE/partner/customers/$CUSTOMER_ID" \
  -H "X-API-Key: $API_KEY" | jq '{
    id: .data.id,
    status: .data.status,
    partner_customer_ref: .data.partner_customer_ref
  }'

Example:

{
  "id": "pcus_…",
  "status": "approved",
  "partner_customer_ref": "partner-cust-001"
}

Use customer_id on quote only when status == "approved".

6. Revoke (partner offboarding)

When an end-customer should no longer use Element Pay under your integration, call revoke. The vault case moves to suspended. There is no partner reinstate endpoint in v1 — create a new customer if the person returns later.

curl -sS -X POST "$BASE/partner/customers/$CUSTOMER_ID/revoke" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "account_closed"}' | jq '.data | {id, status, updated_at}'

Behavior	Detail
Allowed from	`incomplete`, `pending_review`, `approved`, `active`
Result	`status: suspended`
Idempotent	Already `suspended` or `rejected` → 200 with current customer (no duplicate webhook)
Optional body	`reason` (max 512 chars) — audit-only; not echoed in API JSON
After revoke	`PATCH` → 409; `POST /partner/orders/quote` with this `customer_id` → 422 (`Customer is not approved for orders`)
Webhook	`customer.revoked` when status transitions to `suspended`

7. Quote and accept with `customer_id`

After status=approved, use customer_id on quote. Full response examples: Quote and accept. Discover network_id from catalog for the same country + order_type:

curl -sS "$BASE/partner/catalog?country=KE&order_type=OnRamp" \
  -H "X-API-Key: $API_KEY" \
  | jq '.data.onramp.countries.KE.payment_methods.mobile_money.providers[] | {id, name}'

KE OnRamp (momo):

curl -sS -X POST "$BASE/partner/orders/quote" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order_type": "OnRamp",
    "currency": "KES",
    "country": "KE",
    "local_amount": 800,
    "customer_id": "'"$CUSTOMER_ID"'",
    "asset": {
      "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bdA02913",
      "currency": "USDC",
      "network": "BASE"
    },
    "payment_method": {
      "type": "mobile_money",
      "phone_number": "+2541111111111",
      "network_id": "7ea6df5c-6bba-46b2-a7e6-f511959e7edb"
    },
    "wallet_address": "0xde0B295669a9FD93d5F28D9Ec85E40f4cb697BAe"
  }' | tee /tmp/quote.json | jq '{quote_id: .data.quote_id, expires_at: .data.expires_at}'

export QUOTE_ID=$(jq -r '.data.quote_id' /tmp/quote.json)
sleep 2

curl -sS -X POST "$BASE/partner/orders/$QUOTE_ID/accept" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' | jq '.data | {quote_id, status, order: .order.order_id}'

OnRamp quote ids are typically yc_receive_…. Use asset: { token, currency, network } — not a bare top-level "token".

Errors

Situation	Typical	Action
Missing profile/docs on submit	`422` + `missing[]` (e.g. `profile.id_type`, `profile.id_number`, `profile.officers[0].identity_document.number`, `document.identity`)	PATCH / upload until `GET` shows empty `missing[]`, then resubmit
Quote with unapproved / suspended `customer_id`	`422`	Wait for `approved` or use another customer
Revoke after offboard	`409` on PATCH	Expected — customer is terminal for edits
Unknown / other-tenant id	`404`	Use id from this API key
Bad key	`401`	Fix `X-API-Key`

Quote and accept — OffRamp, response fields, deprecated inline
Route cheat sheet — KYC vs banking routes
Webhooks
Quickstart — condensed end-to-end
Banking / accounts — optional, after deposit account ready

Get started

Customer KYC

Banking

Corridors

Sandbox

Quickstart

Customers quickstart

Two gates (do not confuse them)

Auth and environments

Status model

Happy path

1. Requirements

2. Create customer

Individual

Business

3. Upload documents

4. Submit

5. Wait until approved (webhooks + poll)

6. Revoke (partner offboarding)

7. Quote and accept with `customer_id`

Errors

Next

​Customers quickstart

​Two gates (do not confuse them)

​Auth and environments

​Status model

​Happy path

​1. Requirements

​2. Create customer

​Individual

​Business

​3. Upload documents

​4. Submit

​5. Wait until approved (webhooks + poll)

​6. Revoke (partner offboarding)

​7. Quote and accept with customer_id

​Errors

​Next

Customers quickstart

Two gates (do not confuse them)

Auth and environments

Status model

Happy path

1. Requirements

2. Create customer

Individual

Business

3. Upload documents

4. Submit

5. Wait until approved (webhooks + poll)

6. Revoke (partner offboarding)

7. Quote and accept with `customer_id`

Errors

Next