Generating checks| Directory of API methods

Directory of API methods - Receipts (for the Russian Federation)

You can use the API to get information about receipts for which you have sent data via Paybox.

To access the receipts resource, the following methods will be available:

POST v1/receipts - Creating a receipt
GET v1/receipts - Getting a list of receipts
GET v1/receipts/{receipt_id} - Getting information on the receipt

Receipt object

The receipt object (pg_receipt) contains up-to-date information about the receipt created for payment or refund.

receipt_id string, required;ID of the receipt generated in PayBox. operation_type string, required;Type of operation in the online cash register. receipt_format string, required;Format of the receipt (fiscal document). merchant_id string, required;Store ID. payment_id string, required;Payment ID with which the receipt was associated in the store’s personal account refund_id string, required;ID of the refund or cancellation that the receipt was associated with in the store’s personal account status string, required;Status of the receipt registration in the online cash register. Possible values: - pending - pending - the receipt is pending registration - registered - the receipt is registered - error - the receipt could not be registered. fiscal_document_numberstring, optional;Number of the fiscal document. fiscal_storage_numberstring, optional;Number of the fiscal drive in the online cash register. fiscal_attributestring, optional;Fiscal attribute of the receipt, which is generated by the online cash register after successful registration of the receipt. registered_at string, optional;Date and time of receipt registration in the online cash register fiscal storage. Output in ISO 8601 YYYY-MM-DD HH:MM:SS format. created_at string, optional;Date the receipt was created in Paybox. Output in ISO 8601 YYYY-MM-DD HH:MM:SS format. fiscal_provider_id string, optional;Unique ID of the receipt generated by the online cash register. link string, optional;Link to the receipt in the FDO. The availability of this value depends on the specific online cash register receipt_methodstring, required;The method by which the receipt was created. Possible values: - together - Receipt with payment - separately - Receipt is separate from the payment error string, required;Description of the receipt registration error. Depends on the specific online cash register company object, required;Information about the store.

Nested parameters of the company object

Nested parameters of the positions array

name string, required;Name of the goods, work, service (no more than 128 characters). (Tag in 54 FL— 1030). price float, required</p;Price per unit of goods, works, services, including discounts and extra charges (tag in 54 FL— 1079) -- the whole part of no more than 8 characters - fractional part of no more than 2 characters. quantity float, required;Quantity/weight of the goods (tag in 54 FL— 1023). - the whole part of no more than 5 characters - fractional part of no more than 3 characters. Maximum value depends on the specific online cash register. measure string, required;Measure of the quantity of the subject of calculation (tag in 54 FL— 2108). sum float, calculated required;Cost of goods/services in rubles (tag in 54 FL— 1043). - the whole part of no more than 8 characters - - fractional part of no more than 2 characters. Value is calculated automatically in Paybox payment_method string, required;Indication of the method of calculation (tag in 54 FL— 1214). Displays the payment method and the fact of the transfer of the goods to the buyer. Example: the buyer pays for the goods in full and receives it immediately. In this case, you need to pass the value full_payment (full settlement). payment_object string, required;Indication of the subject of calculation (tag in 54 FL— 1212) is what payment is accepted for, for example, goods, services. vat_code string, required;VAT tax rate (tag in 54 FL— 1199). additional_payment_object_props string, optional;Additional details of the subject of calculation (tag in 54 FL— 1191). Maximum line length is 64 characters. country_code string, optional;Digital code of the country of origin of the goods according to the international classifier of the countries of the world (OK (MK (ISO 3166) 004-97) 025-2001) (tag in 54 FL— 1230). declaration_number string, optional;Number of the customs declaration (from 1 to 32 characters). (tag in 54 FL— 1231). excise float, optional;Amount of excise duty in rubles (tag in 54 FL— 1229). Whole part of no more than 8 characters fractional part of no more than 2 characters the value cannot be negative; mark_quantity object, optional;Fractional quantity of the marked product (tag in 54 FL— 1291).Can be displayed only when using FDF 1.2.

Nested parameters of the positions.mark_quantity object

Nested array parameters positions.payment_object_industry_details

Nested parameters of the positions.mark_code_type object

Nested parameters of the positions.supplier object

Nested array parameters settlements

Nested parameters of the additional_user_props object

