openapi: 3.1.0
info:
  title: Nomba Accounts Saved Cards API
  description: The Nomba Accounts API enables developers to manage business accounts on the Nomba platform. It provides endpoints for retrieving account details, fetching the parent account balance, and listing terminals assigned to an account. This API serves as the foundation for account management operations within the Nomba ecosystem.
  version: 1.0.0
  contact:
    name: Nomba Developer Support
    url: https://developer.nomba.com
  termsOfService: https://nomba.com/terms
servers:
- url: https://api.nomba.com
  description: Production Server
- url: https://sandbox.nomba.com
  description: Sandbox Server
security:
- bearerAuth: []
tags:
- name: Saved Cards
  description: Endpoints for retrieving and managing customer saved cards.
paths:
  /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'
components:
  schemas:
    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'
    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
    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.
    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
  parameters:
    accountId:
      name: accountId
      in: header
      required: true
      description: The unique identifier of the parent business account.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth2 bearer token obtained from the Nomba Authentication API.
externalDocs:
  description: Nomba Accounts API Documentation
  url: https://developer.nomba.com/nomba-api-reference/accounts/fetch-terminals-assigned-to-an-account