# Payment Hub

Payment Hub is a private multi-project payment orchestration API. Project backends create and query payment orders. Payment Hub never owns project accounts or entitlements.

## Canonical resources

- Human documentation: https://payments.null2null.com/docs/
- Complete AI integration guide: https://payments.null2null.com/docs/integration.md
- OpenAPI 3.1 contract: https://payments.null2null.com/openapi.json
- Service health: https://payments.null2null.com/health

## Mandatory integration rules

- Call Payment Hub only from a project backend.
- Never expose a project API key to a browser, mobile app, desktop app, repository, analytics event, or log.
- Create a local merchant order before calling Payment Hub.
- Use a stable Idempotency-Key for every order create attempt and every retry of that attempt.
- Treat prices, currencies, providers, channels, wallets, and payment methods as server-side configuration.
- Verify project webhooks with HMAC-SHA256 over timestamp + "." + eventId + "." + rawBody.
- Use the raw request body and a constant-time signature comparison.
- Reject replayed or stale events and process each event ID once.
- Grant entitlement only when an authenticated Payment Hub order state is succeeded.
- Never grant entitlement for creating, waiting, partially_paid, processing, failed, or expired.
- Process refunded idempotently according to the project's documented revocation policy.
- Reconcile non-terminal local orders through the authenticated query API.
- Do not use external checkout in App Store iOS or Google Play Android builds.

## Public project API

- POST /v1/orders
- GET /v1/orders/{orderId}
- GET /v1/orders/by-merchant-order/{merchantOrderId}

Administrative provisioning is internal and is not publicly reachable. Ask the Payment Hub operator to provision each project, provider account, product route, webhook secret, and project API key.
Provider accounts and products are staged inactive and require explicit operator activation after provider credential and checkout-security validation.