API Reference

The Plexy API is a RESTful API that uses JSON for request and response bodies. It powers the merchant-facing endpoints used to create payments, manage checkout sessions, and look up available payment methods.

Base URL

Authentication

All API requests must include your API key in the x-api-key header:

curl https://api.plexypay.com/v2/paymentMethods \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"merchantAccount": "YOUR_MERCHANT_ACCOUNT"}'

See Authentication for details on obtaining and rotating keys.

Request format

• Use Content-Type: application/json for all requests
• All timestamps are in ISO 8601 format
• Amounts are specified in the smallest currency unit (e.g., 5000 = 50.00 KZT). See Currency Codes.

Response format

Successful responses return a 2xx status code with a JSON body. Example response from POST /payments:

{
  "pspReference": "BNV58BSJF9WQ5K65",
  "resultCode": "Authorised",
  "amount": { "currency": "KZT", "value": 10000 },
  "merchantReference": "order-1729012345",
  "paymentMethod": { "type": "scheme", "brand": "visa" }
}

The resultCode field tells you the outcome of the payment. See HTTP Status Codes and Refusal Reasons for the full list of values.

Error format

Error responses return a 4xx or 5xx status code with an error body:

{
  "error": {
    "code": "invalid_request",
    "message": "Amount must be greater than 0",
    "param": "amount"
  }
}

See Error Codes for the full catalog of error types and codes.

Webhooks

Plexy sends webhook events for important state changes. See the webhooks guide for setup instructions.

API endpoints

The merchant API exposes five operations grouped by resource:

Payment Methods

Payments

Sessions