openapi: 3.1.0
info:
  title: Nomba Global Payout API
  description: >-
    The Nomba Global Payout API is a single integration point that enables
    cross-border payment operators, remittance platforms, and fintechs to
    collect funds in Nigerian Naira or stablecoins (USDT/USDC) and trigger
    instant disbursements to the United Kingdom via Faster Payments, Europe
    via SEPA, Canada via Interac and bank transfer, and the Democratic
    Republic of Congo via Mobile Money. The API embeds FX sourcing and
    compliance directly into the technical layer, eliminating the need for
    operators to manage foreign exchange processes. It provides a four-step
    integration flow: fetch rate, lock rate, authorize transfer, and track
    transaction.
  version: '1.0.0'
  contact:
    name: Nomba Developer Support
    url: https://developer.nomba.com
  termsOfService: https://nomba.com/terms
externalDocs:
  description: Nomba Global Payout Documentation
  url: https://developer.nomba.com/docs/products/global-payout/introduction
servers:
  - url: https://api.nomba.com
    description: Production Server
  - url: https://sandbox.nomba.com
    description: Sandbox Server
tags:
  - name: Corridors
    description: >-
      Endpoints for listing supported payout corridors and their
      configurations.
  - name: Exchange Rates
    description: >-
      Endpoints for fetching and locking live exchange rates for
      cross-border payouts.
  - name: Payouts
    description: >-
      Endpoints for initiating and tracking cross-border payout
      transactions.
security:
  - bearerAuth: []
