arazzo: 1.0.1
info:
  title: Cellulant Payout, Query, and Refund
  summary: Disburse a payout, query its outcome, and reverse it with a refund when the payout did not succeed.
  description: >-
    Adds an automatic reversal path to a Beep disbursement. The workflow posts a
    payout with BEEP.postPayment, queries the outcome with BEEP.queryPayment,
    and branches: when the query reports the payout pending (status code 139) it
    issues a refund with BEEP.refundPayment, and when the payout succeeded it
    ends. All three steps call the single bare postPayment operationId,
    discriminated by the function field, and inline the Beep Basic Authorization
    header alongside the payload credentials.
  version: 1.0.0
sourceDescriptions:
- name: payoutsApi
  url: ../openapi/cellulant-payouts-api-openapi.yml
  type: openapi
workflows:
- workflowId: payout-query-and-refund
  summary: Disburse a payout, query its outcome, and refund it when it did not succeed.
  description: >-
    Posts a payout, queries it, and conditionally issues a refund with
    BEEP.refundPayment when the payout is still pending.
  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.
      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 used across all three steps.
      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: postPayout
    description: >-
      Disburse the payout with function BEEP.postPayment.
    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:
      beepTransactionId: $response.body#/results/0/beepTransactionID
      postStatusCode: $response.body#/results/0/statusCode
  - stepId: queryPayout
    description: >-
      Query the payout outcome with function BEEP.queryPayment. Branch to a
      refund when the payout is still pending (status code 139); otherwise end.
    operationId: postPayment
    parameters:
    - name: Authorization
      in: header
      value: "Basic $inputs.basicAuth"
    requestBody:
      contentType: application/json
      payload:
        function: BEEP.queryPayment
        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:
      queryStatusCode: $response.body#/results/0/statusCode
      queryStatusDescription: $response.body#/results/0/statusDescription
    onSuccess:
    - name: payoutPending
      type: goto
      stepId: refundPayout
      criteria:
      - context: $response.body
        condition: $.results[0].statusCode == 139
        type: jsonpath
    - name: payoutSucceeded
      type: end
      criteria:
      - context: $response.body
        condition: $.results[0].statusCode != 139
        type: jsonpath
  - stepId: refundPayout
    description: >-
      Reverse the payout with function BEEP.refundPayment when the query
      reported it did not complete.
    operationId: postPayment
    parameters:
    - name: Authorization
      in: header
      value: "Basic $inputs.basicAuth"
    requestBody:
      contentType: application/json
      payload:
        function: BEEP.refundPayment
        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:
      refundStatusCode: $response.body#/results/0/statusCode
      refundBeepTransactionId: $response.body#/results/0/beepTransactionID
  outputs:
    beepTransactionId: $steps.postPayout.outputs.beepTransactionId
    queryStatusCode: $steps.queryPayout.outputs.queryStatusCode
    refundStatusCode: $steps.refundPayout.outputs.refundStatusCode