arazzo: 1.0.1
info:
  title: Cellulant Validate and Post Payout
  summary: Validate the destination account, then post a mobile money or bank payout through the Beep platform.
  description: >-
    Reduces failed disbursements by validating the destination before sending
    value. Both steps call the single global Beep payouts endpoint, switching
    behaviour through the function discriminator — BEEP.validateAccount confirms
    the destination account is reachable, and BEEP.postPayment then disburses
    the funds. Because the spec exposes one operationId for the endpoint, both
    steps reference it as a bare operationId. Beep credentials are supplied both
    inline in the payload and as the inlined Basic Authorization header.
  version: 1.0.0
sourceDescriptions:
- name: payoutsApi
  url: ../openapi/cellulant-payouts-api-openapi.yml
  type: openapi
workflows:
- workflowId: validate-and-post-payout
  summary: Validate a destination account and then disburse a payout to it.
  description: >-
    Validates the destination account with BEEP.validateAccount and, on
    success, posts the payout with BEEP.postPayment.
  inputs:
    type: object
    required:
    - basicAuth
    - username
    - password
    - countryCode
    - serviceCode
    - msisdn
    - accountNumber
    - payerTransactionId
    - amount
    - datePaymentReceived
    - currencyCode
    properties:
      basicAuth:
        type: string
        description: Base64-encoded Beep Basic auth credentials for the Authorization header.
      username:
        type: string
        description: Beep payload credential username.
      password:
        type: string
        description: Beep payload credential password.
      countryCode:
        type: string
        description: ISO 3166-1 alpha-2 country code (KE, GH, TZ, UG, NG, ...).
      serviceCode:
        type: string
        description: Beep service code identifying the payout rail.
      msisdn:
        type: string
        description: Customer mobile number with country code.
      accountNumber:
        type: string
        description: Destination account number.
      payerTransactionId:
        type: string
        description: Unique merchant payer transaction id.
      amount:
        type: number
        description: Payout amount.
      datePaymentReceived:
        type: string
        description: Payment received timestamp (yyyy-mm-dd hh:mm:ss).
      currencyCode:
        type: string
        description: Currency code for the payout.
      narration:
        type: string
        description: Free-text narration for the payout.
      paymentMode:
        type: string
        description: Payment mode (ATM, Mobile, Bank, Card, Cash).
      callbackUrl:
        type: string
        description: URL Beep posts the delivery callback to.
  steps:
  - stepId: validateAccount
    description: >-
      Confirm the destination account is reachable before disbursing by calling
      the Beep endpoint with function BEEP.validateAccount.
    operationId: postPayment
    parameters:
    - name: Authorization
      in: header
      value: "Basic $inputs.basicAuth"
    requestBody:
      contentType: application/json
      payload:
        function: BEEP.validateAccount
        countryCode: $inputs.countryCode
        payload:
          credentials:
            username: $inputs.username
            password: $inputs.password
          packet:
            serviceCode: $inputs.serviceCode
            MSISDN: $inputs.msisdn
            accountNumber: $inputs.accountNumber
            payerTransactionID: $inputs.payerTransactionId
            amount: $inputs.amount
            datePaymentReceived: $inputs.datePaymentReceived
            currencyCode: $inputs.currencyCode
            countryCode: $inputs.countryCode
    successCriteria:
    - condition: $statusCode == 200
    - condition: $response.body#/authStatus/authStatusCode == 131
    outputs:
      authStatusCode: $response.body#/authStatus/authStatusCode
  - stepId: postPayout
    description: >-
      Disburse the payout to the validated account with function
      BEEP.postPayment. The platform accepts the payout asynchronously and fires
      delivery callbacks to the configured callback URL.
    operationId: postPayment
    parameters:
    - name: Authorization
      in: header
      value: "Basic $inputs.basicAuth"
    requestBody:
      contentType: application/json
      payload:
        function: BEEP.postPayment
        countryCode: $inputs.countryCode
        payload:
          credentials:
            username: $inputs.username
            password: $inputs.password
          packet:
            serviceCode: $inputs.serviceCode
            MSISDN: $inputs.msisdn
            accountNumber: $inputs.accountNumber
            payerTransactionID: $inputs.payerTransactionId
            amount: $inputs.amount
            datePaymentReceived: $inputs.datePaymentReceived
            currencyCode: $inputs.currencyCode
            countryCode: $inputs.countryCode
            narration: $inputs.narration
            paymentMode: $inputs.paymentMode
            extraData:
              callbackUrl: $inputs.callbackUrl
              pushToOriginator: true
    successCriteria:
    - condition: $statusCode == 200
    - condition: $response.body#/authStatus/authStatusCode == 131
    outputs:
      authStatusCode: $response.body#/authStatus/authStatusCode
      results: $response.body#/results
      beepTransactionId: $response.body#/results/0/beepTransactionID
      paymentStatusCode: $response.body#/results/0/statusCode
  outputs:
    validationAuthStatusCode: $steps.validateAccount.outputs.authStatusCode
    beepTransactionId: $steps.postPayout.outputs.beepTransactionId
    paymentStatusCode: $steps.postPayout.outputs.paymentStatusCode