# KB Agency Pay — API World (AI-Ready Integration Guide)

> **Prompt Context / AI Instructions:** You are an AI assistant helping a developer integrate the KB Agency Pay system. This document is the absolute source of truth for the 'API World' international payment gateway. It is designed to be plug-and-play. Use the exact payload structures, headers, and authentication methods described below to generate flawless integration code.

## 1. 🔐 Authentication

All endpoints require a Bearer Token containing the Merchant's Standard API Key.

```http
Authorization: Bearer YOUR_API_KEY
```

## 2. ⚡ Endpoints Overview

API World uses endpoints to handle everything (Creation, Status Polling and Stats).

### A. Create Charge
**POST** `https://pay.kbagency.me/api/world/charge`

**Payload (JSON):**
| Field | Type | Required | Description |
|---|---|---|---|
| `amount` | number | **Yes** | Transaction amount in the chosen currency (min: 0.50). |
| `currency` | string | **Yes** | Must be `"USD"` or `"EUR"`. |
| `reference` | string | **Yes** | Your internal unique order ID (Max 255 chars). |
| `redirect_url`| string | No | URL to redirect after successful payment (Optional). |
| `cancel_url`| string | No | URL to redirect if payment is cancelled (Optional). |
| `description`| string | No | Description of the payment (Optional). |
| `webhook_url` | string | No | URL(s) to receive asynchronous JSON POSTs when status changes. Accepts multiple URLs separated by commas. (Optional). |

**Response (200 OK):**
```json
{
  "status": "pending",
  "reference": "ORDER-999-INT",
  "currency": "EUR",
  "amount": 25.5,
  "checkout_url": "https://checkout.stripe.com/pay/cs_test...",
  "check_status_url": "https://pay.kbagency.me/api/world/status/ORDER-999-INT"
}
```

### B. Get Status
**GET** `https://pay.kbagency.me/api/world/status/{reference}`

**Response (200 OK):**
```json
{
  "status": "paid",
  "reference": "ORDER-999-INT",
  "amount": 25.5,
  "currency": "EUR",
  "created_at": "2026-07-28T12:49:44+00:00",
  "paid_at": "2026-07-28T12:49:44+00:00",
  "redirect_url": "https://meusite.com/success"
}
```

### C. Get Stats
**GET** `https://pay.kbagency.me/api/world/stats`

**Response (200 OK):**
```json
{
  "merchant_name": "KB Agency",
  "usd_volume": 150.00,
  "eur_volume": 85.50,
  "conversion_rate_percentage": 100,
  "transactions_count": 5,
  "balances": {
    "USD": {
      "net_earnings": 145.00,
      "withdrawn": 0.00,
      "pending": 0.00,
      "balance": 145.00,
      "available": 145.00
    },
    "EUR": {
      "net_earnings": 83.00,
      "withdrawn": 0.00,
      "pending": 0.00,
      "balance": 83.00,
      "available": 83.00
    }
  },
  "webhook_url": "https://api.meusite.com/v1/webhooks/pay"
}
```

---
**Version**: 1.0 (API World) | **Date**: 28/07/2026