Payment Async Notify (CP Callback)

The Nova platform delivers HTTP POST callbacks to the game CP notify_url after payment success or refund. This page describes the JSON + HMAC-SHA256 callback contract and includes PHP and Go verification examples.

End-to-end flow

Typical path from order creation to client acknowledgment (in-app purchase via Google Play or similar).

This is a product-level view. The async HTTP callback to your game server is what this page specifies. Refunds and other settlements follow the same notify-and-retry pattern when confirmed server-side.

1. Create order: the game calls the SDK backend to start payment; it returns a platform order id (linked to CP fields such as reference_id).
2. Store payment: the client opens Google Play (or other store); after the user pays, the client receives a purchase token (or equivalent).
3. Verify & settle: the client sends the token to the SDK backend, which validates it with the store and completes fulfillment on the platform side.
4. Notify CP (async): after payment is confirmed (and for refunds when settled server-side), the platform POSTs to the CP notify_url with the contract on this page — server-to-server only.
5. CP handling: verify signature, grant entitlement, return HTTP 2xx; non-2xx may trigger retries from the notifier.
6. Tell the player: the game server notifies the game client via push, realtime channel, polling, etc.

Note: after NovaSDK completes verification and order settlement, the platform posts asynchronously to the CP notify_url. The “SDK backend” in the diagram is this unified client + CP-facing layer.

Callback precedence

Use the order-level notify_url when present; otherwise fall back to the app-default notify_url configured in the console.

Request

Item	Value
Method	POST
Content-Type	application/json
Timeout	~3s server-side

Headers

Header	Description
NOVA-X-Callback-App-Id	App ID
NOVA-X-Callback-Timestamp	UTC ms timestamp
NOVA-X-Callback-Sign	HMAC-SHA256 hex (lowercase)
NOVA-X-Callback-Sign-Method	hmac-sha256

JSON body

Field	Type	Description
order_id	string	Nova order ID
app_id	number	App ID
uid	number	Player UID
reference_id	string	CP reference (cp_order_id)
extension	string	Order extension
timestamp	number	UTC ms timestamp
status	number	Order status: 1 paid, 4 refunded
payment_platform	string	Store channel, e.g. google, apple
goods_id	number	Product ID from order creation

Sample body:

{
  "order_id": "20250718112706471433",
  "app_id": 10001,
  "uid": 1003,
  "reference_id": "8f8bfa08-6471-ab96-8107-252407b67c80",
  "extension": "8f8bfa08-6471-ab96-8107-252407b67c80",
  "timestamp": 1753174571860,
  "status": 1,
  "payment_platform": "google",
  "goods_id": 1001
}

Signature

1. Params: app_id, extension, goods_id, order_id, payment_platform, reference_id, status, timestamp, uid (string values).
2. Sort keys ascending.
3. Join as k1=v1&k2=v2&....
4. HMAC-SHA256(plain, app_secret) → lowercase hex.
5. Compare to NOVA-X-Callback-Sign.

Response

Return HTTP 2xx on success. Response body format is not validated.

Retries

Up to 3 attempts: immediate, +15s, +1m.

Examples

See the Chinese version for full PHP and Go sample code.

References

• Publisher server integration