Register, list, retrieve, update, and remove Tabby webhook endpoints scoped to a merchant_code. Tabby fires authorize, capture, close, reject, expire, refund, and update events as JSON POSTs to your HTTPS endpoint with optional arbitrary auth-header signing. Failed deliveries retry with exponential backoff (1m timeout, up to 4 retries at 1-4 minute intervals).
openapi: 3.1.0
info:
title: Tabby API Reference
version: 1.0.0
x-logo:
url: assets/tabby-new.png
altText: tabby Logo
description: |
Tabby Documentation: **[docs.tabby.ai](https://docs.tabby.ai/)**
servers:
- url: https://api.tabby.ai/
description: Production (UAE, Kuwait)
- url: https://api.tabby.sa/
description: Production (KSA)
tags:
- name: Checkout
description: >-
Checkout is a whole process of customer data collection and payment
authorization.
- name: Payments
description: >-
The core of tabby is a payments flow enabling you to handle payments at
your webstore.
- name: Webhooks
description: Manage webhook endpoints.
- name: Disputes
description: >-
The Disputes API is designed to simplify the process of handling disputes
and help merchants resolve issues with customer orders more efficiently.
Merchants can use this API to retrieve a list of disputes, view details
about a specific dispute, and approve or challenge a bunch of disputes. It
mirrors the functionality available in Tabby Merchant Dashboard and
operates exclusively with live payments using live credentials. A secret
key is required for using the Disputes API. <SchemaDefinition
schemaRef="#/components/schemas/Webhook" />
paths:
/api/v2/checkout:
post:
tags:
- Checkout
summary: Create a session
description: >-
Creates a Checkout session. Creates Session and Payment, returns
Pre-Scoring result (status), ids of Payment and Session.
operationId: postCheckoutSession
security:
- bearerAuth:
- secret_key
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
payment:
$ref: '#/components/schemas/CheckoutCreation'
lang:
$ref: '#/components/schemas/LanguageCode'
merchant_code:
type: string
example: code provided to you from Tabby side
description: >-
Please contact your integration manager to get the merchant
code.
merchant_urls:
$ref: '#/components/schemas/MerchantUrls'
token:
type: string
default: null
description: >
If you already have `token`, you can pass it there.
Authorization header still requires Secret Key.
required:
- payment
- lang
- merchant_code
responses:
'200':
$ref: '#/components/responses/CheckoutSession'
'400':
$ref: '#/components/responses/BadRequestError_CheckoutPost'
'401':
$ref: '#/components/responses/AuthenticationError_CheckoutPost'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/UnexpectedError'
/api/v2/checkout/{id}:
get:
tags:
- Checkout
summary: Retrieve an existing checkout session
description: >-
Use this API to retrieve the token (only if tokens used in your
integration )
operationId: getCheckoutSession
security:
- bearerAuth:
- secret_key
parameters:
- $ref: '#/components/parameters/sessionIdParam'
responses:
'200':
$ref: '#/components/responses/CheckoutSession'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/AuthenticationError_key_doesnt_exist'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/UnexpectedError'
/api/v2/payments/{id}:
get:
tags:
- Payments
summary: Retrieve a payment
description: >-
Retrieves the specified payment. Returns the entire payment object,
including the payment Status, Captures and Refunds objects.
operationId: getPayment
security:
- bearerAuth:
- secret_key
parameters:
- $ref: '#/components/parameters/paymentIdParam'
responses:
'200':
$ref: '#/components/responses/PaymentResponse'
'400':
$ref: '#/components/responses/BadRequestError_PaymentsGet'
'401':
$ref: '#/components/responses/AuthenticationError_PaymentsGet'
'404':
$ref: '#/components/responses/NotFoundError_no_such_payment'
'500':
$ref: '#/components/responses/UnexpectedError'
put:
tags:
- Payments
summary: Update a payment
description: >-
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.
operationId: putPayment
security:
- bearerAuth:
- secret_key
parameters:
- $ref: '#/components/parameters/paymentIdParam'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
order:
type: object
properties:
reference_id:
type: string
description: Merchant-assigned order or cart ID.
example: 1001_updated
responses:
'200':
$ref: '#/components/responses/PaymentUpdate'
'400':
$ref: '#/components/responses/BadRequestError_PaymentsGet'
'401':
$ref: '#/components/responses/AuthenticationError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError_no_such_payment'
'500':
$ref: '#/components/responses/UnexpectedError'
/api/v2/payments/{id}/captures:
post:
tags:
- Payments
summary: Capture a payment
description: >-
Send a Capture requests for Authorized payments only. If you capture the
full payment amount, the payment will be automatically closed with full
capture. If you capture partial amount, the payment will remain
Authorized until the rest of the amount is captured or Close request
sent.
operationId: postPaymentCapture
security:
- bearerAuth:
- secret_key
parameters:
- $ref: '#/components/parameters/paymentIdParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CaptureRequest'
responses:
'200':
$ref: '#/components/responses/PaymentCaptureResponse'
'400':
$ref: '#/components/responses/BadRequestError_PaymentsCapture'
'401':
$ref: '#/components/responses/AuthenticationError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError_no_such_payment'
'500':
$ref: '#/components/responses/UnexpectedError'
/api/v2/payments/{id}/refunds:
post:
tags:
- Payments
summary: Refund a payment
description: >-
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.
operationId: postPaymentRefund
security:
- bearerAuth:
- secret_key
parameters:
- $ref: '#/components/parameters/paymentIdParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RefundRequest'
responses:
'200':
$ref: '#/components/responses/PaymentRefundResponse'
'400':
$ref: '#/components/responses/BadRequestError_PaymentsRefund'
'401':
$ref: '#/components/responses/AuthenticationError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError_no_such_payment'
'409':
$ref: '#/components/responses/PaymentRefundError'
'500':
$ref: '#/components/responses/UnexpectedError'
/api/v2/payments/{id}/close:
post:
tags:
- Payments
summary: Close a payment
description: >-
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.
operationId: closePayment
security:
- bearerAuth:
- secret_key
parameters:
- $ref: '#/components/parameters/paymentIdParam'
responses:
'200':
$ref: '#/components/responses/PaymentClose'
'400':
$ref: '#/components/responses/BadRequestError_PaymentsClose'
'401':
$ref: '#/components/responses/AuthenticationError'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError_no_such_payment'
'500':
$ref: '#/components/responses/UnexpectedError'
/api/v2/payments:
get:
tags:
- Payments
summary: List of all payments
description: >-
Returns a list of success payments (`AUTHORIZED` or `CLOSED`) you’ve
previously created. The payments are returned in sorted order, with the
most recent payments appearing first. Each entry in the array is a
separate payments object, including the status, any captures and any
refunds. If no more payments are available, the resulting array will be
empty. Payments might be filtered by creation date.
operationId: getPayments
security:
- bearerAuth:
- secret_key
parameters:
- in: query
name: created_at__gte
schema:
type: string
format: date
description: >-
This is a filter for the payment creation date, use it to get the
list of payments where creation date >= created_at__gte. ISO 8601
date time format (greater than or equal to). No time should be
provided, it starts at 00:00:00 be default. For example 2020-01-23
-> 2020-01-23T00:00:00Z.
- in: query
name: created_at__lte
schema:
type: string
format: date-time
description: >-
This is a filter for the payment creation date, use it to get the
list of payments where creation date <= created_at__lte. ISO 8601
date time format (less than or equal to). No time should be
provided, it starts at 00:00:00 be default. For example 2020-01-23
-> 2020-01-23T00:00:00Z.
- in: query
name: limit
schema:
type: integer
maximum: 20
description: Limits the number of returned results.
- in: query
name: status
schema:
type: string
enum:
- authorized
- closed
- rejected
- new
- captured
- refunded
- cancelled
example: authorized
description: |
Filter the orders by specific statuses:
- `authorized`, `closed` and `rejected` belong to the API payment statuses;
- `new`, `captured`, `refunded` and `cancelled`` refer to the statuses on Tabby Merchant Dashboard;
- If absent, all `AUTHORIZED` and `CLOSED` payments are returned.
- in: query
name: offset
schema:
type: integer
description: >-
The number of records into a dataset that you want to start, indexed
at 0.
responses:
'200':
$ref: '#/components/responses/Payments'
'400':
$ref: '#/components/responses/BadRequestError_failed'
'401':
$ref: '#/components/responses/AuthenticationError'
'500':
$ref: '#/components/responses/UnexpectedError'
/api/v1/webhooks:
post:
tags:
- Webhooks
summary: Register a webhook
description: Creates a new webhook
operationId: postWebhook
security:
- bearerAuth:
- secret_key
parameters:
- $ref: '#/components/parameters/merchantCodeParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookRegistration'
responses:
'200':
$ref: '#/components/responses/WebhookRegistration'
'400':
$ref: '#/components/responses/BadRequestError_bad_request'
'401':
$ref: '#/components/responses/AuthenticationError_authorization'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/UnexpectedError'
get:
tags:
- Webhooks
summary: Retrieve all webhooks
description: Retrieves all registred webhooks.
operationId: getWebhooks
security:
- bearerAuth:
- secret_key
parameters:
- $ref: '#/components/parameters/merchantCodeParam'
responses:
'200':
$ref: '#/components/responses/WebhookAll'
'401':
$ref: '#/components/responses/AuthenticationError_authorization'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/UnexpectedError'
/api/v1/webhooks/{id}:
get:
tags:
- Webhooks
summary: Retrieve a webhook
description: Retrieves the specified webhook.
operationId: getWebhook
security:
- bearerAuth:
- secret_key
parameters:
- $ref: '#/components/parameters/webhookIdParam'
- $ref: '#/components/parameters/merchantCodeParam'
responses:
'200':
$ref: '#/components/responses/Webhook'
'401':
$ref: '#/components/responses/AuthenticationError_invalid_secret_key'
'404':
$ref: '#/components/responses/NotFoundError_no_such_webhook'
'500':
$ref: '#/components/responses/UnexpectedError'
put:
tags:
- Webhooks
summary: Update a webhook
description: Updates the specified webhook.
operationId: putWebhook
security:
- bearerAuth:
- secret_key
parameters:
- $ref: '#/components/parameters/webhookIdParam'
- $ref: '#/components/parameters/merchantCodeParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WebhookUpdate'
responses:
'200':
$ref: '#/components/responses/WebhookUpdate'
'400':
$ref: '#/components/responses/BadRequestError_bad_request'
'401':
$ref: '#/components/responses/AuthenticationError_authorization'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/NotFoundError_no_such_webhook'
'500':
$ref: '#/components/responses/UnexpectedError'
delete:
tags:
- Webhooks
summary: Remove a webhook
description: Removes the specified webhook.
operationId: deleteWebhook
security:
- bearerAuth:
- secret_key
parameters:
- $ref: '#/components/parameters/webhookIdParam'
- $ref: '#/components/parameters/merchantCodeParam'
responses:
'200':
$ref: '#/components/responses/WebhookDelete'
'401':
$ref: '#/components/responses/AuthenticationError_invalid_secret_key'
'404':
$ref: '#/components/responses/NotFoundError_no_such_webhook'
'500':
$ref: '#/components/responses/UnexpectedError'
/api/v1/disputes:
get:
tags:
- Disputes
summary: Get disputes list
description: Returns list of 100 recently created disputes.
operationId: getDisputes
security:
- bearerAuth:
- secret_key
parameters:
- in: query
name: statuses
schema:
type: array
items:
type: string
description: DisputeStatus
enum:
- new
- declined
- cancelled
- refunded
- in_progress
- evidence_merchant
- evidence_customer
example: statuses=new&statuses=declined
description: Dispute status. If not set, then all statuses will be in result.
- in: query
name: created_at_gte
schema:
type: string
example: created_at_gte=2022-12-01T00:00:00Z
description: Filter disputes created after or at the specified date and time.
- in: query
name: created_at_lte
schema:
type: string
example: created_at_lte=2022-12-01T00:00:00Z
description: Filter disputes created before or at the specified date and time.
- in: query
name: page_token
schema:
type: string
description: >-
To load the next page of disputed items provide page token. This
code can be obtained from the `next_page_token` variable in the
response of dispute list. If `next_page_token` is empty in response,
it means last page of disputes has been reached.
responses:
'200':
$ref: '#/components/responses/Disputes'
'400':
$ref: '#/components/responses/BadRequestError_bad_request'
'401':
$ref: '#/components/responses/AuthenticationError_invalid_secret_key'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/UnexpectedError'
/api/v1/disputes/{disputeId}:
get:
tags:
- Disputes
summary: Get dispute by id
description: Returns detailed information about dispute.
operationId: getDispute
security:
- bearerAuth:
- secret_key
parameters:
- $ref: '#/components/parameters/disputeIdParam'
responses:
'200':
$ref: '#/components/responses/Dispute'
'400':
$ref: '#/components/responses/BadRequestError_bad_request'
'401':
$ref: '#/components/responses/AuthenticationError_invalid_secret_key'
'404':
$ref: '#/components/responses/NotFoundError_Disputes'
'500':
$ref: '#/components/responses/UnexpectedError'
/api/v1/disputes/{disputeId}/provide-evidence:
post:
tags:
- Disputes
summary: Provide evidence for a dispute
description: >-
Provide evidence (text and/or attachments) for a dispute. Used by the
merchant to submit proof in response to an evidence request.
operationId: postDisputeProvideEvidence
security:
- bearerAuth:
- secret_key
parameters:
- $ref: '#/components/parameters/disputeIdParam'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
content:
type: string
example: >-
I am providing a photo of the damaged product that was
received
description: Text content of the evidence being provided.
attachment_ids:
type: array
items:
type: string
format: uuid
example: attachment id, uuid format
description: >-
Array of attachment IDs to include as evidence. IDs can be
received via `upload attachment` endpoint.
required:
- content
responses:
'200':
$ref: '#/components/responses/DisputeProvideEvidence'
'400':
$ref: '#/components/responses/BadRequestError_bad_request'
'401':
$ref: '#/components/responses/AuthenticationError_invalid_secret_key'
'404':
$ref: '#/components/responses/NotFoundError_Disputes'
'409':
$ref: '#/components/responses/DisputeProvideEvidenceConflict'
'500':
$ref: '#/components/responses/UnexpectedError'
/api/v1/disputes/approve:
post:
tags:
- Disputes
summary: Approve disputes
description: >-
Approve disputes (refund money to the customer). Only 20 disputes can be
approved within a single request.
operationId: postDisputesApprove
security:
- bearerAuth:
- secret_key
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
dispute_ids:
type: array
items:
type: string
format: uuid
example: dispute id, uuid format
description: >-
Array of dispute ids. Only 20 disputes can be approved
within a single request.
required:
- dispute_ids
responses:
'200':
$ref: '#/components/responses/DisputesApprove'
'400':
$ref: '#/components/responses/BadRequestError_bad_request'
'401':
$ref: '#/components/responses/AuthenticationError_invalid_secret_key'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/UnexpectedError'
/api/v1/disputes/challenge:
post:
tags:
- Disputes
summary: Challenge disputes
description: >-
Challenge disputes (request Tabby support to take a look at the case).
Only 20 disputes can be challenged within a single request. Only
disputes with status 'new' might be challenged.
operationId: postDisputesChallenge
security:
- bearerAuth:
- secret_key
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
dispute_id:
type: string
example: uuid
description: ID of the dispute
description:
type: string
example: Comment for Tabby support
description: Comment for Tabby support.
reason:
type: string
enum:
- merchant_reason_other
- merchant_reason_order_on_its_way
- merchant_reason_order_has_been_already_delivered
- merchant_reason_order_amount_should_be_different
- merchant_reason_problem_with_delivery
example: merchant_reason_other
description: |
Reason for requesting dispute challenge:
- `merchant_reason_other` - there were other problems with the order that required further clarification;
- `merchant_reason_order_on_its_way` - the order has been confirmed and is in the process of being delivered;
- `merchant_reason_order_has_been_already_delivered` - the order has already been delivered and is complete;
- `merchant_reason_order_amount_should_be_different` - there was a problem with the amount of the order and it needed to be changed;
- `merchant_reason_problem_with_delivery` - there was a problem with the order during delivery that needed to be adjusted and resolved.
amount:
type: string
example: '100'
description: >-
If the dispute challenged with reason
`merchant_reason_order_amount_should_be_different` - a new
disputed amount is required.
attachment_ids:
type: array
items:
type: string
format: uuid
example: attachment id, uuid format
description: >-
Attachment ID that will be attached. ID can be received via
`upload attachment` endpoint.
required:
- dispute_id
- description
- reason
responses:
'200':
$ref: '#/components/responses/DisputesChallenge'
'400':
$ref: '#/components/responses/BadRequestError_bad_request'
'401':
$ref: '#/components/responses/AuthenticationError_invalid_secret_key'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/UnexpectedError'
/api/v1/disputes/attachments/upload:
post:
tags:
- Disputes
summary: Upload attachment
description: >-
Upload an attachment. Attachment must be in PNG, JPEG or PDF format and
can be up to 5 megabytes in size. Files larger than 5 MB are rejected.
operationId: postUploadAttachment
security:
- bearerAuth:
- secret_key
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
attachment:
type: string
format: binary
description: >-
Attachment must be in PNG, JPEG or PDF format and can be up
to 5 megabytes in size. Files larger than 5 MB are rejected.
required:
- attachment
responses:
'200':
$ref: '#/components/responses/DisputeAttachmentUpload'
'400':
$ref: '#/components/responses/BadRequestError_bad_request'
'401':
$ref: '#/components/responses/AuthenticationError_invalid_secret_key'
'500':
$ref: '#/components/responses/UnexpectedError'
components:
parameters:
paymentIdParam:
in: path
name: id
required: true
schema:
type: string
format: uuid
example: payment id, uuid format
description: ID of the payment.
webhookIdParam:
in: path
name: id
required: true
schema:
type: string
format: uuid
example: webhook id, uuid format
description: ID of the webhook.
refundIdParam:
in: path
name: refund_id
required: true
schema:
type: string
format: uuid
example: refund id, uuid format
description: ID of the refund.
merchantCodeParam:
in: header
name: X-Merchant-Code
required: true
schema:
type: string
example: code provided to you from Tabby side
description: >-
Used for multi store/countries setup, please contact your Account
manager to recognize that
sessionIdParam:
in: path
name: id
required: true
schema:
type: string
format: uuid
example: session id, uuid format
description: ID of the session.
disputeIdParam:
in: path
name: dispute_id
required: true
schema:
type: string
format: uuid
example: dispute id, uuid format
description: ID of the dispute.
responses:
CheckoutSession:
description: Success. Checkout session object is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutSession'
Dispute:
description: Success. Returns dispute info.
content:
application/json:
schema:
type: object
properties:
dispute:
$ref: '#/components/schemas/Dispute'
required:
- dispute
DisputeAttachmentUpload:
description: Success. Attachment was uploaded.
content:
application/json:
schema:
type: object
properties:
id:
type: string
format: uuid
example: attachment id, uuid format
description: Unique ID of attachment
DisputeProvideEvidence:
description: Success. Evidence was submitted for the dispute.
content:
application/json:
schema:
$ref: '#/components/schemas/Evidence'
DisputeProvideEvidenceConflict:
description: >-
Conflict. Evidence cannot be submitted for the dispute in its current
state.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_409'
Disputes:
description: Success. Returns a list of disputes.
content:
application/json:
schema:
type: object
properties:
disputes:
type: array
items:
$ref: '#/components/schemas/DisputeNoHistory'
next_page_token:
type: string
example: next_page_token
required:
- disputes
- next_page_token
DisputesApprove:
description: Success. Disputes were approved.
content:
application/json:
schema:
type: object
properties:
disputes:
type: array
items:
$ref: '#/components/schemas/DisputeNoHistory'
DisputesChallenge:
description: Success. Disputes were challenged.
content:
application/json:
schema:
type: object
properties:
disputes:
type: array
items:
$ref: '#/components/schemas/DisputeNoHistory'
PaymentCaptureResponse:
description: Success. Payment object is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentCaptureResponse'
PaymentClose:
description: Success. Payment object is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentClose'
PaymentRefundError:
description: Refund is unavailable.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_409'
PaymentRefundResponse:
description: Success. Payment object is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentRefundResponse'
PaymentResponse:
description: Success. Payment object is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResponse'
PaymentUpdate:
description: Success. Payment object is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/Paym
# --- truncated at 32 KB (131 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tabby/refs/heads/main/openapi/tabby-api-openapi.yml