A workflow definition is a YAML or JSON document that declares top-level metadata, ordered steps, action keys, and runtime variables for the Workflow API.

Top-level keys

Key	Type	Required	Default	Notes
`version`	numeric `string` or `int`	No	`1`	Reserved for future schema evolution. Keep at `1`.
`name`	`string`	Yes	None	Allowed characters: letters, numbers, spaces, and `. , _ -` (regex `^[a-zA-Z0-9 .,_-]+$`).
`description`	`string`	No	`Workflow for <name>`	Free-form description shown in the dashboard.
`steps`	array of step objects	Yes	None	Must contain at least one step. The maximum step count is configurable per organization.

Step shape

Each step is an object with exactly one action key plus optional metadata.

- name: "calc_split"             # Optional, used to reference the step's output downstream.
  compute:                       # Exactly one of: send_money, compute, wait_event, get_wallet_balance.
    outputs:
      bank_share: "monetary_percent(input.net_amount, 6000)"
      wallet_share: "input.net_amount - bank_share"

The name field is optional. When set, downstream steps can reference this step's output as ${steps.<name>.output.<field>}. The allowed characters for a step name are ^[a-zA-Z_][a-zA-Z0-9_-]*$.

Action keys

A step must contain exactly one of the following:

send_money: transfer funds between PayMongo wallets and bank accounts.
compute: derive values, split amounts, run conditional logic.
wait_event: pause until an external event arrives. (Beta.)
get_wallet_balance: read the available and pending balance of a PayMongo wallet.

Minimal example

The smallest valid workflow has one step.

version: 1
name: "minimal-payout"
description: "Send PHP 200 to a bank account"
steps:
    - send_money:
        source:
            type: "wallet"
            account: "${SOURCE_WALLET_ACCOUNT}"
        destination:
            type: "bank"
            account: "${DESTINATION_ACCOUNT}"
            account_name: "Beneficiary Name"
            bic: "RCBCPHMMXXX"
        provider: "auto"
        amount: "20000"
        currency: "PHP"

Variables and chaining

Any string field accepts a ${...} reference that resolves at runtime: workflow input, an earlier step's output, or an inline expression. See Variables and Expressions for the full reference.