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
- Merchant Setup: Entering connection details (Save)
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.
Rules
Checked by the API means Shuttle refuses the request however it is sent; a screen name means only that screen refuses it, and a direct API call would be accepted.
| Rule | Checked by | What you see |
|---|---|---|
| The body must carry a workflow object | The API | 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 | The API | 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 | The API | NO_PERMISSION (403): "apiValidation.error.permissions" |
| The workflow type (the connector) is mandatory on create | The API | 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 | The API | MANDATORY (400): "validations.name.notempty" |
| The reporting code must be unique across the instance's workflows; one is generated when the body carries none | The API | 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 API | the connector's localised message |
| Settings are not validated against the settings schema server-side; Merchant Setup's form is the only check | Merchant Setup screen | 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 | The API | settings discarded, no error |
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
- 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
Updated 10 minutes ago
Did this page help you?