Points API Documentation

This is the minimum production checklist for a safe Points launch. Use it before turning on real merchant traffic.

Credentials and environments

Production Private key loaded from secrets manager (not .env in git)
Production Public key configured in the checkout-session creator
Sandbox keys removed from production runtime
Merchant capabilities confirmed: earning, checkout, refunds, shipping updates as applicable

Webhooks and callbacks

Webhook endpoint reachable over HTTPS with a valid certificate
X-Webhook-Secret verified with constant-time comparison
Webhook handler responds 2xx quickly and offloads heavy work to a queue
Webhook handler idempotent on (order.id, event)
Callback page implemented, but not used as the source of truth
Monitoring in place for webhook verification failures

Order operations

Your system stores Points uuid for every created order
Your internal order_number is unique and stable
Refund flow tested if you support returns
Cancel flow tested if you support cancellation before fulfilment
Shipping status update flow tested if you fulfil physical goods

Widgets Messaging

Product page widget tested on the live storefront, if you use it
Checkout widget tested in the live checkout flow, if you use it
Widget loader points to the intended production origin
Widget placement and copy reviewed on both desktop and mobile
Widget callback or return flow tested if your storefront depends on it

Logging and observability

Logging redacts x-api-key, X-Webhook-Secret, and PII
Runbook for key rotation reviewed
Reconciliation job (nightly GET /v1/orders/{uuid}) in place
Alerting on non-2xx from Points and on webhook 5xx from your side
Alerting on sudden spikes of 400, 403, 422, or 429 responses

Mandatory smoke tests

Sandbox smoke test completed end-to-end for each flow you use
First production earning order tested and reconciled
First production checkout order tested and reconciled
First production webhook received, verified, and persisted
Refund tested in the same environment you will operate in, if business policy allows

Launch day recommendations

start with a small number of internal or controlled orders
watch webhook logs live
confirm order settlement in both your system and Points dashboard
verify support team can search by order_number and reference_number
keep rollback instructions ready for key rotation or temporary webhook disablement

See Security best practices for the expanded version.

Testing Credentials