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 (request.fiscalization for capture and payment or checkout.fiscalization for payment token) in the financial transaction requests.
The following card transactions support fiscalization:
- payment;
- refund;
- capture;
- payment token.
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.
|
|||||||||||||||||||||||||||||||||||||||||||||||||
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
|
|||||||||||||||||||||||||||||||||||||||||||||
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"
}
}
}
Refunds
Refunds with fiscalization are available for payment and capture transactions. The refunds can be made with an API request or in the merchant back office.
Info
Refunds with fiscalization are only available for the full amount of the original (parent) transaction.
Refunds with API
To initiate a refund with fiscalization, include fiscalization parameter set to true in the standard refund request.
Example of a refund request with fiscalization
{
"request": {
"amount": 10,
"parent_uid": "ec331643-d17f-4e3c-9a13-b15191e28193",
"reason": "Client request",
"fiscalization": true
}
}
Refunds in the merchant back office
Refunds can also be initiated in the merchant's back office on the Transaction details page. Follow the steps below to make a refund:
1) Find the transaction for which you need to make a refund on Orders page.
2) Click Refund
3) In the displayed modal window,submit the refund amount, enter the reason for the refund and select through the fiscalization service. The refund will be made for the full amount of the parent transaction regardless of the specified amount.
4) The information on the refund along with the associated fiscalization data will be displayed on the transaction details page for the refund and the corresponding original transaction.
