Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.formance.com/llms.txt

Use this file to discover all available pages before exploring further.

A trigger is a way to fire a workflow from a payment event. The trigger is linked to a unique workflow that will be executed only if its filter condition is satisfied. If so, it will forward values from the event to the workflow in a set of configured variables corresponding to the ones expected in the workflow.

​
Creating a trigger

To create a trigger, use the Create Trigger endpoint: POST {baseUrl}/api/orchestration/v2/triggers 
{
  "event": "SAVED_PAYMENT",
  "filter": "event.type == \"PAY-IN\" && event.provider == \"ADYEN\" && hasPrefix(event.rawData.merchantReference, \"test\") == true",
  "vars": {
    "paymentID": "event.id",
    "amount": "event.amount",
    "asset": "event.asset",
    "merchantID": "'001'",
    "userID": "'003'",
    "merchantReference": "event.rawData.merchantReference"
  },
  "workflowID": "efxxxxx-xxxx-yyyy-dddd-d236abzzzzzz"
}

​
Filter syntax

The syntax for the filter is based on the expr-lang expression language. Example filter: 
event.type == "PAY-IN" && event.provider == "PROVIDERID" && hasPrefix(event.rawData.merchantReference, "test") == true

​
Testing a trigger

Before deploying a trigger to production, you can test it to verify that the filter matches correctly and that variables are extracted as expected. Use the Test Trigger endpoint: POST {baseUrl}/api/orchestration/v2/triggers/{triggerID}/test The payload should be the payment event you want to test against: 
{
  "id": "dummyValue",
  "type": "PAY-IN",
  "asset": "EUR/2",
  "amount": 4199,
  "scheme": "visa",
  "status": "SUCCEEDED",
  "rawData": {
    "amount": {
      "value": 4199,
      "currency": "EUR"
    },
    "reason": "012789:0000:03/2030",
    "success": "true",
    "eventCode": "AUTHORISATION",
    "eventDate": "2023-12-15T15:22:32+01:00",
    "operations": ["CANCEL", "CAPTURE", "REFUND"],
    "pspReference": "XXXXXXXX",
    "paymentMethod": "visa",
    "additionalData": {
      "authCode": "789789",
      "expiryDate": "03/2030",
      "cardSummary": "0000"
    },
    "merchantReference": "XXXX",
    "merchantAccountCode": "XXXXX"
  },
  "metadata": {},
  "provider": "PROVIDERID",
  "createdAt": "2023-12-15T15:22:32+01:00",
  "reference": "XXXXXX",
  "connectorId": "connectorID",
  "initialAmount": 4199
}
The response shows whether the filter matched and the extracted variable values: 
{
  "data": {
    "filter": {
      "match": true
    },
    "variables": {
      "amount": { "value": "4199" },
      "asset": { "value": "EUR/2" },
      "merchantID": { "value": "001" },
      "paymentID": { "value": "dummyValue" },
      "userID": { "value": "003" }
    }
  }
}

​
Evaluating metadata in triggers

You can use link() and get() functions to retrieve metadata from related accounts in your trigger variables and filters.

​
Accessing account metadata

To retrieve metadata from a payment’s associated account: 
{
  "event": "SAVED_PAYMENT",
  "workflowID": "xxx",
  "vars": {
    "myVar": "get(link(event, \"destination_account\").metadata, \"foo\")"
  }
}
This example retrieves the foo metadata field from the destination account linked to the payment event.

​
Webhooks

You can create webhooks to get notified of Flows events, whether they succeed or fail:
EventDescription
STARTED_WORKFLOWWorkflow instance has started
SUCCEEDED_WORKFLOWWorkflow instance completed successfully
FAILED_WORKFLOWWorkflow instance failed
STARTED_WORKFLOW_STAGEA workflow stage has started
SUCCEEDED_WORKFLOW_STAGEA workflow stage completed successfully
FAILED_WORKFLOW_STAGEA workflow stage failed
SUCCEEDED_TRIGGERTrigger fired successfully
FAILED_TRIGGERTrigger failed to fire
You can find the complete list of available events in the Formance events repository.