openapi: 3.1.0
info:
  title: Nomba Charge API
  description: >-
    The Nomba Charge API provides direct card charging capabilities for
    developers building payment solutions. It supports submitting customer
    card details, OTP verification, retrieving user saved cards, and
    managing the server-to-server card payment flow. This API is designed
    for merchants and platforms that need programmatic control over the card
    payment process, including handling 3D Secure authentication steps.
  version: '1.0.0'
  contact:
    name: Nomba Developer Support
    url: https://developer.nomba.com
  termsOfService: https://nomba.com/terms
externalDocs:
  description: Nomba Charge API Documentation
  url: https://developer.nomba.com/nomba-api-reference/charge/submit-customer-card-otp
servers:
  - url: https://api.nomba.com
    description: Production Server
  - url: https://sandbox.nomba.com
    description: Sandbox Server
tags:
  - name: Card Charge
    description: >-
      Endpoints for submitting card details, processing OTP verification,
      and managing the card payment flow.
  - name: Order Management
    description: >-
      Endpoints for retrieving order details and managing checkout
      transactions.
  - name: Saved Cards
    description: >-
      Endpoints for retrieving and managing customer saved cards.
security:
  - bearerAuth: []
paths:
  /v1/checkout/checkout-card-detail:
    post:
      operationId: submitCustomerCardDetails
      summary: Submit customer card details
      description: >-
        Submits customer card details to initiate a card payment. This is the
        first step in the server-to-server card charge flow. The API will
        return instructions for the next step, which typically involves OTP
        verification or 3D Secure authentication.
      tags:
        - Card Charge
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - cardNumber
                - expiryMonth
                - expiryYear
                - cvv
                - orderReference
              properties:
                cardNumber:
                  type: string
                  description: >-
                    The full card number (PAN).
                  pattern: '^\d{13,19}$'
                expiryMonth:
                  type: string
                  description: >-
                    The card expiry month (MM format).
                  pattern: '^\d{2}$'
                  example: '12'
                expiryYear:
                  type: string
                  description: >-
                    The card expiry year (YY format).
                  pattern: '^\d{2}$'
                  example: '25'
                cvv:
                  type: string
                  description: >-
                    The card verification value.
                  pattern: '^\d{3,4}$'
                pin:
                  type: string
                  description: >-
                    The card PIN, required for local card transactions.
                  pattern: '^\d{4}$'
                orderReference:
                  type: string
                  description: >-
                    The order reference from a previously created checkout
                    order.
                tokenizedCard:
                  type: boolean
                  description: >-
                    Set to true to tokenize the card for future payments.
                  default: false
      responses:
        '200':
          description: Card details submitted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardChargeResponse'
        '400':
          description: Invalid card details or request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/checkout/checkout-card-otp:
    post:
      operationId: submitCustomerCardOtp
      summary: Submit customer card OTP
      description: >-
        Submits the OTP (One-Time Password) sent to the customer phone or
        email to complete card payment verification. This is typically the
        second step in the server-to-server card charge flow after card
        details have been submitted.
      tags:
        - Card Charge
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - otp
                - orderReference
                - transactionId
              properties:
                otp:
                  type: string
                  description: >-
                    The OTP received by the customer.
                  pattern: '^\d{4,8}$'
                orderReference:
                  type: string
                  description: >-
                    The order reference for the transaction.
                transactionId:
                  type: string
                  description: >-
                    The transaction ID from the card details submission step.
      responses:
        '200':
          description: OTP verified and payment processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CardChargeResponse'
        '400':
          description: Invalid OTP or request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/checkout/resend-card-otp:
    post:
      operationId: resendOtpToCustomer
      summary: Resend OTP to customer phone
      description: >-
        Resends the OTP to the customer phone number if the original OTP
        was not received, was incorrect, or has expired.
      tags:
        - Card Charge
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - orderReference
                - transactionId
              properties:
                orderReference:
                  type: string
                  description: >-
                    The order reference for the transaction.
                transactionId:
                  type: string
                  description: >-
                    The transaction ID from the card details submission step.
      responses:
        '200':
          description: OTP resent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '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/user-card/{orderReference}:
    get:
      operationId: getUserSavedCards
      summary: Get user saved cards
      description: >-
        Retrieves cards saved by a user during previous checkout transactions.
        Requires OTP validation before cards can be fetched to ensure the
        request is authorized by the card holder.
      tags:
        - Saved Cards
      parameters:
        - name: orderReference
          in: path
          required: true
          description: >-
            The order reference used to validate the user session.
          schema:
            type: string
        - $ref: '#/components/parameters/accountId'
      responses:
        '200':
          description: Saved cards retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedCardsResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No saved cards found for the order reference
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/checkout/request-user-otp:
    post:
      operationId: requestUserOtpForSavedCards
      summary: Request OTP to validate user before fetching saved cards
      description: >-
        Requests an OTP to be sent to the customer for validation before
        their saved cards can be retrieved. This ensures only the card holder
        can access their saved payment methods.
      tags:
        - Saved Cards
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - orderReference
              properties:
                orderReference:
                  type: string
                  description: >-
                    The order reference for the current transaction.
                customerEmail:
                  type: string
                  format: email
                  description: >-
                    The customer email to send the OTP to.
      responses:
        '200':
          description: OTP sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '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/order/{orderReference}:
    get:
      operationId: getOrderDetails
      summary: Get order details by order reference
      description: >-
        Retrieves the details of a checkout order using the generated order
        reference. This can be used to check the current status and details
        of a payment order.
      tags:
        - Order Management
      parameters:
        - name: orderReference
          in: path
          required: true
          description: >-
            The unique order reference generated when the order was created.
          schema:
            type: string
        - $ref: '#/components/parameters/accountId'
      responses:
        '200':
          description: Order details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderDetailsResponse'
        '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:
  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:
    CardChargeResponse:
      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:
            transactionId:
              type: string
              description: >-
                The unique identifier for the transaction.
            orderReference:
              type: string
              description: >-
                The order reference for the transaction.
            status:
              type: string
              description: >-
                The current status of the charge.
              enum:
                - otp_required
                - 3ds_required
                - successful
                - failed
                - pending
            message:
              type: string
              description: >-
                Additional information about the charge status or next steps.
    SavedCardsResponse:
      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 saved cards for the user.
              items:
                $ref: '#/components/schemas/SavedCard'
    OrderDetailsResponse:
      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 order reference.
            amount:
              type: number
              format: double
              description: >-
                The order amount.
            currency:
              type: string
              description: >-
                The currency of the order.
            status:
              type: string
              description: >-
                The current status of the order.
              enum:
                - pending
                - successful
                - failed
                - cancelled
            createdAt:
              type: string
              format: date-time
              description: >-
                The date and time the order was created.
    SavedCard:
      type: object
      properties:
        cardId:
          type: string
          description: >-
            The unique identifier for 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.
        tokenKey:
          type: string
          description: >-
            The token key for charging this saved card.
    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