Фискализация
API Freepayment позволяет отправить фискальные данные в запросе финансовой транзакции и получить в ответе ссылку на фискальный чек.
Дополнительные параметры запроса для фискализации
Чтобы отправить фискальные данные, вам необходимо передать дополнительные параметры в объекте fiscalization в запросе финансовой транзакции.
Для банковских карт, фискализацию поддерживают следующие транзакции:
- оплата;
- возврат средств;
- списание средств.
Для альтернативных способов оплаты, фискализацию поддерживают следующие транзакции:
- оплата;
- возврат средств;
- списание средств.
Вариант интеграции Orange Data
При этом варианте интеграции фискальные данные формируются в асинхронном режиме.
Фискальные данные можно получить:
- в ответе на запрос статуса
- в личном кабинете на странице детальной информации о транзакции.
Запрос
Info
Обратите внимание, что для корректной обработки запроса фискализации, необходимо указать ИНН (идентификационный номер налогоплательщика) в поле Налоговый номер при создании/редактировании торговца/магазина в личном кабинете системы. Для обработки запроса будет использован Налоговый номер магазина. При его отсутствии в личном кабинете, будет использован Налоговый номер торговца.
Info
В запросе в объекте `billing_address` или `customer`, нужно обязательно прислать параметр `email` и/или `phone`.
В таблице ниже указаны параметры и их возможные значения для объекта fiscalization.
| Параметр | Тип | Описание |
|---|---|---|
| fiscalization | object | Секция параметров фискализации. |
| external_id | string (255) | Уникальный идентификатор транзакции в системе торговца. |
| operator * обязательный |
string (255) | Идентификатор группы устройств, с помощью которых будет пробит чек. |
| positions * обязательный |
array | Список предметов расчета, каждый элемент которого состоит из ряда параметров, например: |
| name * обязательный |
string (255) | Наименование позиции в чеке. |
| type *обязательный |
string (24) | Тип позиции в чеке. Возможные значения: product; product_storno; gambling_bet; и другие. |
| pay_type | string (24) | Признак способа расчета. Возможные значения: full_prepay - Предоплата 100%; partial_prepay - Частичная предоплата; advance - Аванс и другие. Если не передано, по умолчанию используется full_pay. |
| pay_method | string (24) | Тип оплаты по чеку. Возможные значения: full_cash - наличными;full_cashless - безналичными; и другие. Если не передано, по умолчанию используется full_cashless. |
| amount * обязательный |
bigInteger | Сумма позиции в чеке c учетом скидок и наценок в минимальных денежных единицах. Сумма значений amount по всем позициям в чеке должна быть равна значению основного параметра amount в запросе финансовой транзакции. |
| quantity * обязательный |
float (8) | Количество однотипной позиции в чеке. Десятичное число с точностью до 6 символов после точки. |
| description | string (510) | Описание позиции в чеке. |
| nomenclature_code | string (510) | Номенклатурный код товара. |
| untaxed | boolean | Если true, не участвует в расчете налогов. В этом случае, массив taxes не обязателен. Если false, участвует в расчете налогов. В этом случае, массив taxes обязателен в запросе. |
| taxes *условно обязательный |
array | Массив с данными о налогах. Обязателен за исключением случаев, когда "untaxed": true". |
| percent * обязательный |
string (6) | Налоговая ставка. Возможные значения: 20 10 20/120 10/110 0 |
| system | string (255) | Система налогообложения. Возможные значения: standard - ОСН (общая система налогообложения),simplified - УСН (упрощенная система налогообложения), и другие. |
| id | string (32) | Идентификатор налога в системе торговца. |
| description | string (510) | Описание типа налога. |
Пример запроса на карточный платеж с фискализацией
{
"request": {
"amount": "1800",
"currency": "RUB",
"description": "qwerty",
"tracking_id": "your_uniq_number",
"language": "en",
"test": false,
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"country": "RU",
"city": "Moscow",
"state": "99",
"zip": "00001",
"address": "Street 1 ",
"phone": "+1 (123) 1234567890"
},
"credit_card": {
"number": "5555444433331111",
"verification_value": "737",
"holder": "JOHN DOE",
"exp_month": "07",
"exp_year": "2027"
},
"customer": {
"email": "john.doe@example.com",
"ip": "0.0.0.0",
"phone": "+12312312312345"
},
"fiscalization": {
"external_id": "id",
"operator": "MAIN",
"positions": [
{
"name": "985621466",
"type": "product",
"amount": 1100,
"quantity": 1.0,
"description": "123456789",
"untaxed": false,
"taxes": [
{
"system": "simplified",
"percent": "10"
}
]
},
{
"name": "name1",
"type": "product",
"amount": 700,
"quantity": 1.0,
"description": "string 510",
"untaxed": false,
"taxes": [
{
"percent": "20/120"
}
]
}
]
}
}
}
Ответ
| Параметр | Тип | Описание |
|---|---|---|
| fiscalization | object | Секция параметров фискализации. |
| type | string | Тип транзакции. Возможные значения: payment, refund, payout. |
| id | string (36) | Идентификатор транзакции в системе Freepayment. |
| external_id | string (255) | Внешний идентификатор транзакции фискализации торговца. |
| status * обязательный |
string (255) | Статус транзакции фискализации. Возможные значения: successful - успешно; failed - ошибка проведения транзакции на стороне провайдера; pending (или incomplete) - транзакция в процессе обработки; error (или expired или deleted) - ошибка обработки транзакции в системе Freepayment. |
| code * обязательный |
string (6) | Код результата транзакции фискализации. |
| message *обязательный |
string (255) | Сообщение для торговца о результате транзакции фискализации. |
| friendly_message *обязательный |
string (255) | Сообщение для покупателя о результате транзакции фискализации. |
| operator | string (255) | Идентификатор группы устройств, с помощью которых будет пробит чек. |
| device | string (255) | Идентификатор ККМ. |
| receipts * обязательный |
array | Массив чеков. |
| id * обязательный |
string (255) | Уникальный идентификатор чека в системе Freepayment. |
| serial_id | string (255) | Последовательный номер чека в ККМ. |
| receipt_num | string (255) | Номер чека в системе Freepayment. |
| created_at | string | Время и дата создания чека в системе Freepayment. Формат: YYYY-MM-DDThh:mm:ssTZD, где YYYY – год (например, 2019), MM – месяц (например, 02), DD – день (например, 09), hh – часы (например, 18), mm – минуты (например, 20), ss – секунды (например, 45), TZD – часовой пояс (+hh:mm или –hh:mm относительно UTC). |
| ofd_id | string (255) | Уникальный идентификатор фискального чека в системе ОФД (оператора фискальных данных). |
| ofd_link * обязательный |
string (1024) | Ссылка на сайт оператора фискальных данных. |
| ofd_qr_code * обязательный |
string (1024) | Ссылка на фискальный чек, содержащий QR код. |
| total_amount | integer | Сумма по чеку в минимальных денежных единицах. |
| receipt_info | object | Исходные данные из ответа Freepayment или ОФД. |
Пример синхронного ответа на карточный платеж с фискализацией
{
"transaction": {
"uid": "a5c5bf0f-38f3-4f15-862d-f5ed08b640c3",
"status": "successful",
"amount": 1800,
"currency": "RUB",
"description": "qwerty",
"type": "payment",
"payment_method_type": "credit_card",
"tracking_id": "your_uniq_number",
"message": "Successfully processed",
"test": false,
"created_at": "2023-11-22T08:18:23.839Z",
"updated_at": "2023-11-22T08:18:24.265Z",
"paid_at": "2023-11-22T08:18:24.217Z",
"expired_at": null,
"recurring_type": null,
"closed_at": null,
"settled_at": null,
"manually_corrected_at": null,
"language": "en",
"credit_card": {
"holder": "JOHN DOE",
"stamp": "8656cb1f676f80ff7aa84d72dc7fdb0be93781e84710cd47fe9aab86163cabf9",
"brand": "master",
"last_4": "1111",
"first_1": "5",
"bin": "555544",
"bin_8": "55554444",
"issuer_country": null,
"issuer_name": null,
"product": null,
"exp_month": 7,
"exp_year": 2027,
"token_provider": null,
"token": null
},
"receipt_url": "https://account.freepayment.online/customer/transactions/a5c5bf0f-38f3-4f15-862d-f5ed08b640c3/b562942e785b4c3999fb00227f831912d1d9ee22ffb379f67ee805505b0ec7e9?language=en",
"status_code": null,
"gateway": {
"iframe": true
},
"mute_notifications": null,
"id": "a5c5bf0f-38f3-4f15-862d-f5ed08b640c3",
"fiscalization": {
"type": "payment",
"amount": 1800,
"id": "5b95328a-a657-496a-bcef-93a87efd8477",
"external_id": "id",
"status": "incomplete",
"code": null,
"message": null,
"friendly_message": null,
"operator": "MAIN",
"device": null,
"receipts": [
{}
]
},
"redirect_url": "https://account.freepayment.online/process/a5c5bf0f-38f3-4f15-862d-f5ed08b640c3",
"payment": {
"auth_code": "654321",
"bank_code": "05",
"rrn": "999",
"ref_id": "777888",
"message": "Payment was approved",
"amount": 1800,
"currency": "RUB",
"billing_descriptor": "TEST GATEWAY BILLING DESCRIPTOR",
"gateway_id": 2956,
"status": "successful"
},
"avs_cvc_verification": {
"avs_verification": {
"result_code": "1"
},
"cvc_verification": {
"result_code": "1"
}
},
"customer": {
"ip": "0.0.0.0",
"email": "john.doe@example.com",
"device_id": null,
"birth_date": null
},
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"address": "Street 1 ",
"country": "RU",
"city": "Moscow",
"zip": "00001",
"state": "99",
"phone": "+1 (123) 1234567890"
}
}
}
Пример ответа на запрос статуса с фискальными данными
{
"transaction": {
"uid": "a5c5bf0f-38f3-4f15-862d-f5ed08b640c3",
"status": "successful",
"amount": 1800,
"currency": "RUB",
"description": "qwerty",
"type": "payment",
"payment_method_type": "credit_card",
"tracking_id": "your_uniq_number",
"message": "Successfully processed",
"test": false,
"created_at": "2023-11-22T08:18:23.839Z",
"updated_at": "2023-11-22T08:18:24.265Z",
"paid_at": "2023-11-22T08:18:24.217Z",
"expired_at": null,
"recurring_type": null,
"closed_at": null,
"settled_at": null,
"manually_corrected_at": null,
"language": "en",
"credit_card": {
"holder": "JOHN DOE",
"stamp": "8656cb1f676f80ff7aa84d72dc7fdb0be93781e84710cd47fe9aab86163cabf9",
"brand": "master",
"last_4": "1111",
"first_1": "5",
"bin": "555544",
"bin_8": "55554444",
"issuer_country": null,
"issuer_name": null,
"product": null,
"exp_month": 7,
"exp_year": 2027,
"token_provider": null,
"token": null
},
"receipt_url": "https://account.freepayment.online/customer/transactions/a5c5bf0f-38f3-4f15-862d-f5ed08b640c3/b562942e785b4c3999fb00227f831912d1d9ee22ffb379f67ee805505b0ec7e9?language=en",
"status_code": null,
"gateway": {
"iframe": true
},
"mute_notifications": null,
"id": "a5c5bf0f-38f3-4f15-862d-f5ed08b640c3",
"fiscalization": {
"type": "payment",
"amount": 1800,
"id": "5b95328a-a657-496a-bcef-93a87efd8477",
"external_id": "id",
"status": "successful",
"code": null,
"message": "Ok - Check processed",
"friendly_message": "Ok - Check processed",
"operator": "MAIN",
"device": null,
"receipts": [
{
"id": "5b95328a-a657-496a-bcef-93a87efd8477",
"ofd_id": "872970506",
"ofd_link": "www.taxcom.ru",
"serial_id": 130,
"created_at": "2023-11-22T11:18:00",
"ofd_qr_code": "https://cheques-test.orangedata.ru/7727401209/5b95328a-a657-496a-bcef-93a87efd8477",
"receipt_num": 192058,
"receipt_info": {
"fp": "872970506",
"id": "5b95328a-a657-496a-bcef-93a87efd8477",
"change": 0.0,
"ofdinn": "7704211201",
"content": {
"type": 1,
"positions": [
{
"tax": 6,
"text": "985621466",
"price": 11.0,
"quantity": 1.0,
"paymentMethodType": 4,
"paymentSubjectType": 1
},
{
"tax": 3,
"text": "name1",
"price": 7.0,
"quantity": 1.0,
"paymentMethodType": 4,
"paymentSubjectType": 1
}
],
"checkClose": {
"payments": [
{
"type": 2,
"amount": 11.0
},
{
"type": 2,
"amount": 7.0
}
]
},
"ffdVersion": 2,
"customerContact": "john.doe@example.com"
},
"ofdName": "Такском ТЕСТ",
"deviceRN": "0000000000034229",
"deviceSN": "0001660038015559",
"fsNumber": "9999078900011495",
"companyINN": "7727401209",
"fnsWebsite": "www.nalog.gov.ru",
"ofdWebsite": "www.taxcom.ru",
"companyName": "company",
"processedAt": "2023-11-22T11:18:00",
"shiftNumber": 173,
"documentIndex": 130,
"processedAtTz": "2023-11-22T11:18:00.0000000+03:00",
"documentNumber": 192058
},
"total_amount": 1800
}
]
},
"redirect_url": "https://account.freepayment.online/process/a5c5bf0f-38f3-4f15-862d-f5ed08b640c3",
"payment": {
"auth_code": "654321",
"bank_code": "05",
"rrn": "999",
"ref_id": "777888",
"message": "Payment was approved",
"amount": 1800,
"currency": "RUB",
"billing_descriptor": "TEST GATEWAY BILLING DESCRIPTOR",
"gateway_id": 2956,
"status": "successful"
},
"avs_cvc_verification": {
"avs_verification": {
"result_code": "1"
},
"cvc_verification": {
"result_code": "1"
}
},
"customer": {
"ip": "0.0.0.0",
"email": "john.doe@example.com",
"device_id": null,
"birth_date": null
},
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"address": "Street 1 ",
"country": "RU",
"city": "Moscow",
"zip": "00001",
"state": "99",
"phone": "+1 (123) 1234567890"
}
}
}