πŸ‡ΊπŸ‡Ώ Refund Fiscalization - OFD

Explanatory guide that helps companies to become compliant with local Uzbek tax authorities

πŸ› οΈ Processing a Refund with v2/api/payment/refund Endpoint

⚠️

Important: OFD Support

Please note that (OFD) functionality is only supported in thev2/api/payment/refund endpoint.

Ensure that you are using this version to incorporate fiscal data into your refund processing.

To initiate a payment refund process, you will need to make a PUT request to the v2/api/payment/refund endpoint.

This call should include a JSON request body containing the necessary regulatory details.

Request

{
  "transactionId": "",
  "amount": 1000,
  "idempotencyKey": "",
  "orderData": {
    "orderId": "1500",
    "advanceContractId": "",
    "orderItems": [
      {
        "productLink": "https://...",
        "productImage": "https://.../Image",
        "productName": "Product Name",
        "productCode": "",
        "productBarCode": "",
        "productLabel": "",
        "packageCode": "",
        "productQuantity": 0,
        "price": 0,
        "sumPrice": 0,
        "vat": 0,
        "vatPercent": 0,
        "discount": 0,
        "additionalDiscount": 0,
        "voucher": 0,
        "uzRegulatoryOrderItem": {
          "commissionInfoTin": "",
          "commissionInfoPinfl": ""
        }
      }
    ],
    "uzRegulatoryOrderDetails": {
      "latitude": 0,
      "longitude": 0,
      "taxiVehicleNumber": "",
      "taxiTin": "",
      "taxiPinfl": ""
    },
    "billingAddress": {
      "firstName": "",
      "lastName": "",
      "city": "",
      "country": "",
      "line1": "",
      "line2": "",
      "postalCode": "",
      "state": "",
      "phoneNumber": "",
      "personalId": "",
      "taxId": ""
    },
    "shippingAddress": {
      "firstName": "",
      "lastName": "",
      "city": "",
      "country": "",
      "line1": "",
      "line2": "",
      "postalCode": "",
      "state": "",
      "phoneNumber": "",
      "personalId": "",
      "taxId": ""
    }
  },
  "extraAttributes": [
    {
     "key": "RECEIPT_TYPE",
     "value": "Refund",
     "description": "OFD Receipt type"
    }
  ]
}

Request Description

Property

Type

Description

source

String

Payment source, in this case, "Card".

amount

Number

The amount for the transaction

currency

String

The three-letter currency code, here "UZS" for Uzbekistani soΚ»m.

metadata.order.orderId

String

Unique identifier for the order.

metadata.order.advanceContractId

String

DownPayment contract Id

metadata.order.uzRegulatoryOrderDetails

Object

Required if the merchant provides Taxi aggregation services.

latitude

Double

Location of Pickup (Optional)

longitude

Double

Location of Pickup (Optional)

taxiVehicleNumber

String(8)

Vehicle Number

taxiTin

String(9)

TIN (if the principal is a legal entity)

taxiPinfl

String(14)

PINFL (if the principal is an individual)

metadata.order.orderItems

Array

List of items within the order.

uzRegulatoryOrderItem

Object

Container for Uzbekistan's regulatory information for an order item.

commissionInfoPinfl

String

Personal Identification Number of the individual in fiscal data(Committent).
Required if the merchant is an individual entrepreneur.

commissionInfoTin

String

Tax Identification Number of the committent, required if the merchant is a legal entity.

productLink

String (URL)

Link to the product page. (Optional)

productImage

String (URL)

URL of the product's image. (Optional)

productName

String(63)

Name of the product. (Required)

productCode

String(17)

IKPU code (tasnif.soliq.uz)[https://tasnif.soliq.uz] On this site you can determine the IKPU codes of goods and services (Required)

productBarCode

String(13)

Barcode of the product. (Optional)

productLabel

String(21)

Label associated with the product.(AKA Marking code)(Optional)

packageCode

String(2)

Code for the product's packaging.(Required)

productQuantity

Number

Quantity of the product in the order.(Required)

price

Number

Price of a single product unit.(Required)

sumPrice

Number

Total price for the product quantity.(Required)

vat

Number

Value-added tax amount on the product.(Required)

vatPercent

Number

The percentage rate of the value-added tax.(Required)

discount

Number

Discount applied to the product. (Optional)

additionalDiscount

Number

Any additional discount applied to the product. Used for Insurances
(Optional)

voucher

Number

Total amount of voucher. Does not affect the order price or VAT (Optional)

metadata.order.billingAddress

Object

Container for the billing address information.

phoneNumber

String

Contact phone number of Card Holder.
(Required)

metadata.extraAttributes

Array

Additional attributes relevant to the payment.

key

String

RECEIPT_TYPE (Indicates the type of sale) (Required)

value

String

Indicates the type of sale, Default: Sale
Refund,<br />DownPayment,<br />Credit<br />(Required)

description

String

Description of what the extra attribute represents.
(Optional)

Payment Refund Confirmation and Receipts

Upon the successful completion of a payment, the cardholder will receive an SMS notification containing the URL to their OFD receipt. This ensures immediate access to transaction proof for customer convenience and record-keeping.

Cardholder Receipt

  • SMS Notification: An SMS will be sent to the cardholder's phone number as provided in the billing details. This message includes a direct URL to the OFD receipt for the completed transaction.

Merchant Receipt Retrieval

  • Receipt Endpoint: Merchants can obtain a copy of the transaction receipt by querying the /v2/api/payment/query/token-based through the transaction query endpoint. `Receipt property stores receipt URL.
    This allows for easy retrieval and storage of fiscal data necessary for compliance and accounting purposes.