openapi: 3.0.1 info: title: PayTabs PT2 Payments API description: 'PayTabs PT2 REST API for MENA payment acceptance. A small, uniform surface: POST /payment/request creates and manages transactions (hosted payment page, managed/own form, invoices, tokenized and recurring charges, and follow-up capture / void / release / refund actions selected via tran_type), and POST /payment/query reads transaction status by tran_ref or cart_id. Requests are JSON; the merchant server key is sent in the `authorization` header and the profile is identified by `profile_id` in the body.' termsOfService: https://paytabs.com/en/terms-and-conditions/ contact: name: PayTabs Support url: https://support.paytabs.com/ version: '2.0' servers: - url: https://secure.paytabs.com description: UAE / default region - url: https://secure.paytabs.sa description: Saudi Arabia (KSA) - url: https://secure-egypt.paytabs.com description: Egypt - url: https://secure-oman.paytabs.com description: Oman - url: https://secure-jordan.paytabs.com description: Jordan - url: https://secure-kuwait.paytabs.com description: Kuwait - url: https://secure-iraq.paytabs.com description: Iraq - url: https://secure-morocco.paytabs.com description: Morocco - url: https://secure-doha.paytabs.com description: Qatar - url: https://secure-global.paytabs.com description: Global security: - serverKey: [] tags: - name: Payments description: Create and manage transactions. paths: /payment/request: post: operationId: createPaymentRequest tags: - Payments summary: Create or act on a transaction description: Creates a transaction. The `tran_type` field selects the action - `sale` or `auth` initiate a new payment (returning a hosted `redirect_url` for HPP/managed/own-form flows, or authorizing a stored `token`), while `capture`, `void`, `release`, `refund` and `register` act on a prior transaction referenced by `tran_ref`. Invoice and recurring flows reuse the same endpoint with additional fields. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PaymentRequest' responses: '200': description: Transaction created or actioned. content: application/json: schema: $ref: '#/components/schemas/PaymentResponse' '400': description: Validation error (missing or conflicting parameters). '401': description: Authentication failed (wrong server key or region host). components: schemas: PaymentResponse: type: object properties: tran_ref: type: string tran_type: type: string cart_id: type: string cart_description: type: string cart_currency: type: string cart_amount: type: string redirect_url: type: string format: uri description: Hosted payment page URL to redirect the customer to (sale/auth HPP flows). customer_details: $ref: '#/components/schemas/CustomerDetails' payment_result: type: object properties: response_status: type: string description: A (authorized), H (hold), P (pending), V (voided), E (error), D (declined). response_code: type: string response_message: type: string transaction_time: type: string payment_info: type: object properties: payment_method: type: string card_type: type: string card_scheme: type: string payment_description: type: string token: type: string description: Card token returned when tokenise/register was requested. PaymentRequest: type: object required: - profile_id - tran_type - tran_class - cart_id - cart_description - cart_currency - cart_amount properties: profile_id: oneOf: - type: integer - type: string description: The PayTabs profile that owns the transaction. tran_type: type: string enum: - sale - auth - capture - void - release - refund - register description: The transaction action to perform. tran_class: type: string enum: - ecom - recurring - moto description: Transaction class - e-commerce, recurring, or mail/telephone order. cart_id: type: string maxLength: 64 description: Merchant-side cart/order identifier. cart_description: type: string maxLength: 128 cart_currency: type: string description: ISO 4217 currency (e.g. SAR, AED, EGP, USD). cart_amount: type: number minimum: 0.01 tran_ref: type: string description: Prior transaction reference (required for capture/void/release/refund). callback: type: string format: uri maxLength: 255 description: Server-to-server IPN callback URL. return: type: string format: uri maxLength: 255 description: Browser return URL after the hosted payment page. customer_details: $ref: '#/components/schemas/CustomerDetails' shipping_details: $ref: '#/components/schemas/CustomerDetails' hide_shipping: type: boolean payment_methods: type: array items: type: string description: Restrict allowed methods, e.g. creditcard, mada, applepay, stcpay, valu, unionpay, amex, meeza, knet, benefit, omannet, urpay. token: type: string description: Saved-card token for token-based / recurring charges. tokenise: type: integer minimum: 1 maximum: 6 description: Request tokenization of the card in the returned response. show_save_card: type: boolean config_id: type: integer description: Hosted page theme/config identifier. card_filter: type: string maxLength: 255 description: Restrict accepted BIN ranges. framed: type: boolean description: Render the hosted page inside an iframe (managed form). user_defined: type: object description: Up to nine merchant fields udf1..udf9. CustomerDetails: type: object properties: name: type: string email: type: string format: email phone: type: string street1: type: string city: type: string state: type: string country: type: string description: ISO 3166-1 alpha-2 country code (e.g. SA, AE, EG). zip: type: string ip: type: string securitySchemes: serverKey: type: apiKey in: header name: authorization description: Merchant server key sent as the raw value of the `authorization` HTTP header (not a Bearer token), obtained from the PayTabs merchant dashboard under Developers > Key management. Format resembles SXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX. Must match the profile's region host.