API Reference

๐Ÿ‡บ๐Ÿ‡ฟ Refund Fiscalization - OFD

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

Suggest Edits

๐Ÿ› ๏ธ Processing a Refund with v2/api/payment/refund Endpoint

โš ๏ธ

Important: OFD Support

Please note that (OFD) functionality is only supported in the v2/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": "Sale",
     "description": "OFD Receipt type"
    }
  ]
}

Request Description

PropertyTypeDescription
sourceStringPayment source, in this case, "Card".
amountNumberThe amount for the transaction
currencyStringThe three-letter currency code, here "UZS" for Uzbekistani soสปm.
metadata.order.orderIdStringUnique identifier for the order.
metadata.order.advanceContractIdStringDownPayment contract Id
metadata.order.uzRegulatoryOrderDetailsObjectRequired if the merchant provides Taxi aggregation services.
latitudeDoubleLocation of Pickup (Optional)
longitudeDoubleLocation of Pickup (Optional)
taxiVehicleNumberString(8)Vehicle Number
taxiTinString(9)TIN (if the principal is a legal entity)
taxiPinflString(14)PINFL (if the principal is an individual)
metadata.order.orderItemsArrayList of items within the order.
uzRegulatoryOrderItemObjectContainer for Uzbekistan's regulatory information for an order item.
commissionInfoPinflStringPersonal Identification Number of the individual in fiscal data(Committent).
Required if the merchant is an individual entrepreneur.
commissionInfoTinStringTax Identification Number of the committent, required if the merchant is a legal entity.
productLinkString (URL)Link to the product page. (Optional)
productImageString (URL)URL of the product's image. (Optional)
productNameString(63)Name of the product. (Required)
productCodeString(17)IKPU code (tasnif.soliq.uz)[https://tasnif.soliq.uz] On this site you can determine the IKPU codes of goods and services (Required)
productBarCodeString(13)Barcode of the product. (Optional)
productLabelString(21)Label associated with the product.(AKA Marking code)(Optional)
packageCodeString(2)Code for the product's packaging.(Required)
productQuantityNumberQuantity of the product in the order.(Required)
priceNumberPrice of a single product unit.(Required)
sumPriceNumberTotal price for the product quantity.(Required)
vatNumberValue-added tax amount on the product.(Required)
vatPercentNumberThe percentage rate of the value-added tax.(Required)
discountNumberDiscount applied to the product. (Optional)
additionalDiscountNumberAny additional discount applied to the product. Used for Insurances
(Optional)
voucherNumberTotal amount of voucher. Does not affect the order price or VAT (Optional)
metadata.order.billingAddressObjectContainer for the billing address information.
phoneNumberStringContact phone number of Card Holder.
(Required)
metadata.extraAttributesArrayAdditional attributes relevant to the payment.
keyStringRECEIPT_TYPE (Indicates the type of sale) (Required)
valueStringIndicates the type of sale, Default: Sale
Refund, DownPayment, Credit(Required)
descriptionStringDescription 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.

Updated about 1 month ago