Getting started

Before your server can call the API, your business needs to be onboarded and approved. This is a one-time setup done in the Merchant Portal (not via the API).

1. Create your merchant account

Register in the Merchant Portal. This creates your merchant record and your manager login. Your merchant starts with KYB status in_review.

2. Pass business verification (KYB)

The Ping Business compliance team reviews your registration. You can watch the status in the portal:

KYB status	Meaning
in_review	Under review. You can sign in and look around, but cannot mint an API key.
approved	Verified. You can mint your API key and go live.
rejected	Rejected — the portal shows the reason and what to fix.

Gate #1 — enforced by the backend: the API key cannot be created until KYB is approved. Attempting earlier returns 409 Conflict.

3. Create a store

In the portal, create at least one store. Note its store identifier (UUID) — your integration is scoped to exactly one merchant + one store per credential set. New stores start in test mode (T); switch to live mode (L) from the portal when you're ready.

4. Create products and get them approved

Products are created and edited in the Merchant Portal only — the integration API reads them but never writes them. Every product listing goes through review:

Listing status	Meaning
pending	Awaiting review. Not purchasable.
approved	Purchasable — appears in API reads with state: "A".
rejected	Not purchasable; portal shows review notes.

Gate #2 — enforced by the backend: checkout is blocked (403) for products that aren't approved, even if you know their IDs.

For a subscription product, set the three recurring fields when creating it: recurring_frequency (WEEKLY | MONTHLY | YEARLY), recurring_intervals, and recurring_total_execution_times. Subscription products must be priced in HKD.

5. Configure your payment networks

In the portal, configure which payment methods your checkout offers. Available networks:

CreditCard · Alipay · Wechat · CUP · Fps · Octopus · PayMe

Your integration should read the current list from your merchant record at runtime (GET /merchants) rather than hard-coding it. Two special rules:

• Octopus totals must be an exact multiple of HKD 0.10 — incompatible totals are rejected before a payment form is signed.
• Subscriptions require the CreditCard network to be enabled.

6. Mint your API key

Once KYB is approved, generate your API key in the Merchant Portal (Settings → API key).

The key is shown exactly once. Ping Business stores only a hash. Copy it into your server's secret store immediately — if you lose it, mint a new one (which invalidates the old one).

You now have the three values every API request needs:

Credential	Example	Where you got it
Merchant API key	pk_... (opaque secret)	Shown once at minting
Merchant identifier	9b2f0e64-... (UUID)	Merchant Portal
Store identifier	2c7a1d90-... (UUID)	Merchant Portal

7. Make your first call

Verify your credentials by reading your own merchant record:

curl https://biz-app.staging.pingbusiness.org/merchants \
  -H "X-PingBiz-API-Key: $PINGBIZ_MERCHANT_API_KEY" \
  -H "X-PingBiz-Merchant-Identifier: $PINGBIZ_MERCHANT_IDENTIFIER" \
  -H "X-PingBiz-Store-Identifier: $PINGBIZ_STORE_IDENTIFIER" \
  -G -d "identifier=$PINGBIZ_MERCHANT_IDENTIFIER"

A 200 with your merchant record (including payment_networks) means you're ready for the quickstart.