Flutterwave Wallet Balance Guarded Payout

arazzo: 1.0.1
info:
  title: Flutterwave Wallet Balance Guarded Payout
  summary: Check a currency wallet balance, then only send a transfer to an existing recipient when funds are sufficient.
  description: >-
    A funds-guarded disbursement flow. The workflow fetches the available
    balance for a currency wallet and branches: when the available balance is
    high enough it initiates a transfer to an existing recipient and verifies
    the payout status, and when it is not it ends without moving money. This
    prevents failed payouts caused by an underfunded wallet. Every step spells
    out its request inline so the flow can be read and executed without opening
    the underlying OpenAPI description.
  version: 1.0.0
sourceDescriptions:
- name: transfersApi
  url: ../openapi/flutterwave-transfers-api-openapi.yml
  type: openapi
- name: walletsApi
  url: ../openapi/flutterwave-wallets-api-openapi.yml
  type: openapi
workflows:
- workflowId: wallet-balance-guarded-payout
  summary: Verify wallet funds are sufficient, then send and verify a transfer.
  description: >-
    Fetches the currency wallet balance, branches to a transfer only when the
    available balance covers the amount, then verifies the transfer status.
  inputs:
    type: object
    required:
    - accessToken
    - currency
    - amount
    - recipientId
    properties:
      accessToken:
        type: string
        description: OAuth2 client-credentials bearer token for the Authorization header.
      currency:
        type: string
        description: Currency wallet to check and pay out from (e.g. NGN).
      amount:
        type: number
        description: Amount to transfer in the major currency unit.
      recipientId:
        type: string
        description: Identifier of an existing recipient to pay out to.
      narration:
        type: string
        description: Optional narration shown on the payout.
  steps:
  - stepId: checkBalance
    description: Fetch the available balance for the currency wallet.
    operationId: getWalletBalance
    parameters:
    - name: Authorization
      in: header
      value: "Bearer $inputs.accessToken"
    - name: currency
      in: path
      value: $inputs.currency
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      availableBalance: $response.body#/available_balance
    onSuccess:
    - name: sufficientFunds
      type: goto
      stepId: createTransfer
      criteria:
      - context: $response.body
        condition: $.available_balance >= $inputs.amount
        type: jsonpath
    - name: insufficientFunds
      type: end
      criteria:
      - context: $response.body
        condition: $.available_balance < $inputs.amount
        type: jsonpath
  - stepId: createTransfer
    description: Initiate the transfer once funds are confirmed sufficient.
    operationId: createTransfer
    parameters:
    - name: Authorization
      in: header
      value: "Bearer $inputs.accessToken"
    requestBody:
      contentType: application/json
      payload:
        amount: $inputs.amount
        currency: $inputs.currency
        recipient_id: $inputs.recipientId
        narration: $inputs.narration
    successCriteria:
    - condition: $statusCode == 201
    outputs:
      transferId: $response.body#/id
  - stepId: verifyTransfer
    description: Retrieve the transfer to confirm its final status.
    operationId: getTransfer
    parameters:
    - name: Authorization
      in: header
      value: "Bearer $inputs.accessToken"
    - name: id
      in: path
      value: $steps.createTransfer.outputs.transferId
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      transferStatus: $response.body#/status
    onSuccess:
    - name: transferSucceeded
      type: end
      criteria:
      - context: $response.body
        condition: $.status == "succeeded"
        type: jsonpath
    - name: transferFailed
      type: end
      criteria:
      - context: $response.body
        condition: $.status == "failed"
        type: jsonpath
  outputs:
    availableBalance: $steps.checkBalance.outputs.availableBalance
    transferId: $steps.createTransfer.outputs.transferId
    transferStatus: $steps.verifyTransfer.outputs.transferStatus