Conventions

Response format

All responses share a single wrapper structure:

JSON API v3

Success response


{
  "success": true,
  "data": { ... }
}

Error response


{
  "success": false,
  "error": {
    "code": "INVOICE_NOT_FOUND",
    "message": "Invoice with the specified ID was not found",
    "details": null
  }
}

The data and error fields are mutually exclusive — the absent field is not serialized. In some cases details carries structured information: e.g. details.invoice_id for INVOICE_ALREADY_EXISTS or details.contract_id for CONTRACT_ALREADY_EXISTS.

HTTP response codes

HTTP code	Meaning
`200`	Processed successfully
`201`	Resource created (Invoice / Contract)
`202`	Request accepted for processing (Refund)
`400`	Invalid request (validation errors)
`401`	Authentication error
`403`	No access to the specified project (IP not in whitelist, project inactive)
`404`	Resource not found
`409`	Conflict (e.g. invoice already exists)
`422`	Business logic error
`500`	Internal platform error
`503`	Service temporarily unavailable

Data types

Type	JSON format	Example
`uuid`	string (UUID v4)	`"1624505c-0031-00cf-7d54-4cf1ce08cb30"`
`datetime`	string (ISO 8601, UTC)	`"2025-03-29T20:00:08Z"`
`money`	object — see below	—
`currency`	string (ISO 4217)	`"RUB"`
`msisdn`	string (E.164 without `+`)	`"79600000000"`
`ip`	string (IPv4/IPv6)	`"10.20.30.40"`
`country`	string (ISO 3166-1 alpha-2)	`"RU"`

Money amounts

All monetary values are represented by a money object:


{
  "amount": "25.00",
  "currency": "RUB",
  "vat_included": true
}

amount — fixed-point string (two digits after the point). Passed as a string to avoid float rounding errors.
currency — ISO 4217 currency code.
vat_included — whether VAT is included in the amount.

Additional invoice parameters

additional_parameters is a free-form map of name/value string pairs — the JSON equivalent of the <AdditionalParameters> block of the XML API. It carries processing flags such as NeedSendNotification as well as the merchant’s own labels.


{
  "additional_parameters": {
    "NeedSendNotification": "False"
  }
}

Invoice creation accepts the block inside order; authorization, cancellation and refund accept it at the top level of the body. The values passed are appended to those already stored on the invoice, and values matching by name are overwritten.

Names are case-insensitive and must be unique: Flag and flag in one object is a 400 BAD_REQUEST request error, not two parameters.