Guide

Onboarding & account readiness

Before a merchant can be charged, they must complete onboarding and be approved for processing. Pay-Pi handles KYC, underwriting, and compliance; you drive the merchant to a hosted form and check their readiness with one endpoint.

Hosted onboarding form

Merchants complete a hosted Finix onboarding form — you don't build or store any of it. The link to send them to is returned as onboardingUrl from the status endpoint below. Once they submit, their application moves into review, and Pay-Pi enables charges and payouts when approved.

Check readiness

Call GET /v1/onboarding/status to see whether a merchant can accept payments and what, if anything, is outstanding.

curl https://connect.pay-pi.com/v1/onboarding/status \
  -H "X-Api-Key: lc_live_..."

{
  "onboardingStatus": "pending",
  "chargesEnabled": false,
  "payoutsEnabled": false,
  "reasons": [
    { "code": "under_review", "message": "Your merchant application is under review." }
  ],
  "requirements": [
    { "code": "document.bank_statement", "message": "Upload a recent bank statement." }
  ],
  "pci": { "status": "unknown", "validUntil": null },
  "onboardingUrl": "https://onboard.pay-pi.com/..."
}

Response fields

onboardingStatusnot_started, pending, enabled, or restricted.

chargesEnabledWhether the merchant can accept payments right now.

payoutsEnabledWhether funds can settle to the merchant's bank.

reasonsWhy the account isn't ready (e.g. under review). Each has a code and message.

requirementsOutstanding items the merchant must provide (e.g. a document).

pciPCI validation state: status and validUntil.

onboardingUrlHosted form link to send the merchant to, or null when nothing is needed.

Charging before a merchant is ready

If you attempt POST /v1/payments while chargesEnabled is false, the API rejects it with a 403 merchant-not-ready. Check readiness first, and surface the reasons and requirements to your merchant so they can finish onboarding. The merchant dashboard renders this same readiness information for merchants automatically.