---
title: "Refund a payment"
method: POST
path: "/api/v2/payments/{id}/refunds"
tags: ["Payments"]
---

# Refund a payment

`POST /api/v2/payments/{id}/refunds`

Send a full or partial refund amount request. You can only refund the payment that has Closed status. By default refunds reflect instantly, which means Tabby initiates a refund through payment gateway.

## Path parameters

- `id` string, uuid, required

## Request body

- RefundRequest
  - `amount` string, required — Amount refunded. Allows to send up to 2 decimals for AED and SAR, up to 3 decimals for KWD.
  - `reference_id` string, required — Idempotency key. Used to avoid similar refund requests.
  - `reason` string — Reason for the refund.
  - `items` OrderItem[] — Array of objects representing the order items being refunded.
    - `reference_id` string — Merchant’s product identifier. Displayed in Customer's App and Merchant Dashboard, used for Item refunds and disputes.
    - `title` string, required — Name of the product.
    - `description` string — Description of the product.
    - `quantity` integer, required — Quantity of the product ordered.
    - `unit_price` string, required — Price per unit of the product. Should be positive or zero.
    - `discount_amount` string — Amount of the applied discount if any. Should be positive or zero.
    - `image_url` string, uri — URL of the item image to show in the order information.
    - `product_url` string, uri — URL of the item at your store.
    - `gender` 'Male' | 'Female' | 'Kids' | 'Other' — Who the goods are designed to.
    - `category` string, required — Required as name of high-level category (Clothes, Electronics,etc.); or a tree of category-subcategory1-subcategory2; or id of the category and table with category-ids data mapped provided.
    - `color` string — white / blue/ green
    - `product_material` string — cotton / polyester / synthetic
    - `size_type` string — EU / UK
    - `size` string — L / XL / 12
    - `brand` string — Mango / Dorothy Perkins / Tommy Hilfiger
    - `is_refundable` boolean — Indicates whether a product can be returned
    - `barcode` string — A machine-readable product identifier. Typically used for logistics and scanning.
    - `ppn` string — Product Part Number assigned by the manufacturer. Used to identify specific components or versions of a product.
    - `seller` string — The name of the seller offering this item. This field is used to distinguish products from different vendors on a single marketplace.

## Response `200`

Success. Payment object is returned.

