openapi: 3.0.3
info:
  title: Tamara Channel Partners Captures Checkout Sessions API
  description: 'Allow payment service providers, platforms, and aggregators to onboard merchants onto

    Tamara on their behalf. Submit merchant KYB/KYC information, retrieve onboarding

    status and merchant API keys, and register onboarding event webhooks.

    '
  version: 1.0.0
  contact:
    name: Tamara Partner Support
    url: https://docs.tamara.co/
servers:
- url: https://partner-api.tamara.co
  description: Production
- url: https://partner-api-sandbox.tamara.co
  description: Sandbox
tags:
- name: Checkout Sessions
  description: Create and manage hosted-checkout sessions.
paths:
  /checkout:
    post:
      operationId: createCheckoutSession
      summary: Create Checkout Session
      description: 'Create a hosted checkout session where Tamara collects payment information and

        completes the BNPL or Pay-Now flow with the consumer. Store the returned

        `order_id` and redirect the customer to `checkout_url`.

        '
      tags:
      - Checkout Sessions
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckoutSessionRequest'
      responses:
        '200':
          description: Checkout session created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutSessionResponse'
        '400':
          description: Validation failure (e.g. unsupported country/currency combination).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CheckoutSessionRequest:
      type: object
      required:
      - order_reference_id
      - total_amount
      - description
      - country_code
      - payment_type
      - items
      - consumer
      - shipping_address
      - tax_amount
      - shipping_amount
      - merchant_url
      properties:
        order_reference_id:
          type: string
        order_number:
          type: string
        total_amount:
          $ref: '#/components/schemas/Money'
        description:
          type: string
          maxLength: 256
        country_code:
          type: string
          enum:
          - SA
          - AE
          - BH
          - KW
          - OM
        payment_type:
          type: string
          enum:
          - PAY_BY_INSTALMENTS
          - PAY_NOW
        instalments:
          type: integer
          minimum: 2
          maximum: 24
        locale:
          type: string
          enum:
          - ar_SA
          - en_US
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        consumer:
          $ref: '#/components/schemas/Consumer'
        billing_address:
          $ref: '#/components/schemas/Address'
        shipping_address:
          $ref: '#/components/schemas/Address'
        discount:
          type: object
          properties:
            name:
              type: string
            amount:
              $ref: '#/components/schemas/Money'
        tax_amount:
          $ref: '#/components/schemas/Money'
        shipping_amount:
          $ref: '#/components/schemas/Money'
        merchant_url:
          $ref: '#/components/schemas/MerchantUrls'
        platform:
          type: string
        is_mobile:
          type: boolean
        risk_assessment:
          type: object
          additionalProperties: true
        expires_in_minutes:
          type: integer
          minimum: 5
          maximum: 1440
          default: 30
        additional_data:
          type: object
          additionalProperties: true
    CheckoutSessionResponse:
      type: object
      properties:
        order_id:
          type: string
          format: uuid
        checkout_id:
          type: string
          format: uuid
        checkout_url:
          type: string
          format: uri
        status:
          type: string
          example: new
    Consumer:
      type: object
      required:
      - first_name
      - last_name
      - phone_number
      properties:
        first_name:
          type: string
        last_name:
          type: string
        phone_number:
          type: string
          description: E.164 phone number for the consumer.
        email:
          type: string
          format: email
        date_of_birth:
          type: string
          format: date
        national_id:
          type: string
    Address:
      type: object
      required:
      - first_name
      - last_name
      - line1
      - city
      - country_code
      properties:
        first_name:
          type: string
        last_name:
          type: string
        line1:
          type: string
        line2:
          type: string
        region:
          type: string
        city:
          type: string
        country_code:
          type: string
          minLength: 2
          maxLength: 2
        phone_number:
          type: string
    MerchantUrls:
      type: object
      required:
      - success
      - failure
      - cancel
      properties:
        success:
          type: string
          format: uri
        failure:
          type: string
          format: uri
        cancel:
          type: string
          format: uri
        notification:
          type: string
          format: uri
    Item:
      type: object
      required:
      - reference_id
      - type
      - name
      - sku
      - quantity
      - total_amount
      properties:
        reference_id:
          type: string
        type:
          type: string
        name:
          type: string
        sku:
          type: string
        quantity:
          type: integer
        unit_price:
          $ref: '#/components/schemas/Money'
        discount_amount:
          $ref: '#/components/schemas/Money'
        tax_amount:
          $ref: '#/components/schemas/Money'
        total_amount:
          $ref: '#/components/schemas/Money'
        image_url:
          type: string
          format: uri
    Money:
      type: object
      required:
      - amount
      - currency
      properties:
        amount:
          type: number
          format: double
          example: 300
        currency:
          type: string
          enum:
          - SAR
          - AED
          - BHD
          - KWD
          - OMR
    Error:
      type: object
      properties:
        message:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              error_code:
                type: string
              description:
                type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer