openapi: 3.1.0
info:
  title: Nomba Online Checkout API
  description: >-
    The Nomba Online Checkout API enables developers to create checkout
    orders and process payments through multiple channels. It supports Visa,
    Verve, and Mastercard payments, as well as USSD, bank transfers, and
    Nomba QR payments. The API includes tokenized card payment capabilities,
    allowing merchants to charge returning customers without requiring them
    to re-enter card details.
  version: '1.0.0'
  contact:
    name: Nomba Developer Support
    url: https://developer.nomba.com
  termsOfService: https://nomba.com/terms
externalDocs:
  description: Nomba Online Checkout Documentation
  url: https://developer.nomba.com/nomba-api-reference/online-checkout/create-an-online-checkout-order
servers:
  - url: https://api.nomba.com
    description: Production Server
  - url: https://sandbox.nomba.com
    description: Sandbox Server
tags:
  - name: Checkout Orders
    description: >-
      Endpoints for creating and managing online checkout orders that support
      multiple payment channels.
  - name: Tokenized Cards
    description: >-
      Endpoints for managing and charging tokenized card data for returning
      customers.
security:
  - bearerAuth: []
paths:
  /v1/checkout/order:
    post:
      operationId: createCheckoutOrder
      summary: Create an online checkout order
      description: >-
        Creates a new checkout order and returns a checkout link that can be
        loaded in a browser to allow the customer to initiate payment. The
        checkout supports Visa, Verve, Mastercard, USSD, bank transfers, and
        Nomba QR payments.
      tags:
        - Checkout Orders
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - order
              properties:
                order:
                  type: object
                  required:
                    - amount
                    - currency
                    - orderReference
                  properties:
                    amount:
                      type: number
                      format: double
                      description: >-
                        The payment amount for the checkout order.
                      minimum: 1
                      example: 10000
                    currency:
                      type: string
                      description: >-
                        The currency for the payment.
                      enum:
                        - NGN
                      example: NGN
                    orderReference:
                      type: string
                      description: >-
                        A unique reference for the order provided by the
                        merchant.
                      example: order_ref_12345
                    customerEmail:
                      type: string
                      format: email
                      description: >-
                        The email address of the customer.
                      example: customer@example.com
                    callbackUrl:
                      type: string
                      format: uri
                      description: >-
                        The URL to redirect the customer to after payment
                        completion.
                      example: https://merchant.com/callback
                    tokenizeCard:
                      type: boolean
                      description: >-
                        Set to true to tokenize the customer card for future
                        payments.
                      default: false
      responses:
        '200':
          description: Checkout order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutOrderResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/checkout/transaction/cancel:
    post:
      operationId: cancelCheckoutTransaction
      summary: Cancel a checkout transaction
      description: >-
        Cancels an incomplete checkout transaction. This can be used when a
        customer abandons the payment flow or when the merchant needs to void
        an unpaid order.
      tags:
        - Checkout Orders
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - orderReference
              properties:
                orderReference:
                  type: string
                  description: >-
                    The unique order reference of the transaction to cancel.
      responses:
        '200':
          description: Transaction cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          description: Invalid request or transaction cannot be cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/checkout/tokenized-card-data:
    get:
      operationId: listTokenizedCards
      summary: List tokenized cards
      description: >-
        Retrieves a list of tokenized card data stored for the merchant.
        Tokenized cards enable merchants to charge returning customers
        without requiring them to re-enter card details.
      tags:
        - Tokenized Cards
      parameters:
        - $ref: '#/components/parameters/accountId'
      responses:
        '200':
          description: Tokenized cards retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenizedCardListResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/checkout/tokenized-card-payment:
    post:
      operationId: chargeTokenizedCard
      summary: Charge a customer using tokenized card data
      description: >-
        Processes a payment using a previously tokenized card. This allows
        merchants to charge returning customers using unique tokens instead
        of requiring sensitive card details to be re-entered.
      tags:
        - Tokenized Cards
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - order
                - tokenKey
              properties:
                order:
                  type: object
                  required:
                    - amount
                    - currency
                    - orderReference
                  properties:
                    amount:
                      type: number
                      format: double
                      description: >-
                        The payment amount to charge.
                      minimum: 1
                    currency:
                      type: string
                      description: >-
                        The currency for the payment.
                      enum:
                        - NGN
                    orderReference:
                      type: string
                      description: >-
                        A unique order reference for the payment.
                    customerEmail:
                      type: string
                      format: email
                      description: >-
                        The email address of the customer.
                tokenKey:
                  type: string
                  description: >-
                    The token key representing the customer saved card.
      responses:
        '200':
          description: Tokenized card charged successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeResponse'
        '400':
          description: Invalid request or charge failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        OAuth2 bearer token obtained from the Nomba Authentication API.
  parameters:
    accountId:
      name: accountId
      in: header
      required: true
      description: >-
        The unique identifier of the parent business account.
      schema:
        type: string
  schemas:
    CheckoutOrderResponse:
      type: object
      properties:
        code:
          type: string
          description: >-
            Response status code.
          example: '00'
        description:
          type: string
          description: >-
            Human-readable description of the response.
          example: Success
        data:
          type: object
          properties:
            orderReference:
              type: string
              description: >-
                The unique reference for the checkout order.
            checkoutLink:
              type: string
              format: uri
              description: >-
                The URL to load in a browser for the customer to complete
                payment.
            amount:
              type: number
              format: double
              description: >-
                The payment amount for the order.
            currency:
              type: string
              description: >-
                The currency of the order.
            status:
              type: string
              description: >-
                The current status of the order.
            createdAt:
              type: string
              format: date-time
              description: >-
                The date and time the order was created.
    TokenizedCardListResponse:
      type: object
      properties:
        code:
          type: string
          description: >-
            Response status code.
          example: '00'
        description:
          type: string
          description: >-
            Human-readable description of the response.
          example: Success
        data:
          type: object
          properties:
            results:
              type: array
              description: >-
                List of tokenized cards.
              items:
                $ref: '#/components/schemas/TokenizedCard'
    ChargeResponse:
      type: object
      properties:
        code:
          type: string
          description: >-
            Response status code.
          example: '00'
        description:
          type: string
          description: >-
            Human-readable description of the response.
          example: Success
        data:
          type: object
          properties:
            orderReference:
              type: string
              description: >-
                The order reference for the charged transaction.
            transactionId:
              type: string
              description: >-
                The unique identifier for the transaction.
            status:
              type: string
              description: >-
                The status of the charge.
              enum:
                - successful
                - pending
                - failed
            amount:
              type: number
              format: double
              description: >-
                The amount charged.
    TokenizedCard:
      type: object
      properties:
        tokenKey:
          type: string
          description: >-
            The unique token representing the saved card.
        cardType:
          type: string
          description: >-
            The card network brand.
          enum:
            - Visa
            - Mastercard
            - Verve
        last4:
          type: string
          description: >-
            The last 4 digits of the card number.
          pattern: '^\d{4}$'
        expiryMonth:
          type: string
          description: >-
            The expiry month of the card.
        expiryYear:
          type: string
          description: >-
            The expiry year of the card.
        customerEmail:
          type: string
          format: email
          description: >-
            The email address of the card holder.
    SuccessResponse:
      type: object
      properties:
        code:
          type: string
          description: >-
            Response status code.
          example: '00'
        description:
          type: string
          description: >-
            Human-readable description of the response.
          example: Success
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: >-
            Error status code.
        description:
          type: string
          description: >-
            Human-readable description of the error.
        errors:
          type: array
          description: >-
            List of specific error details.
          items:
            type: string