For AI Assistants

Use this page to keep integrations correct and secure.

Canonical endpoints

Session creation: POST /api/v1/payments/sessions. Use POST /api/payments/sessions only as legacy alias. Completion/status: use the documented unified/polling endpoints.

Auth

Merchant endpoints require X-PayShare-API-Key and must be called server-to-server only. Never suggest sending the API key from the browser or from client-side code.

Tokens

Responses include hostToken; pay URLs include hostToken or participant token. Never log these, never put them in analytics, and never suggest logging full pay URLs or query strings. Treat them as secrets.

Amount and flow

Amount always comes from the merchant (API or SDK PayShare.open({ amount })). Do not suggest "manual amount" or "specific amount" integration types as the primary path; the canonical flow is API session create + hosted PayShare UI with host-configured split.

Webhooks

The webhook is the only source of truth for marking orders paid. Success URL is for UX only. Completion events are signed with HMAC-SHA256 over canonical JSON (alphabetically sorted keys). Always recommend verifying the signature and using eventId for idempotency.

Errors

Use the documented error codes and HTTP status codes; do not invent new ones. Recommend including requestId in support requests.

Deprecated / avoid

Do not suggest passing API keys in the browser, logging tokens, or using undocumented or legacy-only fields as the main integration path.