Connect a fraud workflow
Creates a workflow: a connection to a fraud screening tool that legal entity routes can then attach to a payment method, so payments on that method are screened before they are taken. Unlike a payment gateway, a workflow is served by its own handler rather than through the gateway path. A workflow has no currencies, no payment methods and no legal entity routes of its own, so it never reaches LINKED: connecting one makes the tool available to route to, and nothing more.
Where you can do this
Section titled “Where you can do this”- Merchant Setup: Entering connection details (Save)
Before you start
Section titled “Before you start”- The processor is a WORKFLOW-type integration published by a processor vendor that is active or hidden and has integrations enabled.
- The instance’s environment decides which of the integration’s sandbox or live configurations is used, and so which connection settings the tool’s connector is installed with.
- Nothing else need already exist. An instance may hold several workflows, including more than one on the same fraud tool.
| Rule | What you see |
|---|---|
| The body must carry a workflow object | VALIDATION_ERROR (400): “API body error: missing workflow object” |
| The body must not carry an id: this route only creates, and a body naming an existing workflow is treated as an edit of a record the route never loaded | NOT_FOUND (404): “workflow not found” |
| Installing a fraud tool’s connector for the first time is a change to the instance, not only to the workflow, and is refused to a session that may create workflows but not connectors | NO_PERMISSION (403): “apiValidation.error.permissions” |
| The workflow type (the connector) is mandatory on create | MANDATORY (400): “validations.paymentWorkflow.workflowType.notempty” |
| A name is mandatory; it defaults to the connector’s name, so only a connector with no name of its own can fail this | MANDATORY (400): “validations.name.notempty” |
| The reporting code must be unique across the instance’s workflows; one is generated when the body carries none | INVALID (400): “validations.reportingCode.nonunique” |
| The fraud tool’s connector must accept the settings: its own save decides, and it is not asked to test the connection first, unlike a payment gateway | the connector’s localised message |
| Merchant Setup’s form checks settings against the settings schema | form validation |
| What is stored is what the connector returns, not what was posted: a connector that answers successfully but returns no settings leaves the workflow with none | settings discarded, no error |
What happens
Section titled “What happens”- The fraud screening connection exists on the instance. Its status is CREATED when the call carried settings, or when the tool declares none; otherwise it stays at SETUP and the operator has to save the settings again before the tool will run.
- Nothing is screened yet. A workflow carries no currencies, payment methods or routes of its own and never reaches LINKED. It starts screening only once it is named on a legal entity route’s payment method (Route a payment method to a provider), and stops being called if it is later archived (Disconnect a provider).
- No webhook is raised for the workflow itself: the platform has no workflow events at all. The instance is re-saved as part of the call, so subscribers receive INSTANCE.UPDATE. No email or SMS is sent to anyone.
- The operator lands on the new provider’s screen, which shows the tool’s connection state, its account name at the tool, and its settings for editing (Update a provider’s settings).
- Nothing is created at the fraud tool itself. The call stores credentials and asks the tool to accept them; an account there has to exist already.
Who can do this
Section titled “Who can do this”- App options: Merchant Setup offers this only for a processor whose type is WORKFLOW, and only through the settings form; a single-provider deep link restricts which processor can be connected, enforced by the app’s routing rather than by the server.
- The platform form of the call,
POST /c/api/instances/{instance_key}/workflows, re-scopes the request to the named instance and runs under that instance’s own session, sopayment_workflowis checked against the instance rather than against the platform’s own session.
Related
Section titled “Related”Was this page helpful?
What went wrong?
Thanks for telling us.