APIs integration

Introduction

Welcome to the Ping Business API.

Ping Business lets you accept payments in Hong Kong — cards, Alipay, WeChat Pay, FPS, Octopus, PayMe and UnionPay — from your own website, without ever touching card data yourself. Your server talks to the Ping Business API; your customer pays on the payment gateway's hosted page; Ping Business verifies the result and hands you a finalized order.

This documentation is for merchants who already have a website and want to add Ping Business payments to it. If you don't have a website yet, use the Merchant Store Vibe Coding Kit instead — it deploys a complete, customizable store for you.

How an integration works

Your customer's browser
        │  1. clicks "Pay"
        ▼
Your website backend  ──────────────►  Ping Business API (biz-app)
        │   2. create intent,             validates products, prices,
        │      request checkout           signs a gateway launch form
        │◄──────────────────────────────
        │  3. auto-submit signed form
        ▼
Payment gateway (PaymentAsia hosted page)
        │  4. customer pays
        ▼
Your return_url / notify_url  ─────►  POST /paymentasia/record_payment
                                          verifies the signature,
                                          creates order + payment,
                                          marks checkout successful

Three things to internalize before you start:

  1. All API calls are server-to-server. Your API key must never appear in a browser, a mobile app bundle, or client-side JavaScript. The customer's browser only ever sees the signed payment form and your own pages.
  2. Ping Business is the source of truth for money. You never tell the API "this payment succeeded" — you forward the gateway's signed callback and Ping Business verifies it cryptographically. Prices come from your approved product catalog, not from the request.
  3. Orders are results, not requests. You never create orders. A successful, verified payment creates the order, its line items, and the payment record atomically.

Core concepts

Object What it is
Merchant Your business. Identified by a merchant identifier (UUID). Holds your KYB status, payment-network configuration, and API key.
Store A sales channel belonging to your merchant. Identified by a store identifier (UUID). Has a mode: T (test) or L (live).
Product Something you sell. Created and managed in the Merchant Portal; each listing is reviewed before it becomes purchasable (state: "A", approved). A product with recurring fields is a subscription product.
Customer A buyer record scoped to your merchant and store. You create these via the API to attach checkouts to.
Intent A checkout in progress. Created by you before payment; carries the currency, total, and an immutable snapshot of the cart. Status: C created → R redirected → S success / F failed / U unknown.
Order / Order item Created by Ping Business only after a verified successful payment (or accepted subscription schedule). Read-only to you.
Payment An immutable record of a verified successful one-time payment.

Environments

Environment Base URL
Staging https://biz-app.staging.pingbusiness.org
Production https://biz-app.pingbusiness.org

Each environment has its own merchant portal, credentials, and data. Develop against staging; switch base URL and credentials to go live. Within an environment, each store also has a test/live mode (T/L) toggled from the Merchant Portal.

What the API does and doesn't do

You can: read your merchant/store configuration, manage customers, read your approved catalog and inventory, create checkout intents, launch hosted payments, record verified gateway callbacks, enroll subscriptions, and read orders, order items, and payments.

You can't (by design): create or modify products (Merchant Portal only), create orders or payments directly, mark an intent successful yourself, or read another merchant's data. Write access to money-movement state exists only through the verified payment flow.

Next steps