1. Register a customer

Create the customer record

POST /v1/payments/customers

curl -X POST https://api-staging.checker.finance/v1/payments/customers \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Nonce: $(uuidgen)" \
  -H "X-Signature: $SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "client_reference": "shanghai-importer-001",
    "legal_name": "Shanghai Importers Ltd",
    "customer_type": "BUSINESS",
    "country": "CN",
    "email": "[email protected]",
    "phone": "+8613800138000",
    "address": {
      "line1": "88 Zhongshan Road",
      "city": "Shanghai",
      "postal_code": "200001",
      "country": "CN"
    },
    "kyb": {
      "business_entity_type": "CORPORATION",
      "business_registration_id_type": "BUSINESS_REGISTRATION",
      "business_registration_id_number": "913100001234567890",
      "website": "https://shanghai-importers.example"
    }
  }'

The customer is created PENDING and becomes ACTIVE once onboarding succeeds. kyb.attestation_ref is optional for this corridor, so the request above omits it; if you do send it, it is stored and returned as-is (and must not be empty). KYB fields may also be completed later with PATCH /v1/payments/customers/{customer_id}.

Upload a registration document (optional)

A registration document is optional for this corridor; onboarding succeeds without one. If you upload one, onboarding submits the newest file whose file_type matches kyb.business_registration_id_type (BUSINESS_REGISTRATION or ARTICLE_OF_ASSOCIATION).

POST /v1/payments/customers/{customer_id}/upload

curl -X POST https://api-staging.checker.finance/v1/payments/customers/cus_01ARZ3NDEKTSV4RRFFQ69G5FAV/upload \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Nonce: $(uuidgen)" \
  -H "X-Signature: $SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@business_registration.pdf" \
  -F "file_type=BUSINESS_REGISTRATION"

Onboard the customer

POST /v1/payments/customers/{customer_id}/onboard

curl -X POST https://api-staging.checker.finance/v1/payments/customers/cus_01ARZ3NDEKTSV4RRFFQ69G5FAV/onboard \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Nonce: $(uuidgen)" \
  -H "X-Signature: $SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "provider-b" }'

Poll GET /v1/payments/customers/{customer_id} until the matching onboarding entry reports ACTIVE. Missing KYB fields are reported as 422 MISSING_KYB_FIELDS with details.missing. This corridor does not require a terms signature.