Nested array parameters receipt_industry_details

Nested parameters of the receipt_operating_details object


{
    "data": {
        "merchant_id": "542088",
        "receipt_id": "bb938d6c-6c1c-44a0-aa54-32c3e14fddb7",
        "operation_type": "sell",
        "receipt_format": "ru_1_05",
        "status": "registered",
        "fiscal_document_number": 10605,
        "fiscal_storage_number": "9999078900006286",
        "fiscal_attribute": 923085333,
        "registered_at": "29.03.2023 17:37:00",
        "created_at": "29.03.2023 20:39:16",
        "fiscal_provider_id": "5e402526-0c20-41c3-b30a-b52e7f903922",
        "positions": [
            {
                "name": "Товар №1",
                "quantity": 2,
                "price": 50,
                "vat_code": "vat_20",
                "payment_method": "full_payment",
                "payment_object": "goods",
                "sum": 100
            },
            {
                "name": "Товар №2",
                "quantity": 1,
                "price": 100,
                "vat_code": "vat_20",
                "payment_method": "full_payment",
                "payment_object": "goods",
                "sum": 100
            }
        ],
        "total": 200,
        "settlements": [
            {
                "type": "cashless",
                "sum": 200
            }
        ],
        "receipt_method": "separately",
        "error": null,
        "link": "https: //consumer.1-ofd-test.ru/v1?fn=9999078900006286&fp=923085333&i=10605&t=20230329T173700&s=7&n=2",
        "payment_id": "764239789"
    }
}

Creating a receipt

The request allows you to send the data for the formation of the receipt to your online cash register.

Using this request, you can generate a prepayment offset receipt if you use the Receipt method with payment. Also, you need to use this request to create a receipt and a receipt return receipt, if you have enabled the Receipt method separately from the payment.

Вложенные параметры объекта customer

phone string, optional Example: 79000000000 ;Buyer's phone number for sending the receipt (tag in 54 FL— 1008). Указывается в формате ITU-T E.164. Specified in the ITU-T E.164 format. Required parameter, if email is not passed. email string, optional ;Buyer's email address for sending the receipt (tag in 54 FL— 1008). Required parameter, if phone is not passed. full_name string, optional Example: Petrov Ivan Vasilievich ;For legal entities — the name of the organization, for IE and individuals — full name. If an individual does not have an TIN, the series and number of the buyer's passport are transmitted in the same parameter. No more than 256 characters. (tag in 54 FL— 1227). inn string, optional; Buyer's TIN (10 or 12 digits). If an individual does not have a TIN, it is necessary to pass passport data in the full_name parameter (tag in 54 FL— 1228). birthdate string, optional Example: 1979-05-18;The date of birth of the buyer in the format YYYY-MM-DD (tag in 54 FL— 1243). It should be transmitted only if FDF 1.2 is used citizenship string, optional Example: 643; Numeric code of the country of which the buyer is a citizen. The country code is specified in accordance with the international classifier of countries of the world ISO3166-1alpha-2, exactly 3 digits. (tag in 54 FL— 1244). It should be transmitted only if FDF 1.2 is used document_code string, optional ;Numeric code of the type of identity document. Exactly 2 digits. (tag in 54 FL— 1245). It should be transmitted only if FDF 1.2 is used document_data string, optional ;Details of the identity document. Maximum of 64 characters. (tag in 54 FL— 1246). It should be transmitted only if FDF 1.2 is used address string, optional ;It should be transmitted only if FDF 1.2 is used It should be transmitted only if FDF 1.2 is used company object, optional ;Information about the store.

Nested parameters of the company object

Nested parameters of the positions array

