MAXFI API

v2 · 2026-04-17 · dev.exezine.az

📄 Hit ⌘P / Ctrl+P and choose Save as PDF in the destination dropdown. A native browser PDF gives you searchable text and tiny file size — no fonts re-rasterised.

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`

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

`CreateCheckoutRequest`

{
  "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`

{
  "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`

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

`CreatePaymentRequest`

{
  "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`

{
  "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`

{
  "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`

{
  "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`

{
  "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:

{
  "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).