# Build with your AI coding agent

Give your assistant the API contract and payment rules before it writes the integration.

## Download agent-specific instructions

Merge the templates into your application’s existing instruction files; do not overwrite existing repository rules. Download the full endpoint reference or fetch only the pages you need from llms.txt.

The AI context contains documentation, not credentials or an authenticated MCP connection. Give your assistant sandbox environment-variable names, never pasted production secrets.

- [Claude project template](/ai/CLAUDE.md): A short CLAUDE.md template linking to the integration reference.

- [Codex repository template](/ai/AGENTS.md): An AGENTS.md template to merge into your application.

- [Integration prompt](/ai/integration-prompt.txt): A stack-aware implementation brief with verification requirements.

- [OpenAPI contract](/openapi.json): Machine-readable fields, responses, errors and security schemes.

## Give your agent the docs

Use the downloadable integration context below with Claude Code, Codex or another coding assistant. For chat tools, attach the Markdown file or paste its contents. For tools that can read URLs, ask them to read /llms-full.txt first.

These files provide documentation context. They do not install an SDK, enable an MCP server, or give an assistant access to your Veyqo account.

- [Documentation index](/llms.txt): A small index of the guides for tools that consume llms.txt.

- [Full integration context](/llms-full.txt): All integration guides in one plain-text Markdown document.

## Claude Code

Merge the integration notes into your project’s CLAUDE.md, or save them in docs/veyqo.md and reference that file from CLAUDE.md. Keep your existing project instructions. Ask Claude to inspect the application before choosing where the integration belongs.

```
# 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.
```

[Claude Code project instructions](https://code.claude.com/docs/en/memory)

## Codex

Merge the same notes into AGENTS.md in your project root, or point that file to docs/veyqo.md. Codex reads repository instructions before working. Add the test command and payment code locations used by your project.

```
# 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.
```

[Codex repository instructions](https://learn.chatgpt.com/docs/agent-configuration/agents-md)

## Start with a concrete integration prompt

This prompt also works with other coding assistants when you attach the integration context. Replace the application-specific details with your own stack and order model.

```
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.
```

## Reusable integration context

Save this as docs/veyqo.md. Review the generated code and test it in sandbox before using live credentials.

```
# 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.
- Direct payments return checkout_url; checkout sessions return url. Do not invent checkout.url.
- Public API requests and responses use snake_case. Dashboard/admin internals are not the integration API.
- Browser checkout uses /checkout/v1 with a publishable key or session ID; prefer trusted server-created sessions.
- Checkout retries may suffix the original reference. Save and verify the session/payment association, not metadata alone.
- Read https://veyqo.org/api-reference.json or https://veyqo.org/openapi.json for all fields, examples and errors.
- Fetch individual endpoint guides from https://veyqo.org/llms.txt when the full context is too large.
- Never infer Nomba/Stripe/Paystack-specific API fields for Veyqo; use the Veyqo contract.
- Add tests for duplicate events, invalid signatures, amount mismatches and retries.

```