name string, required; Name of the goods, work, service (no more than 128 characters). (Tag in 54 FL— 1030). price float, required Example: 100.00; Price per unit of goods, works, services, including discounts and extra charges (tag in 54 FL— 1079) - the whole part of no more than 8 characters- fractional part of no more than 2 characters. quantity float, required Example: 1.00; Quantity/weight of the goods (tag in 54 FL— 1023).. - the whole part of no more than 5 characters - fractional part of no more than 3 characters.Maximum value depends on the specific online cash register If you use FDF 1.2, the subject of calculation is a product subject to mandatory labeling, and the mark_quantity parameter is passed, then the quantity parameter must take a value equal to "1". measure string, required;Measure of the quantity of the subject of calculation (tag in 54 FL— 2108). This parameter is mandatory when using FDF 1.2 payment_method string, required;Признак способа расчета (тег в54 ФЗ— 1214). Определяет способ оплаты и факт передачи товара покупателю. Пример: покупатель полностью оплачивает товар и сразу получает его. В этом случае нужно передать значение full_payment (полный расчет). payment_object string, required; Indication of the method of calculation (tag in 54 FL— 1214). Determines the payment method and the fact of the transfer of the goods to the buyer. Example: the buyer pays for the goods in full and receives it immediately. In this case, you need to pass the value full_payment (full settlement). vat_code string, required; VAT tax rate (tag in 54 FL— 1199). additional_payment_object_props string, optional;Additional details of the subject of calculation (tag in 54 FL— 1191). Maximum line length is 64 characters. country_code string, optional Example: 643 ;Digital code of the country of origin of the goods according to the international classifier of the countries of the world (OK (MK (ISO 3166) 004-97) 025-2001) (tag in 54 FL— 1230). Exactly 3 digits. declaration_number string, optional Example: 10702030/ 261016/0088410 ;Number of the customs declaration (from 1 to 32 characters). (tag in 54 FL— 1231). excise float, optional Example: 25.00; Amount of excise duty in rubles (tag in 54 FL— 1229). Whole part of no more than 8 characters fractional part of no more than 2 characters mark_quantity object, optional ; Fractional quantity of the marked product (tag in 54 FL— 1291). It should be transmitted only if FDF 1.2 is usedMust be transmitted when the following conditions occur simultaneously: 1. one of the following values of the positions.payment_method parameter is passed: 1. non_marked_excise_goods 2. marked_excise_goods 3. non_marked_goods 4. marked_goods 2. 2. the measure field has the value piece. If the parameter is passed, the value of the positions.quantity** parameter must be equal to 1 Example: we sell yogurt by the piece. It comes in a package of 6 pieces with one marking code. When selling one bottle of yogurt, you need to transfer 1 to numerator, and 6 to denominator.

Nested parameters of the positions.mark_quantity object

Nested array parameters positions.payment_object_industry_details

Nested parameters of the positions.mark_code_type object

Nested parameters of the positions.supplier object

Nested array parameters settlements

Nested parameters of the additional_user_props object

Nested array parameters receipt_industry_details

Nested parameters of the receipt_operating_details object

Request example


curl --location --request POST 'https://api.paybox.money/v5/receipts' \
--header 'Accept: application/json' \
--header 'X-JWS-Signature: {{Ваш JWS-токен}}' \
--header 'Content-Type: application/json' \
--data-raw \
'{
  "receipt_format": "ru_1_05",
  "merchant_id": 542088,
  "payment_id": 764239789,
  "operation_type": "sell",
  "customer": {
    "email": "customer@mail.ru"
  },
  "positions": [
    {
      "price": 50.00,
      "name": "Товар №1",
      "quantity": 2.00,
      "vat_code": "vat_20",
      "payment_method": "full_payment",
      "payment_object": "goods"
    },
    {
      "price": 100.00,
      "name": "Товра №2",
      "quantity": 1.00,
      "vat_code": "vat_20",
      "payment_method": "full_payment",
      "payment_object": "goods"
    }
  ],
  "settlements": [
    {
      "type": "cashless",
      "sum": 200.00
    }
  ]
}'

Example of the response body


{
    "data": {
        "merchant_id": "542088",
        "receipt_id": "adec9d48-be2a-4bf4-8ca1-3432fd8920c5",
        "operation_type": "sell",
        "receipt_format": "ru_1_05",
        "status": "pending",
        "fiscal_document_number": "",
        "fiscal_storage_number": null,
        "fiscal_attribute": "",
        "registered_at": null,
        "created_at": "10.04.202315:34:12",
        "fiscal_provider_id": null,
        "positions": [
            {
                "name": "Товар №1",
                "quantity": 2,
                "price": 50,
                "measure": "piece",
                "vat_code": "vat_20",
                "payment_method": "full_payment",
                "payment_object": "goods",
                "sum": 10
            },
            {
                "name": "Товар №2",
                "quantity": 1,
                "price": 100,
                "measure": "piece",
                "vat_code": "vat_20",
                "payment_method": "full_payment",
                "payment_object": "goods",
                "sum": 2
            }
        ],
        "total": 200,
        "settlements": [
            {
                "type": "cashless",
                "sum": 200
            }
        ],
        "company": {
            "inn": "5544332219",
            "email": "customer@mail.ru",
            "tax_system": "osn",
            "payment_address": "shop.ru"
        },
        "receipt_method": "separately",
        "error": null,
        "link": null,
        "payment_id": "764239789"
    }
}

