One API, three rails
POST /v1/payments works the same whether the buyer pays with QRIS, a credit card via Polar, or PayPal. The gateway picks the rail based on currency + method + the app’s mode.
payment.uncle-z.com
One HTTP API for the uncle-z product portfolio. IDR via NICEPAY, USD via Polar, services via PayPal.
What this is
Section titled “What this is”payment.uncle-z.com is the single payment surface that every uncle-z product talks to. It abstracts the different PSPs (NICEPAY, Polar, PayPal) behind a uniform HMAC-signed HTTP API so each product writes the integration once.
Three modes per app
Every app is test, sandbox, or live. Test routes to a mock provider; sandbox hits real PSP sandboxes; live hits production. Two products at different modes can run side by side on the same gateway.
Webhooks with HMAC verification
Inbound PSP events become canonical payment.succeeded / subscription.canceled events delivered to your product, signed with your app’s webhook secret. Idempotent and retried with exponential backoff.
No PSP coupling on your side
Your code never imports a NICEPAY SDK or a Polar SDK. PSP quirks (NICEPAY’s userIP/shopId, Polar’s polar_product_id, signature schemes) all live behind the gateway.
Where to start
Section titled “Where to start”- Quickstart — Create an app, sign your first request, complete a checkout in 5 minutes.
- Modes — Understand
testvssandboxvslive. This is the first thing every integrator gets confused about. - Authentication & signing — The HMAC scheme used on every request. Reference signers in JS, Go, PHP.
- Pick your guide: Polar subscriptions, QRIS via NICEPAY, PayPal for services, or POS retail.
Going-forward stack
Section titled “Going-forward stack”The gateway routes traffic through:
| Currency | Product type | method | PSP |
|---|---|---|---|
| IDR | Anything | qris / va_bca / va_mandiri / va_bni / va_bri / va_permata | NICEPAY |
| USD/EUR/GBP | SaaS / digital products / one-time licenses | polar (override) | Polar.sh (Merchant of Record) |
| USD/EUR/GBP | Services (productized human work) | paypal (override) | PayPal — Polar’s AUP rejects services |
Older docs / commits may mention DOKU and Paddle — those rails are out of scope going forward; ignore them.