# Veyqo payment integration instructions

Read https://veyqo.org/docs-markdown/veyqo.md and the current endpoint contract before changing payment code.
Contract: https://veyqo.org/openapi.json
Docs index: https://veyqo.org/llms.txt
Detailed examples: https://veyqo.org/llms-full.txt

- Merge this into the application's existing instructions; do not replace them.
- Inspect the server stack and existing order, payment, webhook and test code first.
- Use the server API at https://api.veyqo.org/api/v1 with a scoped Veyqo secret key from server environment variables.
- Keep provider credentials, Veyqo API keys and webhook signing secrets separate.
- Calculate integer minor-unit prices from trusted server-side order data.
- Create and save a checkout session server-side; open data.url or its saved cs_ ID.
- Direct payment responses use data.checkout_url, not data.checkout.url.
- Persist one idempotency key per create/refund operation. Preserve key and body on retry.
- Do not reuse an idempotency key for verification polls.
- A redirect or browser callback is not fulfilment authorization. Verify current payment status, amount, currency and trusted order/session association server-side.
- Verify Veyqo-Signature raw hexadecimal digests over timestamp+'.'+raw body, with constant-time comparison and a 300-second tolerance. Accept matching comma-separated digests during rotation.
- Store events durably, deduplicate by event.id and fulfil orders atomically once.
- Handle every documented HTTP/error code with appropriate retry behavior. Reconcile unknown charge outcomes before creating another charge.
- Shared provider accounts do not merge projects. Use the key for the original project environment, and preserve historical account ownership on switches/refunds.
- Use only documented Veyqo endpoints and the hosted checkout.js script; do not invent npm SDKs, MCP tools, transfers APIs or webhook-management REST routes.
- Test duplicate events, invalid/expired signatures, amount/currency mismatches, retries, wrong environments and partial refunds.
- Use sandbox while developing. Never read, print, commit or deploy production secrets.
- State the dashboard settings and environment-variable names needed, run the application's relevant checks, and report unresolved assumptions.

Reference: https://code.claude.com/docs/en/memory