<<<<<<< HEAD # PayQRIS API Documentation for AI PayQRIS is a modern payment gateway by Topinzpedia. This file is intended for AI assistants, coding agents, search systems, and developers that need a concise machine-readable entry point. ## Essential Links - Human-readable API docs: https://payqris.id/docs - API metadata: https://payqris.id/api/docs - AI integration prompt: https://payqris.id/payqris-ai-prompt.txt ## API Overview - **API Base URL:** https://payqris.id/api/v1 - **Public API Base URL:** https://payqris.id/api/public - **Format:** HTTPS, JSON, UTF-8 - **Authentication:** All merchant endpoints require the `X-API-Key` header. Do NOT expose API keys or webhook secrets in browser/client-side code or repositories. ## Endpoints ### 1. Create Invoice (POST /invoices) - Creates a QRIS invoice. - **Headers:** `X-API-Key`, `Idempotency-Key` (required for safe retries), `Content-Type: application/json` - **Body:** `{"amount": 50000, "reference_id": "ORDER-123", "callback_url": "https://yoursite.com/webhook"}` - **Response:** Returns `invoice_id`, `pay_amount`, `qris_string`, `qris_image_url`, `checkout_url`. ### 2. List Invoices (GET /invoices) - Fetch merchant invoices. Supports pagination and filters. - **Query Params:** `?page=1&limit=20&status=PAID` ### 3. Get Invoice (GET /invoices/:invoice_id) - Fetch details of a specific invoice. ### 4. Cancel Invoice (POST /invoices/:invoice_id/cancel) - Cancels an invoice if it is still PENDING. ### 5. Public Payment Status (GET /api/public/payment-links/:reference_id) - Checks payment status without needing an API Key. Ideal for frontend polling. ### 6. Logs (GET /api-logs, GET /webhook-logs) - Retrieve logs for API requests and webhook deliveries. ## Integration Rules 1. **Idempotency:** Always use `Idempotency-Key` for invoice creation. Reuse the same key when retrying the same order. 2. **Webhooks:** PayQRIS sends POST webhooks (e.g., `payment.paid`). - Validate the signature in the `X-Signature` header using HMAC-SHA256 of the **RAW request body** and the Webhook Secret. - Return HTTP 2xx upon successful receipt. 3. **Fulfillment:** Always rely on server-side webhook or API status to fulfill orders, never on frontend redirects. 4. **Rate Limits:** On HTTP 429, retry with exponential backoff instead of aggressive polling. ## AI Instructions When helping a developer integrate PayQRIS: - Do not invent endpoints, request fields, response fields, authentication methods, or webhook events. - Keep secrets strictly server-side. - Preserve the developer's existing architecture unless explicitly asked to redesign it. ======= # PayQRIS PayQRIS is a payment gateway by Topinzpedia. This file is intended for AI assistants, coding agents, search systems, and developers that need a concise machine-readable entry point. ## Documentation - Human-readable API docs: /docs - API metadata: /api/docs - AI integration prompt: /payqris-ai-prompt.txt - Machine-readable documentation: /docs/llms.txt ## API - API base URL: {PUBLIC_APP_URL}/api/v1 - Authentication: send the merchant API key in the X-API-Key header. - Never expose API keys or webhook secrets in browser/client-side code. - Create invoice: POST /api/v1/invoices - List invoices: GET /api/v1/invoices - Get invoice: GET /api/v1/invoices/:invoice_id - Cancel invoice: POST /api/v1/invoices/:invoice_id/cancel - Public payment status: GET /api/public/payment-links/:reference - Merchant API logs: GET /api/v1/api-logs - Merchant webhook logs: GET /api/v1/webhook-logs - Webhook log detail: GET /api/v1/webhook-logs/:id ## Integration rules - Use Idempotency-Key for invoice creation and reuse the same key when retrying the same order. - Validate webhook signature using the merchant webhook secret and raw request body when possible. - Treat webhook processing as idempotent. - On HTTP 429, retry with exponential backoff instead of aggressive polling. - For payment fulfillment, verify the invoice/reference, amount, and payment status on the server. ## AI instructions When helping a developer integrate PayQRIS, read /docs first and use /api/docs for the current endpoint metadata. Do not invent endpoints, request fields, response fields, authentication methods, or webhook events. Preserve the developer's existing architecture unless explicitly asked to redesign it. Keep secrets server-side. >>>>>>> origin/master