PayMongo HomeGuidesAPI ReferenceStart Building
Guides

Quickstart

Create your first Workflow API workflow, attach a schedule trigger, inspect the run, and clean up the trigger.


This walkthrough takes about five minutes. By the end you will have created a workflow, attached a schedule trigger that fires it once, and inspected the resulting instance.

Prerequisites

  • A PayMongo organization ID (org_...).
  • A test-mode secret key (sk_test_...).
  • A test-mode PayMongo wallet with available balance.
  • The two headers explained on the Authentication page (Authorization: Basic ${YOUR_BASIC_TOKEN} and Organization-Id: ${YOUR_ORG_ID}).

Step 1: Define a workflow

Create a one-step workflow that sends PHP 10 from one test-mode wallet to another. Note that amounts are in centavos, so PHP 10 is "1000".

curl --request POST 'https://workflow-api.paymongo.com/v1/workflows' \
  --header 'Authorization: Basic ${YOUR_BASIC_TOKEN}' \
  --header 'Organization-Id: ${YOUR_ORG_ID}' \
  --header 'Content-Type: text/plain' \
  --data 'version: 1
name: "quickstart-workflow"
description: "Workflow API quickstart"
steps:
    - send_money:
        source:
            type: "wallet"
            account: "775447521930"
            account_name: "Source Wallet"
        destination:
            type: "wallet"
            account: "775447521931"
            account_name: "Destination Wallet"
            bic: "PAEYPHM2XXX"
        provider: "paymongo"
        amount: "1000"
        currency: "PHP"
        notes: "Quickstart"'

Replace the wallet account numbers with your own test-mode wallet IDs. The response returns the persisted workflow:

{
  "id": "wf_abc123...",
  "name": "quickstart-workflow",
  "description": "Workflow API quickstart",
  "version": 1,
  "definition": "...",
  "created_at": "...",
  "updated_at": "..."
}

Capture the id. Step 2 uses it.

Step 2: Create a trigger

The Workflow API does not run a workflow until something triggers it. The two trigger types are event-based (a PayMongo event fires) and schedule-based (a cron expression). For this walkthrough, use a schedule trigger that fires every minute.

curl --request POST 'https://workflow-api.paymongo.com/v1/triggers' \
  --header 'Authorization: Basic ${YOUR_BASIC_TOKEN}' \
  --header 'Organization-Id: ${YOUR_ORG_ID}' \
  --header 'Content-Type: application/json' \
  --data '{
    "workflow_id": "wf_abc123...",
    "condition": {
      "schedule": "* * * * *"
    }
  }'

The response returns the trigger:

{
  "id": "trg_xyz456...",
  "workflow_id": "wf_abc123...",
  "condition": {"schedule": "* * * * *"},
  "state": "active",
  "created_at": "..."
}

Capture the trigger id for Step 4.

Step 3: See the instance start

Wait up to one minute. The trigger fires and starts a new workflow instance. List instances for this workflow:

curl --request GET 'https://workflow-api.paymongo.com/v1/instances?workflow_id=wf_abc123...' \
  --header 'Authorization: Basic ${YOUR_BASIC_TOKEN}' \
  --header 'Organization-Id: ${YOUR_ORG_ID}'

You should see at least one instance with status: "running" or status: "completed". Capture the instance id.

Step 4: Read the instance

Fetch the full instance state, including current step status and outputs:

curl --request GET 'https://workflow-api.paymongo.com/v1/instances/inst_xyz789...' \
  --header 'Authorization: Basic ${YOUR_BASIC_TOKEN}' \
  --header 'Organization-Id: ${YOUR_ORG_ID}'

A completed run looks like:

{
  "id": "inst_xyz789...",
  "workflow_id": "wf_abc123...",
  "status": "completed",
  "output": {
    "steps_executed": 1,
    "step_outputs": [
      {
        "status": "completed",
        "transfer_id": "tr_...",
        "transaction_id": "txn_..."
      }
    ]
  }
}

Step 5: Clean up

Because the trigger fires every minute, delete it now to avoid further runs:

curl --request DELETE 'https://workflow-api.paymongo.com/v1/triggers/trg_xyz456...' \
  --header 'Authorization: Basic ${YOUR_BASIC_TOKEN}' \
  --header 'Organization-Id: ${YOUR_ORG_ID}'

Next steps

Updated about 5 hours ago