Onboarding isn't instant. A business you create starts incomplete, gathers what it needs, is submitted for underwriting, and only then goes live and can accept payments. This page is the shared reference for that lifecycle. Every action page links here instead of repeating it.

🚧

PENDING-PUBLISH

The boarding API Reference is pending publication; the ref: targets on this page are placeholders. Replace each with the real boarding-spec operationId once the boarding reference ships.

The boarding lifecycle

stateDiagram-v2
    direction TB
    [*] --> Saved: POST /v1/businesses
    Saved --> PENDING_REQUIREMENTS: enable a service
    PENDING_REQUIREMENTS --> PENDING_UNDERWRITING: requirements complete
    PENDING_UNDERWRITING --> ACTIVE: underwriting approves
    ACTIVE --> CLOSED: close
    CLOSED --> [*]

    Saved: Saved (no status yet)

0. Saved (no status): right after POST /v1/businesses, the business is just saved: id, the fields you sent, and timestamps. It carries no status until you opt into a service.
1. PENDING_REQUIREMENTS: a service has been opted into, but the business is still missing data or documents. What's outstanding is surfaced inline (see below).
2. PENDING_UNDERWRITING: requirements are complete and a service is enabled; underwriting is reviewing.
3. ACTIVE: approved. The business (and its approved services) can operate.
4. CLOSED: the business is closed and no longer operates.

🚧

PENDING-PUBLISH

The close operation is not present in the tested boarding collection (which contains only GET, POST, PATCH, and PUT). Confirm with engineering whether a close endpoint exists and, if so, its method, its response, the resulting status (CLOSED), whether the record is retained, and whether an externalId can be reused afterward. Until confirmed, describe it plainly as a delete and treat the close behavior as unverified.

How underwriting works

Underwriting is asynchronous. Once a business is complete, PCE submits it for review and keeps its status in sync. The decision flows back onto the business automatically, so allow a short delay. A few things worth knowing:

• Status starts with a service. Before you opt into a service, a business simply saves your data and reports no status. Once a service is enabled it sits in PENDING_REQUIREMENTS while you complete it, moves to PENDING_UNDERWRITING when it's complete, and goes live on approval. There's no separate draft state.
• Close a business. Created a business you didn't mean to, or need to close one? You can close it (see the note above on the close operation).
• Watch for the outcome. Keep reading the business back to see the result; there are no status webhooks.

Status by resource

Each resource carries its own status; the business's overall readiness is the combination.

🚧

PENDING-PUBLISH

Two status-vocabulary conflicts are unresolved in the source contract: an enabled service appears as both ENABLED and ACTIVE in different examples, and a pending-disable feature as both PENDING and PENDING_DISABLE. This table uses the ACTIVE / PENDING_DISABLE forms. Confirm the authoritative enum against the API Reference before publish.

Before you can enable a service

A service can't go to underwriting until the business has the basics attached. For Accept Payments (services.payin.card), that means:

• The business is created.
• At least one owner or signatory, with exactly one marked as the control person.
• At least one location with its processing profile.
• At least one bank account attached (where settled funds land, fees are paid, or both).
• Any required documents provided.

When these are in place, enable the service. PCE then tells you if anything is still missing (see below) before moving the business to review.

What's still needed

Onboarding has no separate "requirements" resource to poll. Instead, each service object on the business carries three read-only fields that tell you exactly what's outstanding:

Read them with a GET request to /v1/businesses/{businessId} (add ?expand=true) and inspect services.payin.card.

curl "https://sandbox-api.prioritycommerce.com/v1/businesses/{businessId}?expand=true" \
  -H "x-api-key: <your-key>"

Response: 200 OK (the services.payin.card subtree)

{
  "services": {
    "payin": {
      "card": {
        "uri": "/v1/businesses/bus_42/services/payin/card",
        "enabled": true,
        "status": "PENDING_UNDERWRITING",
        "missingFields": [],
        "missingDocuments": [],
        "errors": []
      }
    }
  }
}

Empty arrays with status: PENDING_UNDERWRITING mean the service has everything it needs and is waiting on a decision. Non-empty arrays tell you precisely what to fix or add.

A review-ready business is exactly that shape: its requirements are cleared, missingFields and missingDocuments are empty, and its status has advanced to PENDING_UNDERWRITING. At that point there is nothing left to send; you track it to ACTIVE. See What to expect on the Underwriting hub.

Tracking a business

Make a GET request to /v1/businesses/{businessId} again to follow status changes as you complete requirements and as underwriting decides. Re-reading the business is the way to see a change; there are no status webhooks.

Poll on a gentle cadence and let the work set how often you read:

• While you complete requirements, read the business back after each change to confirm missingFields, missingDocuments, and errors cleared.
• While you wait on the underwriting decision, poll on an interval and apply exponential backoff between reads rather than tight-looping.
• Stop polling once the business reaches a terminal state (ACTIVE or CLOSED).

🚧

PENDING-PUBLISH

Two things to confirm before publish. First, the recommended re-read interval and backoff ceiling (the exact numbers) are not set by the contract; confirm sensible defaults with engineering. Second, confirm whether onboarding emits webhooks for status transitions (business → underwriting → active, service approved/declined); if it does, document the event names and payload here and switch this section from polling to event-driven. The boarding contract did not model a writable webhook subscription resource; verify current behavior before publish.

Next steps

See also

• Create a business: where the lifecycle begins
• Underwriting exceptions: in-flight requirements and rejections
• Businesses: the resources each status applies to