.. meta::
   :description: Payneteasy Payment Gateway OpenAPI 3.1 specification: machine-readable API schema, interactive reference, SDK generation, and AI assistant integration.

.. _openapi_specification:

OpenAPI Specification
#######################################

.. contents::
   :local:

The API is described by a machine-readable specification in OpenAPI 3.1
format. The full JSON schema is published at
`https://doc.payneteasy.com/openapi.json <https://doc.payneteasy.com/openapi.json>`_.

You can use it to:

- browse the API interactively in your browser
- generate client SDKs in your language of choice
- import the API into tools such as Postman or Insomnia
- feed it to AI coding assistants to generate clients and integrations

Response Format
^^^^^^^^^^^^^^^

By default the gateway returns responses in
``application/x-www-form-urlencoded`` format — the same as it always
has. This behaviour is unchanged: when you send no special ``Accept``
header, you keep receiving form-encoded responses exactly as before.

To receive the same data as JSON instead, send the
``Accept: application/vnd.pay+json`` request header. A JSON response is
easier to deserialize, especially when you parse the response by hand.

This affects the **response** only — the **request** body is still sent
as ``application/x-www-form-urlencoded`` in both cases, with or without
the header.

Default response (``application/x-www-form-urlencoded``):

.. code-block:: text

   type=async-response
   &serial-number=00000000-0000-0000-0000-000002d9b22a
   &merchant-order-id=inv4097763
   &paynet-order-id=6768788
   &end-point-id=22903

The same response when the request includes
``Accept: application/vnd.pay+json``:

.. code-block:: json

   {
       "type": "async-response",
       "serial-number": "00000000-0000-0000-0000-000002d9b22a",
       "merchant-order-id": "inv4097763",
       "paynet-order-id": "6768788",
       "end-point-id": "22903"
   }

Interactive Documentation
^^^^^^^^^^^^^^^^^^^^^^^^^^^

The full API reference is available online as interactive OpenAPI
documentation — no tools or downloads required. Open it in your browser
to browse every endpoint, review request and response parameters and
data schemas, and send test requests right from the page:

| `OpenAPI Interactive Documentation </openapi-doc>`_

SDK generation
^^^^^^^^^^^^^^

`OpenAPI Generator <https://openapi-generator.tech/>`_ is a free,
open-source tool that reads an OpenAPI specification and generates
ready-to-use client SDKs, server stubs, and documentation for more than
50 languages. Its command-line interface, ``openapi-generator-cli``, is
the quickest way to turn the specification above into a working client.

Install it using any of the methods below (see the
`installation guide <https://openapi-generator.tech/docs/installation>`_
for all the options):

.. tabs::

   .. code-tab:: bash npm

      npm install @openapitools/openapi-generator-cli -g

   .. code-tab:: bash Homebrew

      brew install openapi-generator

   .. code-tab:: bash Docker

      docker pull openapitools/openapi-generator-cli

   .. code-tab:: bash JAR

      # requires Java 11+; replace <version> with the latest release from
      # https://github.com/OpenAPITools/openapi-generator/releases
      wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/<version>/openapi-generator-cli-<version>.jar \
          -O openapi-generator-cli.jar
      java -jar openapi-generator-cli.jar version

Then generate a client in the language of your choice:

.. tabs::

   .. code-tab:: bash Java

      openapi-generator-cli generate \
          -i https://doc.payneteasy.com/openapi.json \
          -g java \
          -o sdk-java

   .. code-tab:: bash Python

      openapi-generator-cli generate \
          -i https://doc.payneteasy.com/openapi.json \
          -g python \
          -o sdk-python

   .. code-tab:: bash TypeScript

      openapi-generator-cli generate \
          -i https://doc.payneteasy.com/openapi.json \
          -g typescript-fetch \
          -o sdk-ts

   .. code-tab:: bash PHP

      openapi-generator-cli generate \
          -i https://doc.payneteasy.com/openapi.json \
          -g php \
          -o sdk-php

   .. code-tab:: bash C#

      openapi-generator-cli generate \
          -i https://doc.payneteasy.com/openapi.json \
          -g csharp \
          -o sdk-csharp

   .. code-tab:: bash Go

      openapi-generator-cli generate \
          -i https://doc.payneteasy.com/openapi.json \
          -g go \
          -o sdk-go

   .. code-tab:: bash Ruby

      openapi-generator-cli generate \
          -i https://doc.payneteasy.com/openapi.json \
          -g ruby \
          -o sdk-ruby

   .. code-tab:: bash Kotlin

      openapi-generator-cli generate \
          -i https://doc.payneteasy.com/openapi.json \
          -g kotlin \
          -o sdk-kotlin

   .. code-tab:: bash Swift

      openapi-generator-cli generate \
          -i https://doc.payneteasy.com/openapi.json \
          -g swift5 \
          -o sdk-swift

   .. code-tab:: bash Rust

      openapi-generator-cli generate \
          -i https://doc.payneteasy.com/openapi.json \
          -g rust \
          -o sdk-rust

   .. code-tab:: bash Dart

      openapi-generator-cli generate \
          -i https://doc.payneteasy.com/openapi.json \
          -g dart \
          -o sdk-dart

   .. code-tab:: bash C++

      openapi-generator-cli generate \
          -i https://doc.payneteasy.com/openapi.json \
          -g cpp-restsdk \
          -o sdk-cpp


Using AI Agents
^^^^^^^^^^^^^^^

AI coding assistants — such as Claude Code, ChatGPT, Cursor, and
Windsurf — can read an OpenAPI specification and generate a client or
integration automatically.

Copy the prompt below into your AI assistant and adjust the target
language and requirements as needed:

.. code-block:: text

    Generate an API client from this OpenAPI specification:

    https://doc.payneteasy.com/openapi.json

    Requirements:
    - target language: Python (or TypeScript, PHP, Java, ...)
    - create a typed API client class
    - generate request and response models
    - include usage examples