openapi: 3.1.0
info:
  title: Nomba Transfers API
  description: >-
    The Nomba Transfers API provides endpoints for initiating and managing
    fund transfers. Developers can look up bank codes and names, verify
    account details, initiate transfers to Nigerian bank accounts, and
    transfer funds between Nomba wallets. The API supports domestic money
    transfers and provides the necessary bank metadata for building payment
    flows within applications.
  version: '1.0.0'
  contact:
    name: Nomba Developer Support
    url: https://developer.nomba.com
  termsOfService: https://nomba.com/terms
externalDocs:
  description: Nomba Transfers API Documentation
  url: https://developer.nomba.com/nomba-api-reference/transfers/fetch-bank-codes-and-names
servers:
  - url: https://api.nomba.com
    description: Production Server
  - url: https://sandbox.nomba.com
    description: Sandbox Server
tags:
  - name: Transfers
    description: >-
      Endpoints for bank lookups, account verification, and initiating
      domestic fund transfers to bank accounts and between wallets.
security:
  - bearerAuth: []
paths:
  /v1/transfers/banks:
    get:
      operationId: fetchBankCodes
      summary: Fetch bank codes and names
      description: >-
        Retrieves a list of all supported Nigerian banks along with their
        corresponding bank codes. These codes are required when initiating
        transfers to bank accounts.
      tags:
        - Transfers
      parameters:
        - $ref: '#/components/parameters/accountId'
      responses:
        '200':
          description: Bank list retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankListResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/transfers/bank/lookup:
    post:
      operationId: performBankAccountLookup
      summary: Perform bank account lookup
      description: >-
        Verifies a bank account by looking up the account number and bank
        code. Returns the account holder name if the account is valid. This
        should be called before initiating a transfer to confirm the
        recipient details.
      tags:
        - Transfers
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - accountNumber
                - bankCode
              properties:
                accountNumber:
                  type: string
                  description: >-
                    The bank account number to look up.
                  pattern: '^\d{10}$'
                  example: '0123456789'
                bankCode:
                  type: string
                  description: >-
                    The bank code identifying the financial institution.
                  example: '058'
      responses:
        '200':
          description: Account lookup successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BankAccountLookupResponse'
        '400':
          description: Invalid account number or bank code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/transfers/bank:
    post:
      operationId: transferToBank
      summary: Transfer to a bank account
      description: >-
        Initiates a fund transfer from the authenticated Nomba account to an
        external Nigerian bank account. Requires the recipient account
        number, bank code, amount, and a unique merchant transaction
        reference.
      tags:
        - Transfers
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
                - accountNumber
                - accountName
                - bankCode
                - merchantTxRef
              properties:
                amount:
                  type: number
                  format: double
                  description: >-
                    The amount to transfer in the smallest currency unit (kobo).
                  minimum: 1
                  example: 10000
                accountNumber:
                  type: string
                  description: >-
                    The recipient bank account number.
                  pattern: '^\d{10}$'
                  example: '0123456789'
                accountName:
                  type: string
                  description: >-
                    The name of the recipient account holder.
                  example: John Doe
                bankCode:
                  type: string
                  description: >-
                    The bank code of the recipient financial institution.
                  example: '058'
                merchantTxRef:
                  type: string
                  description: >-
                    A unique transaction reference provided by the merchant
                    for idempotency and reconciliation.
                  example: txn_ref_12345
                narration:
                  type: string
                  description: >-
                    An optional description or note for the transfer.
                  maxLength: 100
                  example: Payment for services
      responses:
        '200':
          description: Transfer initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferResponse'
        '400':
          description: Invalid transfer parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/transfers/wallet:
    post:
      operationId: transferBetweenAccounts
      summary: Transfer between Nomba accounts
      description: >-
        Initiates a wallet-to-wallet transfer between two Nomba accounts.
        Enables instant movement of funds between accounts on the Nomba
        platform without going through external banking rails.
      tags:
        - Transfers
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
                - receiverAccountId
                - merchantTxRef
              properties:
                amount:
                  type: number
                  format: double
                  description: >-
                    The amount to transfer.
                  minimum: 1
                  example: 5000
                receiverAccountId:
                  type: string
                  description: >-
                    The account ID of the recipient Nomba account.
                  example: 5f04b9ee600f1c00084affa2
                merchantTxRef:
                  type: string
                  description: >-
                    A unique transaction reference for idempotency and
                    reconciliation.
                  example: wallet_txn_12345
                narration:
                  type: string
                  description: >-
                    An optional description or note for the transfer.
                  maxLength: 100
      responses:
        '200':
          description: Wallet transfer completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransferResponse'
        '400':
          description: Invalid transfer parameters
          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:
    BankListResponse:
      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 supported banks.
              items:
                $ref: '#/components/schemas/Bank'
    BankAccountLookupResponse:
      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:
            accountNumber:
              type: string
              description: >-
                The verified bank account number.
            accountName:
              type: string
              description: >-
                The name of the account holder as registered with the bank.
            bankCode:
              type: string
              description: >-
                The bank code of the financial institution.
    TransferResponse:
      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 transfer transaction.
            status:
              type: string
              description: >-
                The current status of the transfer.
              enum:
                - pending
                - successful
                - failed
            amount:
              type: number
              format: double
              description: >-
                The amount transferred.
            fee:
              type: number
              format: double
              description: >-
                The fee charged for the transfer.
            merchantTxRef:
              type: string
              description: >-
                The merchant transaction reference provided in the request.
            createdAt:
              type: string
              format: date-time
              description: >-
                The date and time the transfer was initiated.
    Bank:
      type: object
      properties:
        bankCode:
          type: string
          description: >-
            The unique code identifying the bank.
          example: '058'
        bankName:
          type: string
          description: >-
            The official name of the bank.
          example: Guaranty Trust Bank
    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