# MAXFI Payments API — v2.0.0

One API for cards, wallets, BNPL, payouts and KYC. Hosted-checkout-first with first-class direct-API support. Idempotent, signed webhooks, deterministic sandbox.

**Base URL:** `https://maxfi-api.exezine.az`  
**Auth:** `Authorization: Bearer sk_live_…` or `sk_test_…`  
**Docs:** https://dev.exezine.az/docs  
**Spec source:** https://dev.exezine.az/api/openapi.json

---

## Endpoints

### `POST /v2/payments/checkout`
**Create a checkout session**

Tags: `Checkout`
Operation ID: `createCheckoutSession`

---

### `GET /v2/payments/checkout/{id}`
**Get a checkout session**

Tags: `Checkout`
Operation ID: `getCheckoutSession`

---

### `POST /v2/payments`
**Create a direct payment**

Tags: `Payments`
Operation ID: `createPayment`

---

### `GET /v2/payments`
**List payments**

Tags: `Payments`
Operation ID: `listPayments`

---

### `GET /v2/payments/{id}`
**Get a payment**

Tags: `Payments`
Operation ID: `getPayment`

---

### `POST /v2/payments/{id}/capture`
**Capture an authorisation**

Tags: `Payments`
Operation ID: `capturePayment`

---

### `POST /v2/payments/{id}/refund`
**Refund a payment (full or partial)**

Tags: `Payments`
Operation ID: `refundPayment`

---

### `POST /v2/payments/{id}/cancel`
**Cancel an authorisation or pending payment**

Tags: `Payments`
Operation ID: `cancelPayment`

---

### `POST /v2/payouts`
**Create a payout**

Tags: `Payouts`
Operation ID: `createPayout`

---

### `GET /v2/health`
**Service health**

Tags: `Health`
Operation ID: `health`

---

## Schemas

### `Error`
```json
{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "example": "VALIDATION_ERROR"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
```

### `CreateCheckoutRequest`
```json
{
  "type": "object",
  "required": [
    "amount",
    "currency"
  ],
  "properties": {
    "amount": {
      "type": "integer",
      "description": "Minor units (4900 = $49.00)"
    },
    "currency": {
      "type": "string",
      "description": "ISO 4217",
      "example": "USD"
    },
    "description": {
      "type": "string",
      "maxLength": 500
    },
    "order_id": {
      "type": "string",
      "maxLength": 128
    },
    "language": {
      "type": "string",
      "enum": [
        "en",
        "ru",
        "az"
      ],
      "default": "en"
    },
    "customer": {
      "$ref": "#/components/schemas/Customer"
    },
    "success_url": {
      "type": "string",
      "format": "uri",
      "description": "Canonical location (top-level). Legacy: settings.success_url also accepted."
    },
    "cancel_url": {
      "type": "string",
      "format": "uri",
      "description": "Canonical location (top-level). Legacy: settings.cancel_url also accepted."
    },
    "settings": {
      "type": "object",
      "description": "Presentation overrides. Legacy fallback for success_url/cancel_url.",
      "properties": {
        "payment_methods": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "button_text": {
          "type": "string"
        },
        "auto_return": {
          "type": "integer"
        },
        "success_url": {
          "type": "string",
          "format": "uri",
          "description": "Legacy — prefer top-level success_url."
        },
        "cancel_url": {
          "type": "string",
          "format": "uri",
          "description": "Legacy — prefer top-level cancel_url."
        }
      }
    },
    "webhook_url": {
      "type": "string",
      "format": "uri",
      "description": "Per-session override of the merchant-wide webhook URL."
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "test_mode": {
      "type": "boolean"
    }
  }
}
```

### `CheckoutSession`
```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "example": "cs_…"
    },
    "checkout_url": {
      "type": "string"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "amount": {
      "type": "integer"
    },
    "currency": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "open",
        "processing",
        "requires_action",
        "succeeded",
        "failed",
        "expired"
      ],
      "description": "Freshly created sessions are `open` and transition through processing/requires_action to terminal states."
    },
    "livemode": {
      "type": "boolean"
    }
  }
}
```

### `Customer`
```json
{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "phone": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "country": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2
    }
  }
}
```

### `CreatePaymentRequest`
```json
{
  "type": "object",
  "required": [
    "amount",
    "currency"
  ],
  "properties": {
    "amount": {
      "type": "integer"
    },
    "currency": {
      "type": "string"
    },
    "payment_method": {
      "type": "string",
      "enum": [
        "card",
        "token",
        "wallet"
      ],
      "default": "card"
    },
    "card": {
      "type": "object",
      "properties": {
        "number": {
          "type": "string"
        },
        "exp_month": {
          "type": "string"
        },
        "exp_year": {
          "type": "string",
          "description": "2-digit YY"
        },
        "cvc": {
          "type": "string"
        },
        "holder": {
          "type": "string"
        }
      }
    },
    "capture_method": {
      "type": "string",
      "enum": [
        "automatic",
        "manual"
      ],
      "default": "automatic"
    },
    "description": {
      "type": "string"
    },
    "order_id": {
      "type": "string"
    },
    "customer": {
      "$ref": "#/components/schemas/Customer"
    },
    "webhook_url": {
      "type": "string",
      "format": "uri"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    }
  }
}
```

### `Payment`
```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "payment_id": {
      "type": "string"
    },
    "order_id": {
      "type": "string"
    },
    "checkout_session_id": {
      "type": "string"
    },
    "amount": {
      "type": "integer"
    },
    "currency": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "payment_method": {
      "type": "string"
    },
    "source": {
      "type": "string"
    },
    "card_last4": {
      "type": "string"
    },
    "card_brand": {
      "type": "string"
    },
    "customer_email": {
      "type": "string"
    },
    "error_code": {
      "type": "string"
    },
    "error_message": {
      "type": "string"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
```

### `RefundRequest`
```json
{
  "type": "object",
  "properties": {
    "amount": {
      "type": "integer",
      "description": "Omit for full refund of the remaining balance."
    },
    "reason": {
      "type": "string",
      "maxLength": 500
    },
    "idempotency_key": {
      "type": "string",
      "maxLength": 128
    }
  }
}
```

### `RefundResponse`
```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "payment_id": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "refunded",
        "partially_refunded"
      ]
    },
    "amount_refunded": {
      "type": "integer"
    },
    "total_refunded": {
      "type": "integer"
    },
    "remaining": {
      "type": "integer"
    },
    "reason": {
      "type": "string"
    }
  }
}
```

### `CreatePayoutRequest`
```json
{
  "type": "object",
  "required": [
    "amount",
    "currency",
    "destination"
  ],
  "properties": {
    "amount": {
      "type": "integer"
    },
    "currency": {
      "type": "string"
    },
    "destination": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "card",
            "iban",
            "sbp"
          ]
        },
        "card": {
          "type": "string"
        },
        "iban": {
          "type": "string"
        },
        "phone": {
          "type": "string"
        },
        "bic": {
          "type": "string"
        }
      }
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    }
  }
}
```

## Webhooks

All outbound events use the same envelope:
```json
{
  "id": "evt_…",
  "type": "payment.succeeded",
  "livemode": true,
  "created_at": "2026-04-17T06:04:14Z",
  "data": {
    "payment_id": "cs_…",
    "amount": 4900,
    "currency": "USD",
    "status": "succeeded"
  }
}
```

Headers: `X-MAXFI-Signature: sha256=<hex>`, `X-MAXFI-Event`, `X-MAXFI-Event-Id`, `X-MAXFI-Delivery`, `X-MAXFI-Attempt`.

Retry: 8 attempts across 24h with exponential backoff (30s → 24h).