# 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

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](/platforms/user-guides/onboarding-connect-processor/) (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](/platforms/user-guides/rules-legal-entity-route-set-payment-method-routing/)), and stops being called if it is later archived ([Disconnect a provider](/platforms/user-guides/rules-gateway-disconnect/)).
- 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](/platforms/user-guides/rules-gateway-update/)).
- 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, so `payment_workflow` is checked against the instance rather than against the platform's own session.

### Related

- [Connect a payment processor](/platforms/user-guides/rules-gateway-connect/)
- [Disconnect a provider](/platforms/user-guides/rules-gateway-disconnect/)
- [Update a provider's settings](/platforms/user-guides/rules-gateway-update/)
- [Restore an archived provider](/platforms/user-guides/rules-gateway-restore/)
- [Route a payment method to a provider](/platforms/user-guides/rules-legal-entity-route-set-payment-method-routing/)