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

# Close a payment

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

Closed is the final status of the payment. Your payment is going to be closed automatically if you capture the full amount of the payment. If an order is fully cancelled, please close the payment without capturing it - the customer will be refunded for all paid amount. If only a part of the order is delivered, please capture this part and close the payment – it will mean that another part of the order is not going to be delivered to the customer.

## Path parameters

- `id` string, uuid, required

## Response `200`

Success. Payment object is returned.

- PaymentClose — 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[], nullable
    - `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` object[], nullable
  - `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.
- `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)