APIs integration

Authentication

Every request to the Ping Business API is authenticated with three HTTP headers:

X-PingBiz-API-Key: <your merchant API key>
X-PingBiz-Merchant-Identifier: <your merchant UUID>
X-PingBiz-Store-Identifier: <your store UUID>

On every request the API verifies that the key hash matches your merchant, that your merchant is active and KYB-approved, and that the store belongs to your merchant. The request is then executed as a store-scoped integration actor: everything you read and write is automatically scoped to that one merchant + store. There is no way to reach another merchant's data with your key, and no way to widen scope with query parameters.

curl https://biz-app.staging.pingbusiness.org/products \
  -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"

Keep your key server-side

The API key is a backend secret. It must never appear in:

  • browser JavaScript, HTML, or source maps
  • mobile app bundles
  • public repositories or client-reachable environment files
  • URLs or query strings (headers only)

Your website's frontend should call your own backend, and your backend calls Ping Business. If you find the key has leaked, mint a new one in the Merchant Portal immediately — minting a new key invalidates the old one atomically.

The merchant and store identifiers are not secrets by themselves (they identify, not authenticate), but there is no reason to expose them client-side either.

Authentication errors

Status Body Meaning
401 {"error": "Merchant API key missing"} No X-PingBiz-API-Key header.
403 {"error": "Merchant API key invalid"} Key doesn't match this merchant (revoked, mistyped, or wrong environment).
403 merchant/store scope error Identifier headers don't resolve, store doesn't belong to the merchant, or the merchant is suspended / not approved.

A 403 on previously working credentials usually means the key was re-minted, or the merchant was suspended — check the Merchant Portal.

TLS

All production traffic must use HTTPS. The staging and production base URLs are TLS-only.