# AI integration
Source: https://paylinky.vercel.app/docs/ai

Give your AI coding agent accurate Paylinky knowledge.

# AI integration

Paylinky publishes machine-readable documentation so assistants (ChatGPT, Claude, Cursor, Copilot…) can integrate it correctly.

| Resource | URL |
| - | - |
| Documentation index | [`https://paylinky.vercel.app/llms.txt`](https://paylinky.vercel.app/llms.txt) |
| **Full docs in one file** | [`https://paylinky.vercel.app/llms-full.txt`](https://paylinky.vercel.app/llms-full.txt) |
| OpenAPI 3.1 spec | [`https://paylinky.vercel.app/openapi.json`](https://paylinky.vercel.app/openapi.json) |
| Any page as Markdown | `https://paylinky.vercel.app/docs/raw/{slug}` (e.g. `/docs/raw/webhooks`) |

## Prompt to give your agent

```text
You are integrating Paylinky payments. First fetch and read https://paylinky.vercel.app/llms-full.txt.
Rules:
- Base URL https://paylinky.vercel.app/api/v1, auth "Authorization: Bearer plk_(test|live)_…" from server-side env var PAYLINKY_KEY.
- Never expose the key to the browser or mobile app.
- Load GET /countries and GET /crypto/assets; never hard-code operators.
- Use a unique `reference` per order; handle 202 pending, wave_url, and 400 otp_required (retry with the returned `reference` + `otp`).
- Crypto requires customer.email, customer.firstName, customer.lastName — never invent them.
- Fulfil orders only on the signed webhook (HMAC-SHA256 of timestamp + "." + raw body with whsec_ secret) or GET /transaction/{id} === success.
- Test with plk_test_ keys and numbers ending 000000001..5 before going live.
- Live keys need KYC approval and manual activation; if you get key_not_activated or kyc_required, stop and tell the user.
```

## Facts an agent must know

- Two products: **Hosted Page API** (`POST /payment-links` → `payment_link`) and **Direct API** (`POST /collect`, `POST /crypto/collect`).
- Statuses: `pending`, `success`, `failed`, `cancelled`, `expired`, `refunded`. Webhook events: `payment.completed`, `payment.failed`.
- Sandbox is deterministic by the last digit of the phone number (`1` success, `2` pending, `3` failed, `4` OTP `000000`, `5` cancelled).
- Administrators may disable countries, operators, crypto assets or whole methods at any time — always read the catalog.
- The agent cannot bypass key activation or KYC.

## Skill file (for agents that support skills)

```markdown
---
name: paylinky
description: Integrate Paylinky Mobile Money and crypto payments (Hosted Page API and Direct API).
---
1. Read https://paylinky.vercel.app/llms-full.txt and https://paylinky.vercel.app/openapi.json.
2. Ask the user which mode they need: hosted payment link or direct API.
3. Create server-side code only; keys in environment variables.
4. Implement webhook signature verification and idempotent fulfilment.
5. Provide sandbox test steps using numbers ending 000000001–000000005.
```