paths:
  /v1/global-payout/rates:
    get:
      operationId: fetchExchangeRates
      summary: Fetch live exchange rates
      description: >-
        Retrieves the current live exchange rates for all supported payout
        corridors. Rates are indicative and may change. Use the rate lock
        endpoint to secure a rate before initiating a payout.
      tags:
        - Exchange Rates
      parameters:
        - $ref: '#/components/parameters/accountId'
        - name: sourceCurrency
          in: query
          required: false
          description: >-
            Filter rates by source currency.
          schema:
            type: string
            enum:
              - NGN
              - USDT
              - USDC
        - name: destinationCurrency
          in: query
          required: false
          description: >-
            Filter rates by destination currency.
          schema:
            type: string
            enum:
              - GBP
              - EUR
              - CAD
              - CDF
      responses:
        '200':
          description: Exchange rates retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExchangeRateListResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/global-payout/rates/lock:
    post:
      operationId: lockExchangeRate
      summary: Lock an exchange rate
      description: >-
        Locks the current exchange rate for a specified corridor for five
        minutes. The locked rate is guaranteed for the duration and must be
        used when authorizing the payout transfer. This eliminates slippage
        on volatile corridors and removes reconciliation disputes.
      tags:
        - Exchange Rates
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - sourceCurrency
                - destinationCurrency
                - amount
              properties:
                sourceCurrency:
                  type: string
                  description: >-
                    The source currency for the payout.
                  enum:
                    - NGN
                    - USDT
                    - USDC
                destinationCurrency:
                  type: string
                  description: >-
                    The destination currency for the payout.
                  enum:
                    - GBP
                    - EUR
                    - CAD
                    - CDF
                amount:
                  type: number
                  format: double
                  description: >-
                    The payout amount in the source currency.
                  minimum: 1
      responses:
        '200':
          description: Exchange rate locked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLockResponse'
        '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/global-payout/transfer:
    post:
      operationId: createGlobalPayout
      summary: Authorize a global payout transfer
      description: >-
        Authorizes and initiates a cross-border payout transfer using a
        previously locked exchange rate. The transfer includes recipient
        details and the locked rate ID. Supported corridors include the
        United Kingdom (Faster Payments, up to 1,000,000 GBP, settled in
        1-3 hours), Europe (SEPA, up to 100,000 EUR, settled in under 1
        hour), Canada (Interac instant or bank transfer), and the DRC
        (Mobile Money instant or bank transfer).
      tags:
        - Payouts
      parameters:
        - $ref: '#/components/parameters/accountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - rateLockId
                - amount
                - recipient
              properties:
                rateLockId:
                  type: string
                  description: >-
                    The ID of the locked exchange rate to use for this payout.
                amount:
                  type: number
                  format: double
                  description: >-
                    The payout amount in the source currency.
                  minimum: 1
                recipient:
                  $ref: '#/components/schemas/PayoutRecipient'
                merchantTxRef:
                  type: string
                  description: >-
                    A unique merchant reference for idempotency and
                    reconciliation.
                narration:
                  type: string
                  description: >-
                    An optional description for the payout.
                  maxLength: 200
      responses:
        '200':
          description: Payout transfer initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
        '400':
          description: Invalid request or expired rate lock
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/global-payout/transfer/{transactionId}:
    get:
      operationId: trackGlobalPayout
      summary: Track a global payout transaction
      description: >-
        Retrieves the current status and details of a global payout
        transaction. Provides end-to-end tracking from initiation through
        settlement.
      tags:
        - Payouts
      parameters:
        - name: transactionId
          in: path
          required: true
          description: >-
            The unique identifier of the payout transaction to track.
          schema:
            type: string
        - $ref: '#/components/parameters/accountId'
      responses:
        '200':
          description: Payout status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Payout transaction not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/global-payout/corridors:
    get:
      operationId: listPayoutCorridors
      summary: List supported payout corridors
      description: >-
        Retrieves the list of supported cross-border payout corridors along
        with their configurations, limits, settlement times, and available
        payment methods.
      tags:
        - Corridors
      parameters:
        - $ref: '#/components/parameters/accountId'
      responses:
        '200':
          description: Corridors retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CorridorListResponse'
        '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:
    ExchangeRateListResponse:
      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 available exchange rates.
              items:
                $ref: '#/components/schemas/ExchangeRate'
    RateLockResponse:
      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:
            rateLockId:
              type: string
              description: >-
                The unique identifier for the locked rate.
            sourceCurrency:
              type: string
              description: >-
                The source currency.
            destinationCurrency:
              type: string
              description: >-
                The destination currency.
            rate:
              type: number
              format: double
              description: >-
                The locked exchange rate.
            amount:
              type: number
              format: double
              description: >-
                The amount in the source currency.
            convertedAmount:
              type: number
              format: double
              description: >-
                The equivalent amount in the destination currency.
            expiresAt:
              type: string
              format: date-time
              description: >-
                The date and time the rate lock expires (5-minute window).
    PayoutResponse:
      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 payout transaction.
            status:
              type: string
              description: >-
                The current status of the payout.
              enum:
                - initiated
                - processing
                - settled
                - failed
            sourceCurrency:
              type: string
              description: >-
                The source currency of the payout.
            destinationCurrency:
              type: string
              description: >-
                The destination currency of the payout.
            sourceAmount:
              type: number
              format: double
              description: >-
                The amount debited in the source currency.
            destinationAmount:
              type: number
              format: double
              description: >-
                The amount to be received in the destination currency.
            rate:
              type: number
              format: double
              description: >-
                The exchange rate applied.
            fee:
              type: number
              format: double
              description: >-
                The fee charged for the payout.
            paymentMethod:
              type: string
              description: >-
                The payment method used for disbursement.
              enum:
                - faster_payments
                - sepa
                - interac
                - bank_transfer
                - mobile_money
            merchantTxRef:
              type: string
              description: >-
                The merchant transaction reference.
            recipient:
              $ref: '#/components/schemas/PayoutRecipient'
            createdAt:
              type: string
              format: date-time
              description: >-
                The date and time the payout was initiated.
            settledAt:
              type: string
              format: date-time
              description: >-
                The date and time the payout was settled, if applicable.
    CorridorListResponse:
      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 payout corridors.
              items:
                $ref: '#/components/schemas/Corridor'
    ExchangeRate:
      type: object
      properties:
        sourceCurrency:
          type: string
          description: >-
            The source currency code.
          example: NGN
        destinationCurrency:
          type: string
          description: >-
            The destination currency code.
          example: GBP
        rate:
          type: number
          format: double
          description: >-
            The current indicative exchange rate.
        updatedAt:
          type: string
          format: date-time
          description: >-
            The date and time the rate was last updated.
    PayoutRecipient:
      type: object
      required:
        - name
        - country
      properties:
        name:
          type: string
          description: >-
            The full name of the recipient.
        country:
          type: string
          description: >-
            The ISO 3166-1 alpha-2 country code of the recipient.
          enum:
            - GB
            - DE
            - FR
            - NL
            - BE
            - CA
            - CD
          example: GB
        accountNumber:
          type: string
          description: >-
            The recipient bank account number or IBAN.
        sortCode:
          type: string
          description: >-
            The UK sort code, required for Faster Payments.
          pattern: '^\d{6}$'
        iban:
          type: string
          description: >-
            The IBAN, required for SEPA transfers.
        bic:
          type: string
          description: >-
            The BIC/SWIFT code for the recipient bank.
        email:
          type: string
          format: email
          description: >-
            The recipient email, required for Interac transfers.
        phoneNumber:
          type: string
          description: >-
            The recipient phone number, required for Mobile Money.
    Corridor:
      type: object
      properties:
        country:
          type: string
          description: >-
            The destination country name.
        countryCode:
          type: string
          description: >-
            The ISO 3166-1 alpha-2 country code.
        currency:
          type: string
          description: >-
            The destination currency code.
        paymentMethods:
          type: array
          description: >-
            The available payment methods for this corridor.
          items:
            type: string
            enum:
              - faster_payments
              - sepa
              - interac
              - bank_transfer
              - mobile_money
        maxAmount:
          type: number
          format: double
          description: >-
            The maximum payout amount per transaction in the destination
            currency.
        settlementTime:
          type: string
          description: >-
            The estimated settlement time for payouts in this corridor.
          example: 1-3 hours
    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