- PaymentRefundResponse — Payment object.
  - `id` string, uuid — Unique identifier for the payment (UUID), assigned by Tabby. Save it on your side!
  - `created_at` string, date-time — Date and time the payment was created, in UTC, and displayed in ISO 8601 datetime format.
  - `expires_at` string, date-time — Date and time the payment expires, in UTC, and displayed in ISO 8601 datetime format.
  - `status` 'CREATED' | 'AUTHORIZED' | 'CLOSED' | 'REJECTED' | 'EXPIRED' — Status of the current payment: - `CREATED` means that the payment is created successfully, but not finished yet; - `AUTHORIZED` and `CLOSED` mark the successfully approved and captured payments accordingly; - `REJECTED` is returned when a customer is rejected during Tabby Checkout; - `EXPIRED` is used when a customer cancels a payment or when Tabby doesn't receive a successfully paid transaction after timeout.
  - `is_test` boolean — Indicates whether this is a test payment (created using the Test API keys or Production API Keys).
  - `amount` string, required — Total payment amount, including tax, shipping and any discounts. Allows to send up to 2 decimals for AED and SAR, up to 3 decimals for KWD.
  - `currency` 'AED' | 'SAR', required — ISO 4217 currency code for the payment amount. Currently there are 2 possible currency options - depending on the country where the store is located: - `AED` - United Arab Emirates Dirham - `SAR` - Saudi Riyal
  - `description` string, nullable
  - `buyer` BuyerResponse, nullable, required — Customer information
    - `name` string, nullable, required — Customer’s full name.
    - `email` string, email, nullable, required — Customer’s email address.
    - `phone` string, nullable, required — Customer’s phone number. This must be a valid mobile phone where the consumer can receive text messages. The accepted phone masks are - `500000001`, `0500000001`, `+971500000001`, `971500000001`.
    - `dob` string, date, nullable — Customer's date of birth; format is YYYY-MM-DD.
  - `shipping_address` ShippingAddressResponse, nullable, required
    - `city` string, nullable, required — Name of city, municipality, or village.
    - `address` string, nullable, required — Building name, apartment number.
    - `zip` string, nullable, required — Postal code.
  - `order` OrderResponse, nullable, required
    - `reference_id` string, nullable, required — Merchant-assigned order number.
    - `updated_at` string, date-time — Date and time the order was last updated, in UTC, and displayed in ISO 8601 datetime format.
    - `tax_amount` string — Total tax for the order.
    - `shipping_amount` string — Total shipping cost for the order.
    - `discount_amount` string — Total discount for the order. Should be positive or zero. Shows up on Tabby App for the Customer's convenience.
    - `items` OrderItemResponse[], nullable, required — Array of objects representing the order items in this payment.
      - `reference_id` string, nullable — Merchant’s product identifier. Displayed in Customer's App and Merchant Dashboard, used for Item refunds and disputes.
      - `title` string, nullable, required — Name of the product.
      - `description` string, nullable — Description of the product.
      - `quantity` integer, required — Quantity of the product ordered.
      - `unit_price` string, required — Price per unit of the product. Should be positive or zero.
      - `image_url` string, uri, nullable — URL of the item image to show in the order information.
      - `product_url` string, uri, nullable — URL of the item at your store.
      - `gender` 'Male' | 'Female' | 'Kids' | 'Other', nullable — Who the goods are designed to.
      - `category` string, nullable, required — Required as name of high-level category (Clothes, Electronics,etc.); or a tree of category-subcategory1-subcategory2; or id of the category and table with category-ids data mapped provided.
      - `color` string, nullable — white / blue/ green
      - `product_material` string, nullable — cotton / polyester / synthetic
      - `size_type` string, nullable — EU / UK
      - `size` string, nullable — L / XL / 12
      - `brand` string, nullable — Mango / Dorothy Perkins / Tommy Hilfiger
      - `is_refundable` boolean, nullable — Indicates whether a product can be returned
  - `captures` CaptureResponse[]
    - `id` string, uuid — Unique capture ID, assigned by Tabby.
    - `created_at` string, date-time — Date and time the capture was created, in UTC, and displayed in ISO 8601 datetime format, assigned by Tabby.
    - `amount` string, required — Total payment amount, including tax, shipping and any discounts. Allows to send up to 2 decimals for AED and SAR, up to 3 decimals for KWD.
    - `tax_amount` string — Tax amount captured.
    - `shipping_amount` string — Shipping cost captured.
    - `discount_amount` string — Total discount for the order. Should be positive or zero.
    - `items` OrderItemResponse[], nullable — Array of objects representing the order items being captured.
      - `reference_id` string, nullable — Merchant’s product identifier. Displayed in Customer's App and Merchant Dashboard, used for Item refunds and disputes.
      - `title` string, nullable, required — Name of the product.
      - `description` string, nullable — Description of the product.
      - `quantity` integer, required — Quantity of the product ordered.
      - `unit_price` string, required — Price per unit of the product. Should be positive or zero.
      - `image_url` string, uri, nullable — URL of the item image to show in the order information.
      - `product_url` string, uri, nullable — URL of the item at your store.
      - `gender` 'Male' | 'Female' | 'Kids' | 'Other', nullable — Who the goods are designed to.
      - `category` string, nullable, required — Required as name of high-level category (Clothes, Electronics,etc.); or a tree of category-subcategory1-subcategory2; or id of the category and table with category-ids data mapped provided.
      - `color` string, nullable — white / blue/ green
      - `product_material` string, nullable — cotton / polyester / synthetic
      - `size_type` string, nullable — EU / UK
      - `size` string, nullable — L / XL / 12
      - `brand` string, nullable — Mango / Dorothy Perkins / Tommy Hilfiger
      - `is_refundable` boolean, nullable — Indicates whether a product can be returned
    - `reference_id` string, nullable, required — Idempotency key. Used to avoid similar capture requests.
  - `refunds` RefundResponse[]
    - `id` string, uuid — Unique refund ID, assigned by Tabby.
    - `created_at` string, date-time — Date and time the refund was created, in UTC, and displayed in ISO 8601 datetime format, assigned by Tabby.
    - `amount` string, required — Amount refunded. Allows to send up to 2 decimals for AED and SAR, up to 3 decimals for KWD.
    - `reason` string, nullable — Reason for the refund.
    - `items` OrderItemResponse[], nullable — Array of objects representing the order items being refunded.
      - `reference_id` string, nullable — Merchant’s product identifier. Displayed in Customer's App and Merchant Dashboard, used for Item refunds and disputes.
      - `title` string, nullable, required — Name of the product.
      - `description` string, nullable — Description of the product.
      - `quantity` integer, required — Quantity of the product ordered.
      - `unit_price` string, required — Price per unit of the product. Should be positive or zero.
      - `image_url` string, uri, nullable — URL of the item image to show in the order information.
      - `product_url` string, uri, nullable — URL of the item at your store.
      - `gender` 'Male' | 'Female' | 'Kids' | 'Other', nullable — Who the goods are designed to.
      - `category` string, nullable, required — Required as name of high-level category (Clothes, Electronics,etc.); or a tree of category-subcategory1-subcategory2; or id of the category and table with category-ids data mapped provided.
      - `color` string, nullable — white / blue/ green
      - `product_material` string, nullable — cotton / polyester / synthetic
      - `size_type` string, nullable — EU / UK
      - `size` string, nullable — L / XL / 12
      - `brand` string, nullable — Mango / Dorothy Perkins / Tommy Hilfiger
      - `is_refundable` boolean, nullable — Indicates whether a product can be returned
    - `reference_id` string, nullable, required — Idempotency key. Used to avoid similar refund requests.
  - `buyer_history` BuyerHistoryResponse, required — Customer / user / student information from previous purchases with you.
    - `registered_since` string, date-time, required — Date and time the customer / user / student got registred with your store / portal, in UTC, and displayed in ISO 8601 datetime format.
    - `loyalty_level` number, required — Customer / user / student loyalty level with you. Should be sent as a number of successfully placed purchases from your store / portal with any payment methods.
    - `wishlist_count` number — Number of items in Customer's wishlist.
    - `is_social_networks_connected` boolean, nullable — Is social network connected.
    - `is_phone_number_verified` boolean, nullable — Is phone number verified.
    - `is_email_verified` boolean, nullable — Is email verified.
  - `order_history` OrderHistoryResponse[], nullable, required — Array of objects, should contain information on 5-10 previously placed via any payment method orders in any status, current order excluded.
    - `purchased_at` string, date-time, nullable, required — Date and time the order was placed, in UTC, and displayed in ISO 8601 datetime format.
    - `amount` string, nullable, required — Total payment amount, including tax, shipping and any discounts. Allows to send up to 2 decimals for AED and SAR, up to 3 decimals for KWD.
    - `payment_method` 'card' | 'cod', nullable — Payment method used.
    - `status` 'new' | 'processing' | 'complete' | 'refunded' | 'canceled' | 'unknown', nullable, required — Status of the order.
    - `buyer` BuyerResponse, nullable, required — Customer information
      - `name` string, nullable, required — Customer’s full name.
      - `email` string, email, nullable, required — Customer’s email address.
      - `phone` string, nullable, required — Customer’s phone number. This must be a valid mobile phone where the consumer can receive text messages. The accepted phone masks are - `500000001`, `0500000001`, `+971500000001`, `971500000001`.
      - `dob` string, date, nullable — Customer's date of birth; format is YYYY-MM-DD.
    - `shipping_address` ShippingAddressResponse, nullable, required
      - `city` string, nullable, required — Name of city, municipality, or village.
      - `address` string, nullable, required — Building name, apartment number.
      - `zip` string, nullable, required — Postal code.
    - `items` OrderItemHistoryResponse[], nullable — Array of objects representing the order items in this payment. If you want to offer consumers a discount, use this object to create a “discount order item”, with the unit_price set to the negative value of the discount.
      - `reference_id` string, nullable — Merchant’s product identifier. Displayed in Customer's App and Merchant Dashboard, used for Item refunds and disputes.
      - `title` string, nullable, required — Name of the product.
      - `description` string, nullable — Description of the product.
      - `quantity` integer, required — Quantity of the product ordered.
      - `unit_price` string, required — Price per unit of the product. Should be positive or zero.
      - `image_url` string, uri, nullable — URL of the item image to show in the order information.
      - `product_url` string, uri, nullable — URL of the item at your store.
      - `gender` 'Male' | 'Female' | 'Kids' | 'Other', nullable — Who the goods are designed to.
      - `category` string, nullable, required — Required as name of high-level category (Clothes, Electronics,etc.); or a tree of category-subcategory1-subcategory2; or id of the category and table with category-ids data mapped provided.
      - `color` string, nullable — white / blue/ green
      - `product_material` string, nullable — cotton / polyester / synthetic
      - `size_type` string, nullable — EU / UK
      - `size` string, nullable — L / XL / 12
      - `brand` string, nullable — Mango / Dorothy Perkins / Tommy Hilfiger
      - `is_refundable` boolean, nullable — Indicates whether a product can be returned
      - `ordered` integer — Quantity of SKUs in the order without a final status yet.
      - `captured` integer — Quantity of captured SKUs in the order (paid by customer).
      - `shipped` integer — Quantity of SKUs in the order shipped to the customer.
      - `refunded` integer — Quantity of SKUs in the order refunded to the customer.
  - `meta` Meta, nullable — Merchant-defined data about the payment. This field is a key-value map. The example properties provided below.
    - `customer` string, nullable
    - `order_id` string, nullable
  - `attachment` AttachmentV1, nullable — Extra data (booking info, insurance, flight reservations, ...) as serialized JSON
    - `body` object, required — Should be an object containing any of the keys with corresponded sub objects
      - `flight_reservation_details` FlightReservationDetails
        - `pnr` string — Trip booking number, e.g. TR9088999
        - `itinerary` object[], required — Itinerary data, one per segment
          - `departure_city` string
          - `departure_country` string
          - `arrival_city` string
          - `arrival_country` string
          - `carrier` string
          - `departure_date` string, date-time — RFC3339 e.g. 2018-10-17T07:26:33Z
          - `class` string
          - `refundable` boolean — true - if ticket can be cancelled/refunded
        - `insurance` object[], required — Insurance data
          - `insurance_company` string
          - `insurance_type` string
          - `insurance_price` number
        - `passengers` object[], required — Passengers data
          - `full_name` string
          - `first_name` string
          - `last_name` string
          - `dob` string — ISO 8601 date of birth, e.g. 2018-10-17
          - `document_type` string
          - `document_id` string
          - `expiration_id_date` string, date — ISO 8601 date e.g. 2018-10-17
          - `nationality` string
          - `gender` 'F' | 'M' | 'O' — F - female, M - male, O - other
        - `affiliate_name` string — Name of the affiliate that originated the purchase. If none, leave blank.
      - `hotel_reservation_details` HotelReservationDetails
        - `pnr` string — Trip booking number, e.g. TR9088999
        - `hotel_itinerary` object[], required — Hotel itinerary data, one per segment
          - `hotel_name` string
          - `address` string
          - `hotel_city` string
          - `hotel_country` string
          - `start_date` string, date — ISO 8601 date e.g. 2018-10-17
          - `end_date` string, date — ISO 8601 date e.g. 2018-10-17
          - `number_of_rooms` integer
          - `class` string
        - `insurance` object[], required — Insurance data
          - `insurance_company` string
          - `insurance_type` string
          - `insurance_price` number
        - `passengers` object[], required — Passengers data
          - `full_name` string
          - `first_name` string
          - `last_name` string
          - `dob` string — ISO 8601 date of birth, e.g. 2018-10-17
          - `document_type` string
          - `document_id` string
          - `expiration_id_dt` string, date — ISO 8601 date e.g. 2018-10-17
          - `nationality` string
          - `gender` 'F' | 'M' | 'O' — F - female, M - male, O - other
        - `affiliate_name` string — Name of the affiliate that originated the purchase. If none, leave blank.
      - `insurance_details` InsuranceDetails
        - `policy_details` object, required — Information about insurance
          - `insurance_type` string, required — Insurance policy type
          - `insurance_start_dt` string, required — ISO 8601 start date, e.g. 2018-10-17
          - `insurance_end_dt` string, required — ISO 8601 end date, e.g. 2018-10-17
          - `insured_amount` string, required — Amount of insurance policy
          - `car_details` object — Required for car insurance
            - `manufacturer` string, required
            - `model` string, required
            - `year` string, required
          - `travel_details` object — Required for travel insurance
            - `departure_country` string, required
            - `arrival_country` string, required
          - `refundable` boolean — If insurance can be cancelled/refunded - true, otherwise - false
          - `provider_name` string
        - `client` object, required
          - `full_name` string
          - `first_name` string, required
          - `last_name` string, required
          - `dob` string — ISO 8601 date of birth, e.g. 2018-10-17
          - `document_type` string, required
          - `document_id` string
          - `expiration_id_dt` string, date — ISO 8601 date e.g. 2018-10-17
          - `nationality` string
          - `gender` string — F - female, M - male, O - other
        - `payment_history_simple` object
          - `unique_account_identifier` string — Unique name / number to identify the specific customer account
          - `paid_before_flag` boolean — Whether the customer has paid before or not
          - `date_of_last_paid_purchase` string, date, required — ISO 8601 date e.g. 2018-10-17
          - `date_of_first_paid_purchase` string, date, required — ISO 8601 date e.g. 2018-10-17
      - `payment_history_full` AttachmentPaymentHistoryFull
        - `unique_account_identifier` string — Unique name / number to identify the specific customer account
        - `payment_option` 'card' | 'direct banking' | 'cod' | 'other' — One of - card / direct banking / COD (cash) / other
        - `number_paid_purchases` number
        - `total_amount_paid_purchases` number
        - `date_of_last_paid_purchase` string, date — ISO 8601 date e.g. 2018-10-17
        - `date_of_first_paid_purchase` string, date — ISO 8601 date e.g. 2018-10-17
        - `count_paid_purchases_last_month` number
        - `amount_paid_purchases_last_month` number
        - `max_paid_amount_for_1purchase` number
      - `payment_history_simple` AttachmentPaymentHistorySimple
        - `unique_account_identifier` string — Unique name / number to identify the specific customer account
        - `paid_before_flag` boolean — Whether the customer has paid before or not
        - `date_of_last_paid_purchase` string, date — ISO 8601 date e.g. 2018-10-17
        - `date_of_first_paid_purchase` string, date — ISO 8601 date e.g. 2018-10-17
      - `flight_points_simple` FlightPointsSimple
        - `origin` object, required — Origin city and airport
          - `air_code` string, required — Origin IATA airport code, for example - JFK
          - `city_code` string, required — Origin city code, for example - NYC
        - `destination` object, required — Destination city and airport
          - `air_code` string, required — Destination IATA airport code, for example - LAX
          - `city_code` string, required — Destination city code, for example - LAX
      - `marketplaces` Marketplaces — Sellers' details within marketplaces.
        - `seller_id` string, required — Unique ID of the seller within your marketplace.
        - `seller_name` string, required — Name of the seller within your marketplace.
        - `seller_category` string, required — Category of the seller within your marketplace.
        - `seller_website` string, required — Website of the seller within your marketplace.
        - `seller_phone` string, required — Seller's phone number.
        - `seller_registration_date` string, date-time, required — Seller's registration date, in UTC, and displayed in ISO 8601 datetime format.
        - `seller_commercial_registration_number` string, required — Seller's commercial registration number.
      - `education_details` EducationDetails — Education-vertical risk signals for the current session.
        - `merchant_subtype` 'formal_education' | 'courses_training', required — Duplicated from onboarding config for self-check.
        - `program` object, required — Details of the education program being paid for.
          - `payment_tenure_months` integer, required — Total payment plan tenure in months.
          - `months_to_completion` integer, required — Months remaining until program completion / graduation.
        - `student_history` object, required — Student's payment history with the merchant.
          - `late_payments_count` integer, required — Total count of late payments by the student across history.
          - `avg_overdue_duration_days` number, required — Average overdue duration in days.
          - `observation_window_months` integer — Window over which history was calculated, to distinguish a new student's 0 late payments from a long-history clean student's 0.
    - `content_type` string, required — Version of used schema

## Other responses

- `400` — One of the required fields is missing or request is not formatted correctly.
- `401` — The request cannot be authorized.
- `404` — You are using an incorrect ID.
- `409` — Refund is unavailable.
- `500` — Something bad happened. We're notified.

---

[API](https://skmtc.dev/tabby/apis/tabby-api-reference.md) · [All operations](https://skmtc.dev/tabby/apis/tabby-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/tabby/tabby-api-reference/revisions/cff62a2a6ee9/schema)