openapi: 3.1.0
info:
  title: Nomba Accounts Payouts 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: Payouts
  description: Endpoints for initiating and tracking cross-border payout transactions.
paths:
  /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'
components:
  schemas:
    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.
    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.
    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