Fiscalization
Freepayment API lets you send fiscalization information in the request of the financial transaction and receive a link to a fiscal receipt in the response.
Additional parameters for fiscalization
To send the fiscalization information, you need to send additional parameters in the fiscalization object in the financial transaction requests.
The following card transactions support fiscalization:
- payment;
- refund;
- capture.
For alternative payment methods, you can send fiscalization information in the following transactions:
- payment;
- refund;
- capture.
Orange Data integration option
The fiscal receipt is formed in an asynchronous mode.
You can look up fiscal data
- in the response to the status query;
- in the back office, in the transaction details.
Request
Info
Note that in order for the fiscalization request to be processed properly, it is required to specify TIN (taxpayer identification number) under Tax Id field in the back office system when editing/setting up a corresponding merchant and/or shop. The system will use the shop's Tax Id. If not specified, it will use the merchant's Tax Id.
Info
The transaction request must contain `email` and/or `phone` parameter in `billing_address` or `customer` object.
The table below lists the request parameters and their descriptions for this integration option for the fiscalization object.
| Parameter | Type | Description |
|---|---|---|
| fiscalization | object | A section of fiscalization parameters. |
| external_id | string (255) | Unique transaction identifier in the merchant's system. |
| operator * required |
string (255) | Identifier of the group of devices used to process the receipt. |
| positions * required |
array | A list of the receipt items where each item contains the following parameters: |
| name * required |
string (255) | The name of the receipt item. |
| type * required |
string (24) | Possible values:product; product_storno; gambling_bet; other values. |
| pay_type | string (24) | Calculation type. Possible values: full_prepay - 100% prepayment; partial_prepay - partial prepayment; advance - advance paymentother values. If not sent, full_pay is use by default. |
| pay_method | string (24) | Payment method. Possible values are listed here. If not sent, full_cashless is used by default. |
| amount * required |
bigInteger | Receipt item payment amount including all discounts and surcharges in minimal currency units. The sum of the amount values for all the receipt items must not exceed the transaction amount. |
| quantity * required |
float (8) | The amount/number of the identical receipt items. A number with up to 6 decimal places. |
| description | string (510) | Description of the receipt item. |
| nomenclature_code | string (510) | Nomenclature code of the receipt item. |
| untaxed | boolean | If true, ignored when calculating taxes. In this case, the taxes array is not required. If false, participates in the calculation of taxes. In this case, the taxes array is required in the request. |
| taxes *conditionally required |
array | Array with the taxes data. Required except for the cases when "untaxed": true. |
| percent * required |
string (6) | The tax rate. Possible values: 20 10 20/120 10/110 0 |
| system | string (255) | The taxation system. Possible values: standard - standard taxation system,simplified - simplified taxation system,other values. |
| id | string (32) | Tax identifier in the merchant's system. |
| description | string (510) | Description of the tax type. |
Card payment request example with fiscalization object
{
"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"
}
]
}
]
}
}
}
Response
| Parameter | Type | Description |
|---|---|---|
| fiscalization | object | Fiscalization parameters. |
| type | string | Transaction type. Possible values: payment, refund, payout. |
| id | string (36) | Transaction id in Freepayment system. |
| external_id | string (255) | Transaction id in the merchant's system |
| status * required |
string (255) | Fiscalization transaction status. Possible values: successful - successfully processed; failed - transaction processing error in the provider's system; pending (or incomplete) - transaction is being processed; error (or expired or deleted) - transaction processing error in the Freepayment system. |
| code * required |
string (6) | Fiscalization transaction result code. |
| message * required |
string (255) | Fiscalization transaction result message for the merchant. |
| friendly_message * required |
string (255) | Fiscalization transaction result message for the customer (only in API v.3). |
| operator | string (255) | Identifier of the group of devices used to process the receipt. |
| device | string (255) | Identifier of the cash register. |
| receipts *required |
array | Array of receipts. |
| id * required |
string (255) | Unique receipt identifier in the system of Freepayment. |
| serial_id | string (255) | Receipt sequence number in the cash register. |
| receipt_num | string (255) | Receipt number in Freepayment system. |
| created_at | string | Time and date of the receipt creation in Freepayment system. Set in the ISO-8601 format: YYYY-MM-DDThh:mm:ssTZD, where YYYY – year (for example, 2019), MM – month (for example, 02), DD – day (for example, 09), hh – hours (for example, 18), mm – minutes (for example, 20), ss – seconds (for example, 45), TZD – time zone (+hh:mm or –hh:mm indicating an offset from UTC). |
| ofd_id | string (255) | Unique identifier of the fiscal receipt in OFD system (Operator of Fiscal Data). |
| ofd_link * required |
string (1024) | Link to OFD website. |
| ofd_qr_code * required |
string (1024) | Link to the fiscal receipt with the QR code. |
| total_amount | integer | Receipt amount in minimal currency units. |
| receipt_info | object | Information from the original response of OFD. |
Synchronous response example to payment request with fiscalization object
{
"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"
}
}
}
Response example to status query with fiscalization object
{
"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"
}
}
}