What is a trigger & how you can test it

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.

Create a trigger

POST on endpoint is {baseUrl}/api/orchestration/v2/triggers

https://docs.formance.com/api-reference/orchestrationv2/create-trigger

The payload looks like this:

{
	"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"
}

Test a trigger

The reponse of a trigger test request are the values of variables defined in it.

POST on endpoint is {baseUrl}/api/orchestration/v2/triggers/{triggerID}/test

https://docs.formance.com/api-reference/orchestrationv2/test-trigger

The syntax for the filter is based on:

Language Definition | Expression language

Here is an example of filter defined on the trigger:

event.type == "PAY-IN" && event.provider == "PROVIDERID" && hasPrefix(event.rawData.merchantReference, "test") == true

Payload to be used is the payment event :

{
	"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",
			"hmacSignature":"xxx/yyyyy",
			"paymentLinkId":"XXXXXX"
		},
		"merchantReference":"XXXX",
		"originalReference":"",
		"merchantAccountCode":"XXXXX"
	},
	"metadata":{},
	"provider":"PROVIDERID",
	"createdAt":"2023-12-15T15:22:32+01:00",
	"reference":"XXXXXX",
	"connectorId":"connectorID",
	"initialAmount":4199
}

Result looks like this:

{
	"data": {
		"filter": {
			"match": true
		},
		"variables": {
			"amount": {
				"value": "4199"
			},
			"asset": {
				"value": "EUR/2"
			},
			"merchantID": {
				"value": "001"
			},
			"paymentID": {
				"value": "dummyValue"
			},
			"userID": {
				"value": "003"
			}
		}
	}
}

Webhooks

You can create webhooks to get notified from flows events, in case of failure or success:

• FAILED_TRIGGER

• FAILED_WORKFLOW

• FAILED_WORKFLOW_STAGE

• STARTED_WORKFLOW

• STARTED_WORKFLOW_STAGE

• SUCCEEDED_TRIGGER

• SUCCEEDED_WORKFLOW

• SUCCEEDED_WORKFLOW_STAGE

You’ll find the list of available events here.

stack/libs/events/generated/all.json at main · formancehq/stack