openapi: 3.0.3
info:
  title: Telr Payment Gateway Agreements Hosted Payment Page API
  description: 'Telr is a UAE-headquartered (Dubai) online payment gateway operating across the MENA region (UAE, Saudi Arabia, Bahrain, Jordan), supporting 120+ currencies and 30 languages. This specification models Telr''s documented HTTPS/JSON gateway surfaces: the Hosted Payment Page (order.json), the Remote / Direct API (remote.json, including Apple Pay / Google Pay / Samsung Pay wallet tokens), repeat-billing agreements (manageagreement.json), and the newer REST Payments API (/api/v1/orders). Legacy gateway endpoints authenticate with a numeric store id + authentication key passed in the JSON body; the REST Service/Payments API uses HTTP Basic auth (store id : API key). All transactions are PCI DSS v4.0 Level 1 and NESA certified.'
  termsOfService: https://telr.com/terms-conditions/
  contact:
    name: Telr Support
    url: https://docs.telr.com/
    email: support@telr.com
  version: '1.0'
servers:
- url: https://secure.telr.com
  description: Telr production gateway (MENA)
security:
- basicAuth: []
tags:
- name: Hosted Payment Page
  description: Redirect-based hosted checkout (order.json).
paths:
  /gateway/order.json:
    post:
      operationId: createHostedOrder
      tags:
      - Hosted Payment Page
      summary: Create or check a hosted payment page order
      description: Create a hosted payment page order (method=create) and receive a process.html redirect URL, or check the status of an existing order (method=check) by its order ref. Authenticates with store + authkey in the request body (no HTTP auth header).
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HostedOrderRequest'
      responses:
        '200':
          description: Order created or status returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HostedOrderResponse'
components:
  schemas:
    HostedOrderResponse:
      type: object
      properties:
        method:
          type: string
        trace:
          type: string
        order:
          type: object
          properties:
            ref:
              type: string
            url:
              type: string
              format: uri
              example: https://secure.telr.com/gateway/process.html?o=OrderRef
            cartid:
              type: string
            amount:
              type: string
            currency:
              type: string
            status:
              type: object
              properties:
                code:
                  type: integer
                text:
                  type: string
                  example: Pending
        error:
          type: object
          properties:
            message:
              type: string
            note:
              type: string
    HostedOrder:
      type: object
      properties:
        ref:
          type: string
          description: Existing order ref (used with method=check).
        cartid:
          type: string
          maxLength: 63
          description: Unique cart / order id.
        test:
          type: integer
          enum:
          - 0
          - 1
          description: 0 = live, 1 = test.
        amount:
          type: string
          example: '9.50'
          description: Amount in major currency units.
        currency:
          type: string
          example: AED
          description: 3-letter ISO 4217 currency code.
        description:
          type: string
          maxLength: 63
        trantype:
          type: string
          enum:
          - sale
          - auth
    Customer:
      type: object
      properties:
        email:
          type: string
          format: email
        name:
          type: object
          properties:
            title:
              type: string
            firstName:
              type: string
            lastName:
              type: string
        address:
          type: object
          properties:
            line1:
              type: string
            line2:
              type: string
            line3:
              type: string
            city:
              type: string
            country:
              type: string
              description: ISO 3166-1 alpha-2 country code.
        phone:
          type: string
    HostedOrderRequest:
      type: object
      required:
      - method
      - store
      - authkey
      - order
      - return
      properties:
        method:
          type: string
          enum:
          - create
          - check
          description: create = new hosted order; check = query order status.
        store:
          type: integer
          description: Numeric store id (no text).
        authkey:
          type: string
          description: Authentication key for the store.
        framed:
          type: integer
          enum:
          - 0
          - 1
          - 2
          description: Whether the payment page renders inside an iframe.
        order:
          $ref: '#/components/schemas/HostedOrder'
        return:
          type: object
          properties:
            authorised:
              type: string
              format: uri
            declined:
              type: string
              format: uri
            cancelled:
              type: string
              format: uri
        customer:
          $ref: '#/components/schemas/Customer'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'HTTP Basic auth for the REST Service / Payments API: username = store id, password = API key (generated in Merchant Administration under Integrations > Service API). Base64 of "storeid:apikey".'