Getting a list of receipts

This request allows you to get a list of store receipts filtered by certain criteria. The criteria can be different, for example, the list can be filtered by the number of payment or refund, by the name of the product or the amount of the receipt.

Request parameters

nested array parameters created_at

gtestring, optional; Sets the time from the selected date inclusive. Specified in the ISO 8601 yyyy-mm-dd format Example: created_at[gte]=2022-07-18 ltestring, optional; Sets the time up to and including the selected date. Specified in the ISO 8601 yyyy-mm-dd format Example: created_at[lte]=2022-07-25 operation_typestring, optional; Filter by the type of operation in the online cash register.Filters the list of receipts by the type of cash transaction. Example: operation_type=sell status string, optional; Filter by receipt status.Possible values: - - pending - the receipt is pending registration - - registered - the receipt is registered - error - the receipt could not be registered. Example: status=registered payment_idstring, optional; Filter by payment ID (get all receipts for the specified payment). Example: payment_id=764211668Only one thing can be passed in the request: either the payment ID or the refund ID. refund_idstring, optional;Filter by refund/cancellation ID (get all receipts for the specified refund/cancellation). Example: refund_id=764266262 Only one thing can be passed in the request: either the payment ID or the refund ID. totalstring, optional;Filter by the total amount of the receipt. Example: total=200 descriptionstring, optional;Filter by product name in the receipt. Displays all receipts, where the specified name occurs in the list of goods. Example: total=200 receipt_methodstring, optional;Filter by the method of creating the receipt. Displays all receipts that were created in the specified way. Possible values:- together - Receipt with payment - separately - Receipt is separate from the payment Example: receipt_method=separately limitstring, optional;The size of the output of the query results is the number of objects passed in the response. Possible values: from 1 to100. Example: limit=30 Default value: 10 offset string, optional;A pointer to the next fragment of the list. Example: offset=2 If the value 2 is passed, the system will unload the next portion of data specified in the limit filter value. utc string, optional;Time zone It is used to bring the time in the created_at filter to the time zone of the country from which the request itself comes. Example: utc=3

Request example


curl --location --globoff --request GET 'https://api.paybox.money/v5/receipts?created_at[gte]=2023-03-01&created_at[lte]=2023-03-31&offset=1&limit=2&utc=3' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Example of the response body


