API Playground
Payments
Webhooks
curl --request GET \
--url https://api.tabby.ai/api/v2/payments/{id} \
--header 'Authorization: Bearer <token>'{
"amount": "100",
"currency": "AED",
"buyer": {
"name": "John Doe",
"email": "[email protected]",
"phone": "500000001",
"dob": "2000-01-20"
},
"shipping_address": {
"city": "Dubai",
"address": "Dubai",
"zip": "1111"
},
"order": {
"reference_id": "1001",
"items": [
{
"title": "Name of the product",
"quantity": 1,
"unit_price": "0.00",
"category": "Clothes",
"reference_id": "SKU123",
"description": "Description of the product",
"image_url": "https://example.com/",
"product_url": "https://example.com/",
"gender": "Kids",
"color": "white",
"product_material": "cotton",
"size_type": "EU",
"size": "M",
"brand": "Name of the Brand",
"is_refundable": true
}
],
"updated_at": "2023-11-07T05:31:56Z",
"tax_amount": "0.00",
"shipping_amount": "0.00",
"discount_amount": "0.00"
},
"buyer_history": {
"registered_since": "2023-11-07T05:31:56Z",
"loyalty_level": 0,
"wishlist_count": 0,
"is_social_networks_connected": true,
"is_phone_number_verified": true,
"is_email_verified": true
},
"order_history": [
{
"purchased_at": "2023-11-07T05:31:56Z",
"amount": "100",
"status": "new",
"buyer": {
"name": "John Doe",
"email": "[email protected]",
"phone": "500000001",
"dob": "2000-01-20"
},
"shipping_address": {
"city": "Dubai",
"address": "Dubai",
"zip": "1111"
},
"payment_method": "card",
"items": [
{
"title": "Name of the product",
"quantity": 1,
"unit_price": "0.00",
"category": "Clothes",
"reference_id": "SKU123",
"description": "Description of the product",
"image_url": "https://example.com/",
"product_url": "https://example.com/",
"gender": "Kids",
"color": "white",
"product_material": "cotton",
"size_type": "EU",
"size": "M",
"brand": "Name of the Brand",
"is_refundable": true,
"ordered": 0,
"captured": 0,
"shipped": 0,
"refunded": 0
}
]
}
],
"id": "payment id, uuid format",
"created_at": "2023-11-07T05:31:56Z",
"expires_at": "2023-11-07T05:31:56Z",
"status": "CLOSED",
"is_test": true,
"description": "description",
"captures": [
{
"amount": "100",
"reference_id": "capture idempotency key",
"id": "capture id, uuid format",
"created_at": "2023-11-07T05:31:56Z",
"tax_amount": "0.00",
"shipping_amount": "0.00",
"discount_amount": "0.00",
"items": [
{
"title": "Name of the product",
"quantity": 1,
"unit_price": "0.00",
"category": "Clothes",
"reference_id": "SKU123",
"description": "Description of the product",
"image_url": "https://example.com/",
"product_url": "https://example.com/",
"gender": "Kids",
"color": "white",
"product_material": "cotton",
"size_type": "EU",
"size": "M",
"brand": "Name of the Brand",
"is_refundable": true
}
]
}
],
"refunds": [
{
"amount": "0.00",
"reference_id": "refund idempotency key",
"id": "refund id, uuid format",
"created_at": "2023-11-07T05:31:56Z",
"reason": "Reason for the refund",
"items": [
{
"title": "Name of the product",
"quantity": 1,
"unit_price": "0.00",
"category": "Clothes",
"reference_id": "SKU123",
"description": "Description of the product",
"image_url": "https://example.com/",
"product_url": "https://example.com/",
"gender": "Kids",
"color": "white",
"product_material": "cotton",
"size_type": "EU",
"size": "M",
"brand": "Name of the Brand",
"is_refundable": true
}
]
}
],
"meta": {
"customer": "#customer-id",
"order_id": "#1234"
},
"attachment": {
"body": "{\"flight_reservation_details\": {\"pnr\": \"TR9088999\",\"itinerary\": [...],\"insurance\": [...],\"passengers\": [...],\"affiliate_name\": \"some affiliate\"}}",
"content_type": "application/vnd.tabby.v1+json"
}
}Retrieve a payment
Retrieves the specified payment. Returns the entire payment object, including the payment Status, Captures and Refunds objects.
curl --request GET \
--url https://api.tabby.ai/api/v2/payments/{id} \
--header 'Authorization: Bearer <token>'{
"amount": "100",
"currency": "AED",
"buyer": {
"name": "John Doe",
"email": "[email protected]",
"phone": "500000001",
"dob": "2000-01-20"
},
"shipping_address": {
"city": "Dubai",
"address": "Dubai",
"zip": "1111"
},
"order": {
"reference_id": "1001",
"items": [
{
"title": "Name of the product",
"quantity": 1,
"unit_price": "0.00",
"category": "Clothes",
"reference_id": "SKU123",
"description": "Description of the product",
"image_url": "https://example.com/",
"product_url": "https://example.com/",
"gender": "Kids",
"color": "white",
"product_material": "cotton",
"size_type": "EU",
"size": "M",
"brand": "Name of the Brand",
"is_refundable": true
}
],
"updated_at": "2023-11-07T05:31:56Z",
"tax_amount": "0.00",
"shipping_amount": "0.00",
"discount_amount": "0.00"
},
"buyer_history": {
"registered_since": "2023-11-07T05:31:56Z",
"loyalty_level": 0,
"wishlist_count": 0,
"is_social_networks_connected": true,
"is_phone_number_verified": true,
"is_email_verified": true
},
"order_history": [
{
"purchased_at": "2023-11-07T05:31:56Z",
"amount": "100",
"status": "new",
"buyer": {
"name": "John Doe",
"email": "[email protected]",
"phone": "500000001",
"dob": "2000-01-20"
},
"shipping_address": {
"city": "Dubai",
"address": "Dubai",
"zip": "1111"
},
"payment_method": "card",
"items": [
{
"title": "Name of the product",
"quantity": 1,
"unit_price": "0.00",
"category": "Clothes",
"reference_id": "SKU123",
"description": "Description of the product",
"image_url": "https://example.com/",
"product_url": "https://example.com/",
"gender": "Kids",
"color": "white",
"product_material": "cotton",
"size_type": "EU",
"size": "M",
"brand": "Name of the Brand",
"is_refundable": true,
"ordered": 0,
"captured": 0,
"shipped": 0,
"refunded": 0
}
]
}
],
"id": "payment id, uuid format",
"created_at": "2023-11-07T05:31:56Z",
"expires_at": "2023-11-07T05:31:56Z",
"status": "CLOSED",
"is_test": true,
"description": "description",
"captures": [
{
"amount": "100",
"reference_id": "capture idempotency key",
"id": "capture id, uuid format",
"created_at": "2023-11-07T05:31:56Z",
"tax_amount": "0.00",
"shipping_amount": "0.00",
"discount_amount": "0.00",
"items": [
{
"title": "Name of the product",
"quantity": 1,
"unit_price": "0.00",
"category": "Clothes",
"reference_id": "SKU123",
"description": "Description of the product",
"image_url": "https://example.com/",
"product_url": "https://example.com/",
"gender": "Kids",
"color": "white",
"product_material": "cotton",
"size_type": "EU",
"size": "M",
"brand": "Name of the Brand",
"is_refundable": true
}
]
}
],
"refunds": [
{
"amount": "0.00",
"reference_id": "refund idempotency key",
"id": "refund id, uuid format",
"created_at": "2023-11-07T05:31:56Z",
"reason": "Reason for the refund",
"items": [
{
"title": "Name of the product",
"quantity": 1,
"unit_price": "0.00",
"category": "Clothes",
"reference_id": "SKU123",
"description": "Description of the product",
"image_url": "https://example.com/",
"product_url": "https://example.com/",
"gender": "Kids",
"color": "white",
"product_material": "cotton",
"size_type": "EU",
"size": "M",
"brand": "Name of the Brand",
"is_refundable": true
}
]
}
],
"meta": {
"customer": "#customer-id",
"order_id": "#1234"
},
"attachment": {
"body": "{\"flight_reservation_details\": {\"pnr\": \"TR9088999\",\"itinerary\": [...],\"insurance\": [...],\"passengers\": [...],\"affiliate_name\": \"some affiliate\"}}",
"content_type": "application/vnd.tabby.v1+json"
}
}Authorizations
Bearer authentication header of the form Bearer <secret_key>, where <secret_key> is your secret_key.
Path Parameters
ID of the payment.
"payment id, uuid format"
Response
Success. Payment object is returned.
Payment object.
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.
"100"
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 DirhamSAR- Saudi RiyalKWD- Kuwaiti Dinar
AED, SAR, KWD "AED"
Customer information
Show child attributes
Show child attributes
Customer’s full name.
"John Doe"
Customer’s email address.
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.
"500000001"
Customer's date of birth; format is YYYY-MM-DD.
"2000-01-20"
Show child attributes
Show child attributes
Merchant-assigned order number.
"1001"
Array of objects representing the order items in this payment.
Show child attributes
Show child attributes
Name of the product.
"Name of the product"
Quantity of the product ordered.
x >= 01
Price per unit of the product. Should be positive or zero.
"0.00"
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.
"Clothes"
Merchant’s product identifier. Displayed in Customer's App and Merchant Dashboard, used for Item refunds and disputes.
"SKU123"
Description of the product.
"Description of the product"
URL of the item image to show in the order information.
"https://example.com/"
URL of the item at your store.
"https://example.com/"
Who the goods are designed to.
Male, Female, Kids, Other "Kids"
white / blue/ green
"white"
cotton / polyester / synthetic
"cotton"
EU / UK
"EU"
L / XL / 12
"M"
Mango / Dorothy Perkins / Tommy Hilfiger
"Name of the Brand"
Indicates whether a product can be returned
Date and time the order was last updated, in UTC, and displayed in ISO 8601 datetime format.
Total tax for the order.
"0.00"
Total shipping cost for the order.
"0.00"
Total discount for the order. Should be positive or zero. Shows up on Tabby App for the Customer's convenience.
"0.00"
Customer information. registered_since (as a date of the customer's registration in the App), loyalty_level (as a number of successful orders) and wishlist_count (paid amount by a customer previously, e.g. 500) must be sent for Monthly Billing. is_social_networks_connected is also required for Monthly Billing.
Show child attributes
Show child attributes
Date and time the customer got registred with you, in UTC, and displayed in ISO 8601 datetime format.
Customer's loyalty level within your store, should be sent as a number of successfully placed orders in the store with any payment methods.
Number of items in Customer's wishlist.
x >= 0Is social network connected
Is phone number verified
Is email verified
Array of objects, should contain information on 5-10 previously placed via any payment method orders in any status, current order excluded.
Show child attributes
Show child attributes
Date and time the order was placed, in UTC, and displayed in ISO 8601 datetime format.
Total payment amount, including tax, shipping, and excluding any discounts. Allows to send up to 2 decimals for AED and SAR, up to 3 decimals for KWD.
"100"
Status of the order.
new, processing, complete, refunded, canceled, unknown Customer information
Show child attributes
Show child attributes
Customer’s full name.
"John Doe"
Customer’s email address.
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.
"500000001"
Customer's date of birth; format is YYYY-MM-DD.
"2000-01-20"
Show child attributes
Show child attributes
Name of city, municipality, or village.
"Dubai"
Building name, apartment number.
"Dubai"
Postal code.
"1111"
Payment method used.
card, cod "card"
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.
Show child attributes
Show child attributes
Name of the product.
"Name of the product"
Quantity of the product ordered.
x >= 01
Price per unit of the product. Should be positive or zero.
"0.00"
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.
"Clothes"
Merchant’s product identifier. Displayed in Customer's App and Merchant Dashboard, used for Item refunds and disputes.
"SKU123"
Description of the product.
"Description of the product"
URL of the item image to show in the order information.
"https://example.com/"
URL of the item at your store.
"https://example.com/"
Who the goods are designed to.
Male, Female, Kids, Other "Kids"
white / blue/ green
"white"
cotton / polyester / synthetic
"cotton"
EU / UK
"EU"
L / XL / 12
"M"
Mango / Dorothy Perkins / Tommy Hilfiger
"Name of the Brand"
Indicates whether a product can be returned
Quantity of SKUs in the order without a final status yet.
Quantity of captured SKUs in the order (paid by customer).
Quantity of SKUs in the order shipped to the customer.
Quantity of SKUs in the order refunded to the customer.
Unique identifier for the payment (UUID), assigned by Tabby. Save it on your side!
"payment id, uuid format"
Date and time the payment was created, in UTC, and displayed in ISO 8601 datetime format.
Date and time the payment expires, in UTC, and displayed in ISO 8601 datetime format.
Status of the current payment:
CREATEDmeans that the payment is created successfully, but not finished yet;AUTHORIZEDandCLOSEDmark the successfully approved and captured payments accordingly;REJECTEDis returned when a customer is rejected during Tabby Checkout;EXPIREDis used when a customer cancels a payment or when Tabby doesn't receive a successfully paid transaction after timeout.
CREATED, AUTHORIZED, CLOSED, REJECTED, EXPIRED "CLOSED"
Indicates whether this is a test payment (created using the Test API keys or Production API Keys).
"description"
Show child attributes
Show child attributes
Total payment amount captured, including tax, shipping, and excluding any discounts. Allows to send up to 2 decimals for AED and SAR, up to 3 decimals for KWD.
"100"
Idempotency key. Used to avoid similar capture requests.
"capture idempotency key"
Unique capture ID, assigned by Tabby.
"capture id, uuid format"
Date and time the capture was created, in UTC, and displayed in ISO 8601 datetime format, assigned by Tabby.
Tax amount captured.
"0.00"
Shipping cost captured.
"0.00"
Total discount for the order. Should be positive or zero.
"0.00"
Array of objects representing the order items being captured.
Show child attributes
Show child attributes
Name of the product.
"Name of the product"
Quantity of the product ordered.
x >= 01
Price per unit of the product. Should be positive or zero.
"0.00"
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.
"Clothes"
Merchant’s product identifier. Displayed in Customer's App and Merchant Dashboard, used for Item refunds and disputes.
"SKU123"
Description of the product.
"Description of the product"
URL of the item image to show in the order information.
"https://example.com/"
URL of the item at your store.
"https://example.com/"
Who the goods are designed to.
Male, Female, Kids, Other "Kids"
white / blue/ green
"white"
cotton / polyester / synthetic
"cotton"
EU / UK
"EU"
L / XL / 12
"M"
Mango / Dorothy Perkins / Tommy Hilfiger
"Name of the Brand"
Indicates whether a product can be returned
Show child attributes
Show child attributes
Amount refunded. Allows to send up to 2 decimals for AED and SAR, up to 3 decimals for KWD.
Idempotency key. Used to avoid similar refund requests.
"refund idempotency key"
Unique refund ID, assigned by Tabby.
"refund id, uuid format"
Date and time the refund was created, in UTC, and displayed in ISO 8601 datetime format, assigned by Tabby.
Reason for the refund.
"Reason for the refund"
Array of objects representing the order items being refunded.
Show child attributes
Show child attributes
Name of the product.
"Name of the product"
Quantity of the product ordered.
x >= 01
Price per unit of the product. Should be positive or zero.
"0.00"
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.
"Clothes"
Merchant’s product identifier. Displayed in Customer's App and Merchant Dashboard, used for Item refunds and disputes.
"SKU123"
Description of the product.
"Description of the product"
URL of the item image to show in the order information.
"https://example.com/"
URL of the item at your store.
"https://example.com/"
Who the goods are designed to.
Male, Female, Kids, Other "Kids"
white / blue/ green
"white"
cotton / polyester / synthetic
"cotton"
EU / UK
"EU"
L / XL / 12
"M"
Mango / Dorothy Perkins / Tommy Hilfiger
"Name of the Brand"
Indicates whether a product can be returned
Extra data (booking info, insurance, flight reservations, ...) as serialized JSON
Show child attributes
Show child attributes
Should be an object containing any of the keys with corresponded sub objects
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Itinerary data, one per segment
Show child attributes
Show child attributes
"departure_city"
"departure_country"
"arrival_city"
"arrival_country"
"carrier"
RFC3339 e.g. 2018-10-17T07:26:33Z
"class"
true - if ticket can be cancelled/refunded
Insurance data
Show child attributes
Show child attributes
"insurance_company"
"insurance_type"
"insurance_price"
Passengers data
Show child attributes
Show child attributes
"full_name"
"first_name"
"last_name"
ISO 8601 date of birth, e.g. 2018-10-17
"2018-10-17T00:00:00.000Z"
"document_type"
"document_id"
ISO 8601 date e.g. 2018-10-17
"nationality"
F - female, M - male, O - other
F, M, O "F"
Trip booking number, e.g. TR9088999
"Trip booking number, e.g. TR9088999"
Name of the affiliate that originated the purchase. If none, leave blank.
"Name of the affiliate that originated the purchase. If none, leave blank."
Show child attributes
Show child attributes
Hotel itinerary data, one per segment
Show child attributes
Show child attributes
"hotel_name"
"address"
"hotel_city"
"hotel_country"
ISO 8601 date e.g. 2018-10-17
ISO 8601 date e.g. 2018-10-17
1
"class"
Insurance data
Show child attributes
Show child attributes
Passengers data
Show child attributes
Show child attributes
"full_name"
"first_name"
"last_name"
ISO 8601 date of birth, e.g. 2018-10-17
"2018-10-17T00:00:00.000Z"
"document_type"
"document_id"
ISO 8601 date e.g. 2018-10-17
"nationality"
F - female, M - male, O - other
F, M, O "M"
Trip booking number, e.g. TR9088999
"TR9088999"
Name of the affiliate that originated the purchase. If none, leave blank.
"Name of the affiliate that originated the purchase. If none, leave blank."
Show child attributes
Show child attributes
Information about insurance
Show child attributes
Show child attributes
Insurance policy type
"Insurance policy type"
ISO 8601 start date, e.g. 2018-10-17
"2018-10-17T00:00:00.000Z"
ISO 8601 end date, e.g. 2018-10-17
"2018-10-17T00:00:00.000Z"
Amount of insurance policy
"100"
Required for car insurance
Show child attributes
Show child attributes
"manufacturer"
"model"
"year"
If insurance can be cancelled/refunded - true, otherwise - false
"provider_name"
Show child attributes
Show child attributes
"first_name"
"last_name"
"document_type"
"full_name"
ISO 8601 date of birth, e.g. 2018-10-17
"2018-10-17T00:00:00.000Z"
"document_id"
ISO 8601 date e.g. 2018-10-17
"nationality"
F - female, M - male, O - other
"F"
Show child attributes
Show child attributes
ISO 8601 date e.g. 2018-10-17
ISO 8601 date e.g. 2018-10-17
Unique name / number to identify the specific customer account
"unique name / id of the customer"
Whether the customer has paid before or not
Show child attributes
Show child attributes
Unique name / number to identify the specific customer account
"unique name / id of the customer"
One of - card / direct banking / COD (cash) / other
card, direct banking, cod, other "card"
1
1
ISO 8601 date e.g. 2018-10-17
ISO 8601 date e.g. 2018-10-17
1
1
1
Show child attributes
Show child attributes
Unique name / number to identify the specific customer account
"unique name / id of the customer"
Whether the customer has paid before or not
ISO 8601 date e.g. 2018-10-17
ISO 8601 date e.g. 2018-10-17
Show child attributes
Show child attributes
Destination city and airport
Sellers' details within marketplaces.
Show child attributes
Show child attributes
Unique ID of the seller within your marketplace.
"57327813"
Name of the seller within your marketplace.
"Pet Shop"
Category of the seller within your marketplace.
"Electronics"
Website of the seller within your marketplace.
"https://www.petshop.com"
Seller's phone number.
"500000001"
Seller's registration date, in UTC, and displayed in ISO 8601 datetime format.
Seller's commercial registration number.
"1012345678"
"{\"flight_reservation_details\": {\"pnr\": \"TR9088999\",\"itinerary\": [...],\"insurance\": [...],\"passengers\": [...],\"affiliate_name\": \"some affiliate\"}}"
Version of used schema
Was this page helpful?