> ## Documentation Index
> Fetch the complete documentation index at: https://dev.fbox.uz/llms.txt
> Use this file to discover all available pages before exploring further.

# Оплата Payme

> Инициация платежей через Payme

## Обзор

**Payme Go Payment API** используется для инициации платежа через Payme.

Эндпоинт создает платежную транзакцию и возвращает `payment_id`
that must be used later for fiscalization.

***

## Поля запроса

| Поле      | Тип     | Обяз. | Описание                            |
| --------- | ------- | ----- | ----------------------------------- |
| `amount`  | integer | ✅     | Payment amount in sums              |
| `qr_code` | string  | ✅     | Unique Payme transaction identifier |

***

## Поля ответа

### ✅ Успешный ответ `200`

| Поле                       | Тип     | Описание                                        |
| -------------------------- | ------- | ----------------------------------------------- |
| `data`                     | object  | Данные ответа                                   |
| `data.amount`              | integer | Payment amount in sums                          |
| `data.transaction_id`      | string  | Transaction UUID                                |
| `data.payment_id`          | string  | Unique payment identifier                       |
| `data.inn`                 | string  | Client tax identifier                           |
| `data.qr_code`             | string  | QR code of the transaction                      |
| `data.kkm_id`              | string  | KKM (cash register) ID                          |
| `data.device_id`           | string  | Device ID                                       |
| `data.status`              | string  | Payment status (`successfully`, `failed`, etc.) |
| `data.message`             | string  | Optional message from provider                  |
| `data.client_phone_number` | string  | Client phone number                             |
| `error`                    | null    | Error object (always `null` on success)         |
| `is_success`               | boolean | Always `true`                                   |

### 🚫 Ответ с ошибкой `400`

> **Примечание:** Даже при ошибке валидации сервер возвращает HTTP `200`.

| Поле            | Тип         | Описание                 |
| --------------- | ----------- | ------------------------ |
| `data`          | null        | No data returned         |
| `error`         | object      | Error details            |
| `error.code`    | integer     | Internal error code      |
| `error.message` | string      | Понятное описание ошибки |
| `error.data`    | any \| null | Additional error details |
| `is_success`    | boolean     | Always `false`           |


## OpenAPI

````yaml POST /payment/payme
openapi: 3.1.0
info:
  title: Payme Go API
  description: Payment endpoint for Payme payments
  license:
    name: MIT
    identifier: ''
  version: 1.0.0
servers:
  - url: https://fbox.ngrok.io
security: []
paths:
  /payment/payme:
    post:
      tags:
        - Payme go Payment
      summary: Payme Go payment
      operationId: paymeGoPayment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
            example:
              amount: 1000
              qr_code: '50502044301381396427'
      responses:
        '200':
          description: Fiscalization successful
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/PaymentResponse'
                  - $ref: '#/components/schemas/ErrorResponse'
              example:
                data:
                  amount: 1000
                  transaction_id: a12fc00f-5af5-65b8-adf8-74bff44680ee
                  payment_id: 696e0246c9a128176d5934d8
                  inn: '123456789'
                  qr_code: '50502244301381336427'
                  kkm_id: '00000011'
                  device_id: '00000011'
                  status: successfully
                  message: successfully payment
                  client_phone_number: '998712565009'
                error: null
                is_success: true
        '400':
          description: 'Invalid request (status code: 200)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                data: null
                error:
                  code: 104
                  message: BILLING_ERROR
                  data: null
                is_success: false
        '500':
          description: Internal server error
components:
  schemas:
    PaymentRequest:
      type: object
      required:
        - amount
        - qr_code
      properties:
        amount:
          type: integer
          description: Payment amount in sums
          example: 1000
        qr_code:
          type: string
          description: Unique transaction identifier
    PaymentResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            amount:
              type: integer
            transaction_id:
              type: string
              nullable: false
              example: 3dbec60e-df7d-4c14-929a-8d79b499f7cb
            payment_id:
              type: string
              nullable: false
            inn:
              type: string
              nullable: false
            qr_code:
              type: string
              nullable: false
            kkm_id:
              type: string
              nullable: false
            device_id:
              type: string
              nullable: false
            status:
              type: string
              nullable: false
              example: successfully
            message:
              type: string
              nullable: false
            client_phone_number:
              type: string
              nullable: false
              example: '998712565009'
        error:
          type: string
          nullable: true
        is_success:
          type: boolean
          example: true
    ErrorResponse:
      type: object
      properties:
        data:
          type: string
          nullable: true
          default: null
        error:
          type: object
          properties:
            code:
              type: integer
              example: 104
            message:
              type: string
              example: BILLING_ERROR
            data:
              type: string
              nullable: true
              default: null
        is_success:
          type: boolean
          example: false

````