{
    "data": [
        {
            "merchant_id": "542088",
            "receipt_id": "8e6fa8d3-bf01-4a93-b453-4a018f15318d",
            "operation_type": "sell",
            "receipt_format": "ru_1_05",
            "status": "registered",
            "fiscal_document_number": "11900",
            "fiscal_storage_number": "9999078900006369",
            "fiscal_attribute": "790695398",
            "registered_at": "30.03.202315:20:00",
            "created_at": "30.03.202315:20:29",
            "fiscal_provider_id": "da7d533f-b547-46ca-b127-d0b2ba6cf9f1",
            "positions": [
                {
                    "name": "Товар №1",
                    "quantity": 1,
                    "price": 100,
                    "measure": "piece",
                    "vat_code": "vat_20",
                    "payment_method": "full_payment",
                    "payment_object": "goods",
                    "sum": 100
                },
                {
                    "name": "Товар №2",
                    "quantity": 2,
                    "price": 50,
                    "measure": "piece",
                    "vat_code": "vat_20",
                    "payment_method": "full_payment",
                    "payment_object": "goods",
                    "sum": 100
                }
            ],
            "total": 200,
            "settlements": [
                {
                    "type": "cashless",
                    "sum": 200
                }
            ],
            "company": {
                "inn": "5544332219",
                "email": "customer@mail.ru",
                "tax_system": "osn",
                "payment_address": "shop.ru"
            },
            "receipt_method": "separately",
            "error": null,
            "link": "https://consumer.1-ofd-test.ru/v1?fn=9999078900006369&fp=790695398&i=11900&t=20230330T152000&s=7&n=1",
            "payment_id": "764239789"
        },
        {
            "merchant_id": "542088",
            "receipt_id": "4e7dcdef-ccfc-485c-b63f-1f83dc66845c",
            "operation_type": "sell",
            "receipt_format": "ru_1_05",
            "status": "registered",
            "fiscal_document_number": "11552",
            "fiscal_storage_number": "9999078900006286",
            "fiscal_attribute": "3717461957",
            "registered_at": "30.03.202315:10:00",
            "created_at": "30.03.202315:12:37",
            "fiscal_provider_id": "f3b26edd-a098-42c9-952c-e981a0cff900",
            "positions": [
                {
                    "name": "Товар №1",
                    "quantity": 1,
                    "price": 300,
                    "measure": "piece",
                    "vat_code": "vat_20",
                    "payment_method": "full_payment",
                    "payment_object": "goods",
                    "sum": 300
                },
                {
                    "name": "Товар №2",
                    "quantity": 3,
                    "price": 50,
                    "measure": "piece",
                    "vat_code": "vat_20",
                    "payment_method": "full_payment",
                    "payment_object": "goods",
                    "sum": 150
                }
            ],
            "total": 450,
            "settlements": [
                {
                    "type": "cashless",
                    "sum": 150
                }
            ],
            "company": {
                "inn": "5544332219",
                "email": "customer@mail.ru",
                "tax_system": "osn",
                "payment_address": "shop.ru"
            },
            "receipt_method": "separately",
            "error": null,
            "link": "https://consumer.1-ofd-test.ru/v1?fn=9999078900006286&fp=3717461957&i=11552&t=20230330T151000&s=7&n=1",
            "payment_id": "763548541"
        }
    ]
}

In response to the request, a list of receipts will be returned, taking into account the filters sent. The list will contain information about receipts for the entire period of activity of a particular store, the ID of which was transmitted when generating the JWT. The list will be sorted by the time the receipts were created in descending order.

Getting information on the receipt

The request allows you to get information about the current status of the receipt by its unique identifier.

Request example

In the URL, you need to pass the ID of the receipt to Paybox.


curl --location --request GET 'https://api.paybox.money/v5/receipts/1a624e49-41c3-4d0f-84d3-497483e81153' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

Example of the response body
In response to the request, the receipt object will be sent in the current status.


{
    "data": {
        "merchant_id": "542088",
        "receipt_id": "1a624e49-41c3-4d0f-84d3-497483e81153",
        "operation_type": "sell",
        "receipt_format": "ru_1_05",
        "status": "registered",
        "fiscal_document_number": "9322",
        "fiscal_storage_number": "9999078900006369",
        "fiscal_attribute": "855240058",
        "registered_at": "28.03.202314:24:00",
        "created_at": "28.03.202317:24:02",
        "fiscal_provider_id": "509a911b-5d96-43ac-9df0-3e5d05cfc16a",
        "positions": [
            {
                "name": "Товар №1",
                "quantity": 1,
                "price": 100,
                "measure": "piece",
                "vat_code": "vat_20",
                "payment_method": "full_payment",
                "payment_object": "goods",
                "sum": 100
            },
            {
                "name": "Товар №2",
                "quantity": 2,
                "price": 50,
                "measure": "piece",
                "vat_code": "vat_20",
                "payment_method": "full_payment",
                "payment_object": "goods",
                "sum": 100
            }
        ],
        "total": 100,
        "settlements": [
            {
                "type": "cashless",
                "sum": 100
            }
        ],
        "company": {
            "inn": "5544332219",
            "email": "customer@mail.ru",
            "tax_system": "osn",
            "payment_address": "shop.ru"
        },
        "receipt_method": "together",
        "error": null,
        "link": "https://consumer.1-ofd-test.ru/v1?fn=9999078900006369&fp=855240058&i=9322&t=20230328T142400&s=7&n=1",
        "payment_id": "762881172"
    }
}