Sign in

v1

latestOpenAPI 3.1.02026-07-131991131.4 KB
Payments

Update a payment

Updates the reference_id. You can only use this endpoint to update this 1 field. If you send other fields in the request, they will simply be ignored by tabby. The payment to be updated can have a status of AUTHORIZED or CLOSED.

put/api/v2/payments/{id}

Path parameters

idstring uuid required
Example:payment id, uuid format

ID of the payment.

Request body

Example request

{
  "order": {
    "reference_id": "1001_updated"
  }
}

Response

Success. Payment object is returned.

idstring uuid

Unique identifier for the payment (UUID), assigned by Tabby. Save it on your side!

created_atstring date-time

Date and time the payment was created, in UTC, and displayed in ISO 8601 datetime format.

expires_atstring 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_testboolean

Indicates whether this is a test payment (created using the Test API keys or Production API Keys).

amountstring 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' | 'KWD' required

ISO 4217 currency code for the payment amount. Currently there are 3 possible currency options - depending on the country where the store is located:

  • AED - United Arab Emirates Dirham
  • SAR - Saudi Riyal
  • KWD - Kuwaiti Dinar
descriptionstring nullable

Example response

{
  "id": "payment id, uuid format",
  "status": "CLOSED",
  "amount": "100",
  "currency": "AED",
  "description": "description",
  "buyer": {
    "name": "John Doe",
    "phone": "500000001",
    "dob": "2000-01-20"
  },
  "shipping_address": {
    "city": "Dubai",
    "address": "Dubai",
    "zip": "1111"
  },
  "order": {
    "reference_id": "1001_updated",
    "items": [
      {
        "reference_id": "SKU123",
        "title": "Name of the product",
        "description": "Description of the product",
        "quantity": 1,
        "unit_price": "0.00",
        "image_url": "https://example.com/",
        "product_url": "https://example.com/",
        "gender": "Kids",
        "category": "Clothes",
        "color": "white",
        "product_material": "cotton",
        "size_type": "EU",
        "size": "M",
        "brand": "Name of the Brand"
      }
    ]
  },
  "captures": [
    {
      "id": "capture id, uuid format",
      "amount": "100",
      "tax_amount": "0.00",
      "shipping_amount": "0.00",
      "discount_amount": "0.00",
      "items": [
        {
          "reference_id": "SKU123",
          "title": "Name of the product",
          "description": "Description of the product",
          "quantity": 1,
          "unit_price": "0.00",
          "image_url": "https://example.com/",
          "product_url": "https://example.com/",
          "gender": "Kids",
          "category": "Clothes",
          "color": "white",
          "product_material": "cotton",
          "size_type": "EU",
          "size": "M",
          "brand": "Name of the Brand"
        }
      ],
      "reference_id": "capture idempotency key"
    }
  ],
  "refunds": [
    {
      "id": "refund id, uuid format",
      "reason": "Reason for the refund",
      "items": [
        {
          "reference_id": "SKU123",
          "title": "Name of the product",
          "description": "Description of the product",
          "quantity": 1,
          "unit_price": "0.00",
          "image_url": "https://example.com/",
          "product_url": "https://example.com/",
          "gender": "Kids",
          "category": "Clothes",
          "color": "white",
          "product_material": "cotton",
          "size_type": "EU",
          "size": "M",
          "brand": "Name of the Brand"
        }
      ],
      "reference_id": "refund idempotency key"
    }
  ],
  "order_history": [
    {
      "amount": "100",
      "payment_method": "card",
      "buyer": {
        "name": "John Doe",
        "phone": "500000001",
        "dob": "2000-01-20"
      },
      "shipping_address": {
        "city": "Dubai",
        "address": "Dubai",
        "zip": "1111"
      },
      "items": [
        {
          "reference_id": "SKU123",
          "title": "Name of the product",
          "description": "Description of the product",
          "quantity": 1,
          "unit_price": "0.00",
          "image_url": "https://example.com/",
          "product_url": "https://example.com/",
          "gender": "Kids",
          "category": "Clothes",
          "color": "white",
          "product_material": "cotton",
          "size_type": "EU",
          "size": "M",
          "brand": "Name of the Brand"
        }
      ]
    }
  ],
  "meta": {
    "customer": "#customer-id",
    "order_id": "#1234"
  },
  "attachment": {
    "body": {
      "flight_reservation_details": {
        "pnr": "Trip booking number, e.g. TR9088999",
        "itinerary": [
          {
            "departure_city": "departure_city",
            "departure_country": "departure_country",
            "arrival_city": "arrival_city",
            "arrival_country": "arrival_country",
            "carrier": "carrier",
            "class": "class"
          }
        ],
        "insurance": [
          {
            "insurance_company": "insurance_company",
            "insurance_type": "insurance_type"
          }
        ],
        "passengers": [
          {
            "full_name": "full_name",
            "first_name": "first_name",
            "last_name": "last_name",
            "dob": "2018-10-17T00:00:00.000Z",
            "document_type": "document_type",
            "document_id": "document_id",
            "nationality": "nationality",
            "gender": "F"
          }
        ],
        "affiliate_name": "Name of the affiliate that originated the purchase. If none, leave blank."
      },
      "hotel_reservation_details": {
        "pnr": "TR9088999",
        "hotel_itinerary": [
          {
            "hotel_name": "hotel_name",
            "address": "address",
            "hotel_city": "hotel_city",
            "hotel_country": "hotel_country",
            "number_of_rooms": 1,
            "class": "class"
          }
        ],
        "insurance": [
          {
            "insurance_company": "insurance_company",
            "insurance_type": "insurance_type"
          }
        ],
        "passengers": [
          {
            "full_name": "full_name",
            "first_name": "first_name",
            "last_name": "last_name",
            "dob": "2018-10-17T00:00:00.000Z",
            "document_type": "document_type",
            "document_id": "document_id",
            "nationality": "nationality",
            "gender": "M"
          }
        ],
        "affiliate_name": "Name of the affiliate that originated the purchase. If none, leave blank."
      },
      "insurance_details": {
        "policy_details": {
          "insurance_type": "Insurance policy type",
          "insurance_start_dt": "2018-10-17T00:00:00.000Z",
          "insurance_end_dt": "2018-10-17T00:00:00.000Z",
          "insured_amount": "100",
          "car_details": {
            "manufacturer": "manufacturer",
            "model": "model",
            "year": "year"
          },
          "travel_details": {
            "departure_country": "departure_country",
            "arrival_country": "arrival_country"
          },
          "provider_name": "provider_name"
        },
        "client": {
          "full_name": "full_name",
          "first_name": "first_name",
          "last_name": "last_name",
          "dob": "2018-10-17T00:00:00.000Z",
          "document_type": "document_type",
          "document_id": "document_id",
          "nationality": "nationality",
          "gender": "F"
        },
        "payment_history_simple": {
          "unique_account_identifier": "unique name / id of the customer"
        }
      },
      "payment_history_full": {
        "unique_account_identifier": "unique name / id of the customer",
        "payment_option": "card",
        "number_paid_purchases": 1,
        "total_amount_paid_purchases": 1,
        "count_paid_purchases_last_month": 1,
        "amount_paid_purchases_last_month": 1,
        "max_paid_amount_for_1purchase": 1
      },
      "payment_history_simple": {
        "unique_account_identifier": "unique name / id of the customer"
      },
      "flight_points_simple": {
        "origin": {
          "air_code": "JFK",
          "city_code": "NYC"
        },
        "destination": {
          "air_code": "LAX",
          "city_code": "LAX"
        }
      },
      "marketplaces": {
        "seller_id": "57327813",
        "seller_name": "Pet Shop",
        "seller_category": "Electronics",
        "seller_website": "https://www.petshop.com",
        "seller_phone": "500000001",
        "seller_commercial_registration_number": "1012345678"
      },
      "education_details": {
        "merchant_subtype": "formal_education",
        "program": {
          "payment_tenure_months": 6,
          "months_to_completion": 9
        },
        "student_history": {
          "late_payments_count": 2,
          "avg_overdue_duration_days": 4.5,
          "observation_window_months": 12
        }
      }
    }
  }
}