Implementation Guide

Getting Started

Step 1

Create a Widget link for verify and pay

Step 2

Check the failed rules

Step 3

Fetch the generated risk report

Step 1: Create the Widget link

POST https://api.finx-s.qwist.cloud/verify-and-pay

{
  "redirect_uri": "https://my-app.example.com/callback",
  "language": "de",
  "payment": {
		"creditor": {
     	"iban": "DE89370400440532013000",
      "name": "Acme GmbH"
    },
    "amount": {
      "value": 149.99,
      "currency": "EUR"
    },
    "purpose": "Invoice INV-2025-0042",
    "sepa_purpose_code": "GDDS",
		"end_to_end_reference": "5B5U3FFS9EA2LS0O"
  },
	"provider_id": "3ca31c37-986a-454e-ad64-8e97143c86bc",
  "verification_rules": {
    "account_holder": {
      "expected_name": "Maria Müller",
			"min_affinity": "HIGH"
    },
		"last_activity_within": 10
  },
	"reporting_period": 12
}

Parameters:

Parameter	Required	Description
`redirect_uri`	✅	Where the user is returned after the flow
`language`		Widget UI language. Options: `de`, `en`, `es`, `fr`, `ar`, `it`. Default: `de`
`payment.creditor.iban`	✅	IBAN of the recipient account
`payment.creditor.name`	✅	Name of the recipient (individual or business)
`payment.amount.value`	✅	Amount to transfer
`payment.amount.currency`	✅	Currency code (e.g. `"EUR"` )
`payment.purpose`	✅	Purpose text shown in the recipient's bank statement. Max 140 characters
`payment.sepa_purpose_code`		SEPA category purpose code classifying the transfer as defined in ISO 20022
`payment.end_to_end_reference`		A reference code that can be used by the creditor for further identification of the transaction
`provider_id`		Optional identifier to pre-select the financial provider, bypassing the provider search and selection step
`verification_rules.account_holder.expected_name`		The expected name of the account holder. This is the value compared to the actual account holder's name to set the affinity
`verification_rules.account_holder.min_affinity`		It is an indicator on how closely the name provided by the user matches the account-holder name provided by the bank
`verification_rules.last_activity_within`		Maximum number of days since the account had any activity
`reporting_period`		Number of the months to take into account for the account activity. By default, the last year is set (12).

Response:

{
  "location": "https://widget.qwist.cloud/?token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "id": "5e8c3f2a-9d4b-4f7e-a1c6-3b8d2e9f5a1c"
}

In the next steps you can take a look at how to handle the responses.

Step 2: Failed rules

After the predefined rules are verified, there are two possible outcomes:

The selected account matches the rules specified under the verification_rules field. The payment process then proceeds normally.
One or more of the rules are not properly covered by the account. In this case, the payment is blocked and the flow ends in a failed state.

In both cases, the user is forwarded to the redirect_uri specified in the request -either via a browser redirect or within an iframe overlay- as the final step of the flow. This URI contains several query
parameters that can be analyzed to understand the payment result:

success: A boolean -true or false- indicating if the flow completed successfully.
flow_id: The unique identifier of the flow, which can be used for subsequent lookups - e.g., fetching the risk report.
abort: A boolean -true or false- indicating if the user canceled the flow.
failed_rules: The primary parameter for diagnosing failures. It contains a comma-separated list of keys representing the predefined rules that failed during validation.

If validation succeeds, the failed_rules parameter will be empty. Conversely, if any validation rules fail, this parameter will populate with the corresponding rule identifiers.

Example: ...&failed_rules=[min_affinity,last_activity_within]

Step 3: Fetch the generated risk report

While knowing which rule failed during the Verify and Pay process is helpful, it only offers a limited view of the user's overall profile. To provide deeper context, a dedicated endpoint is available to
retrieve the complete risk report after the flow completes.

This report is generated and remains accessible regardless of the validation outcome. As the rest of the artifacts of this kind, the report will be stored and reachable during 14 days.

See Fetching the generated risk report for the endpoint and response reference.