Build with your AI coding agent

# Veyqo integration

Read docs/veyqo.md before changing payment code.
Keep API keys server-side. Calculate totals from stored order data.
Verify signed webhooks and make order fulfilment idempotent.
Run the project’s existing payment tests after changes.

# Payment integration instructions

Before changing payments, read docs/veyqo.md.
Use the Veyqo REST API; do not invent SDK package names.
Keep credentials in server environment variables.
Verify signatures using the raw request body.
Test duplicate events, retries and amount mismatches.
Run this repository’s existing checks before finishing.

Read https://veyqo.org/llms-full.txt and inspect this application's stack.
Integrate Veyqo hosted checkout using our existing server and order model.
Create the checkout session server-side with a sandbox secret from the environment.
Use the stored order total in minor units, currency and reference.
Add a signed webhook handler with raw-body signature validation, a five-minute
replay window, event deduplication and idempotent order fulfilment.
Verify payment status, amount, currency and reference before fulfilling an order.
Handle API errors and reuse a persisted idempotency key on retries.
Keep secrets server-side and add meaningful tests. Tell me which dashboard
settings and environment variables I need to configure. Do not deploy.

# Integrating Veyqo

Veyqo connects a merchant's existing payment provider accounts through one API.
Public API base: https://api.veyqo.org/api/v1
Documentation: https://veyqo.org/docs
Full integration context: https://veyqo.org/llms-full.txt

- Use Authorization: Bearer $VEYQO_SECRET_KEY on your server only.
- API keys, project assignments and outgoing webhooks belong to one project environment.
- Provider credential accounts may be dedicated or shared across projects in the
  same organization and environment type. Switch assignments for new payments;
  keep existing payments and refunds tied to their original account.
- Start in sandbox. Use provider test credentials with your sandbox key.
- Amounts are integers in the smallest currency unit: 50000 NGN is NGN 500.00.
- Calculate prices from trusted server-side order data, never browser input.
- POST /payments creates a payment; data.checkout.url is its checkout URL.
- POST /checkout/sessions creates hosted checkout; data.id is the session ID.
- Persist an Idempotency-Key per logical POST operation. Reuse it with the same
  body on retries; use a new key for a different operation.
- Use GET /payments/{id} or POST /payments/{id}/verify to check a payment.
- Verify requires payments:read; create requires payments:write.
- Webhooks use Veyqo-Signature and Veyqo-Timestamp headers.
- Verify HMAC-SHA256(secret, timestamp + '.' + raw request body), compare in
  constant time, accept any matching comma-separated signature during rotation,
  and reject timestamps more than 300 seconds from now.
- Deduplicate events by event ID and make fulfilment idempotent.
- Fulfil only after trusted server confirmation of succeeded status and a match
  on the stored order reference, amount and currency. A redirect is not proof.
- POST /payments/{id}/refunds supports full or partial refunds (refunds:write).
- Responses use { success, data } or { success: false, error: { code, message, details } }.
- Check response status and success before reading data. Respect Retry-After.
- Never log API secrets, invent SDK packages, or assume an MCP server exists.
- Read the current API reference for endpoint fields and supported capabilities.
- Add tests for duplicate events, invalid signatures, amount mismatches and retries.