openapi: 3.0.3
info:
  title: Telr Payment Gateway Agreements Payments API 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: Payments API
  description: Newer REST order API with HTTP Basic auth.
paths:
  /api/v1/orders:
    post:
      operationId: createOrder
      tags:
      - Payments API
      summary: Create an order (REST Payments API)
      description: Newer REST order-creation endpoint. Authenticates with HTTP Basic auth (store id as username, API key as password). Returns the order with hypermedia _links and up to two webhooks.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderRequest'
      responses:
        '201':
          description: Order created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/orders/{ref}:
    get:
      operationId: getOrder
      tags:
      - Payments API
      summary: Retrieve an order (REST Payments API)
      description: 'Retrieve an order and its current status by order ref. Authenticates with HTTP Basic auth (store id : API key).'
      parameters:
      - name: ref
        in: path
        required: true
        description: Order reference.
        schema:
          type: string
      responses:
        '200':
          description: Order returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Order not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    OrderRequest:
      type: object
      required:
      - cartId
      - amount
      - currency
      - customer
      properties:
        cartId:
          type: string
          minLength: 1
          maxLength: 63
        transactionType:
          type: string
          enum:
          - SALE
          - AUTH
          - VERIFY
        amount:
          type: object
          properties:
            value:
              type: string
            currency:
              type: string
        currency:
          type: string
          example: AED
        description:
          type: string
          maxLength: 63
        test:
          type: boolean
        customer:
          $ref: '#/components/schemas/Customer'
        webhooks:
          type: array
          maxItems: 2
          items:
            type: string
            format: uri
    Order:
      type: object
      properties:
        ref:
          type: string
        status:
          type: string
          enum:
          - PENDING
          - AUTHORISED
          - PAID
          - CANCELLED
          - DECLINED
        cartId:
          type: string
        amount:
          type: object
          properties:
            value:
              type: string
            currency:
              type: string
        _links:
          type: object
          properties:
            self:
              type: object
              properties:
                href:
                  type: string
            auth:
              type: object
              properties:
                href:
                  type: string
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
        status:
          type: string
        reason:
          type: string
        errors:
          type: array
          items:
            type: object
    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
  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".'