# Kratos Pay Live API — Payin and Payout

This guide describes the Live transaction creation endpoints. Requests may move real funds: verify the environment, amount, phone number and operator before submitting.

## Authentication

Send your Live public key in the `X-MoK-Public-Key` header. These endpoints do not require a secret key or an `applicationId`.

```http
X-MoK-Public-Key: <YOUR_LIVE_PUBLIC_KEY>
Content-Type: application/json
Accept: application/json
```

Base URL: `https://api.kratospay.com`

## Payin — collection

**POST** `/api/v1/live/payin`

```json
{
  "amount": 5000,
  "currency": "XAF",
  "phoneNumber": "237690000000",
  "operator": "orange_money_cm",
  "reference": "INV-123456",
  "description": "Internet bill payment"
}
```

Successful response:

```json
{
  "status": "SUCCESS",
  "reference": "INV-123456",
  "amount": 5000,
  "currency": "XAF",
  "timestamp": "2026-09-10T15:30:00Z",
  "gatewayMessage": "Transaction successful"
}
```

## Payout — disbursement

**POST** `/api/v1/live/payout`

```json
{
  "amount": 5000,
  "currency": "XAF",
  "phoneNumber": "237690000000",
  "operator": "mtn_momo_cm",
  "reference": "OUT-123456",
  "description": "Supplier payment"
}
```

Successful response (example):

```json
{
  "status": "SUCCESS",
  "reference": "OUT-123456",
  "amount": 5000,
  "currency": "XAF",
  "timestamp": "2026-09-10T15:30:00Z",
  "gatewayMessage": "Transaction successful"
}
```

## Example error response

Example validation response using the API error format. The `details` values and HTTP status depend on the error encountered.

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The provided data is invalid.",
    "details": {
      "phoneNumber": [
        "The phone number field is required."
      ]
    }
  },
  "meta": {
    "request_id": "example-request-id",
    "timestamp": "2026-09-10T15:30:00Z"
  }
}
```

## Best practices

- Send all six payload fields using their exact names and use a unique reference per transaction.
- Check `status` in the response body; do not infer transaction success from the HTTP status alone.
- On errors, use `error.code`, `error.message` and `error.details`. Keep `meta.request_id` for troubleshooting.
- Do not automatically retry a transaction without an idempotency strategy in your integration.
- The response samples illustrate the contract and do not guarantee a real transaction.