openapi: 3.1.0
info:
  title: Nomba Accounts Transfers 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: Transfers
  description: Endpoints for bank lookups, account verification, and initiating domestic fund transfers to bank accounts and between wallets.
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:
  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.
    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
    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.
  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