Create Link

Creates a new payment link for initiating a bank transfer through open-banking.
Returns a web URL where the end-user can complete the payment through their bank’s
Strong Customer Authentication (SCA) flow.

Payment Flow Types

The type option determines how the payment link is created and the user experience:

Type

Behavior

Use Case

`link`	Returns a transportable payment link, end-user opens it in [FinqLink WebUI](api-reference/pay-apis#The-FinqLink-Pay-WebUI) to complete the payment. Offers maximum flexibility in terms of expiration and user optionality. Use this flow when generating payment links expected to be operated after a longer time. Example: an invoice sent over email which you don't expect an immediate action for.	Invoicing, QR codes
`direct_sca`	A non-transportable payment link. The API returns a native authorisation URL received from the payment provider and your application will process the redirect call from the payment provider. Available under certain custom requirements (discuss with a Finqware representative).	Mobile app-to-app experience
`wrapped_sca`	A transportable payment link for immediate usage. The authorisation URL is requested at link creation, hence there is no optionality anymore for the user to choose a different payment provider. Use this flow when (1) you know upfront all the payment details and (2) you expect immediate action from your user, as the authorisation URL may expire in minutes.	E-commerce, invoicing
`redirect_sca`	Similar to direct_sca, but handles redirects through WebUI	App-to-app UX

Payment Method Selection

Use the payment_method object as a filter to restrict the available payment methods:

Filter by specific banks (provider_id)
Filter by account type (remitter_type: retail and/or corporate)
Filter by payment rails (payment_scheme: instant, domestic, SEPA)
Filter by environment (env: sandbox, stage, prod)

The WebUI selector component will only show the payment methods that match the filter.

Example if you want to restrict your user to pay from their personal account from a list of specific banks:

{
  "payment_method": {
    "provider_id": ["bt_ro", "ing_ro", "bcr_ro"],
    "remitter_type": ["retail"],
    "env": "prod"
  }
}

Body Parameters

client_idstring Required

API client identifier

Max length

128

client_secretstring

API client secret for authentication. Required for internal (non-OAuth2) authentication mode (e.g., test-only). Not required when using OAuth2 (Bearer token) authentication.

Max length

128

single_transferobject Required

Payment intent data for a single transfer

Show child attributes

payment_methodobject

Filter to restrict available payment methods. By default, all matching methods are available to the user. Use user_editable in options to allow users to change these values.

Show child attributes

optionsobject

Configuration options for the payment link

Show child attributes

trackingobject

Tracking identifiers for billing, audit, and IBAN whitelisting purposes.

Configuration Requirements:

Both fields are optional by default, but may be required based on API client configuration
When required, the API will return a 401 error if the required tracking ID is missing

Validation Rules (applies to both fields):

Length: 1-128 characters
First character: lowercase letter (a-z) or digit (0-9)
Remaining characters: lowercase letters, digits, hyphens (-), o...

Show child attributes

Response

200

Object

Payment link created successfully

Response Attributes

request_idstring

Unique identifier for the API request

created_atstring

Timestamp when the link was created

expires_atstring

Timestamp when the link will expire

api_client_appstring

Name of the API client application

link_idstring

Internal UUID identifier for the payment link

web_idstring

Public identifier for the link (used in web URLs)

web_urlstring

URL for completing the payment.

For link/wrapped_sca types: WebUI URL
For direct_sca/redirect_sca types: Bank SCA URL

400

Object

Validation error or invalid request

Response Attributes

error_idstring Required

Unique identifier for this error instance

request_idstring Required

Request identifier for tracking and correlation

codestring Required

Machine-readable error code for 400 errors:

bad_request: Generic validation or request error
validation_error: Request payload validation failed
invalid_input: Invalid input data provided
unprocessable_entity: Valid request but cannot be processed
cooldown_failed: Data refresh cooldown period not yet elapsed
consent_not_active: Consent is not usable for this operation (e.g. expired, revoked, failed, suspended)
method_selection_error: No AIS method ma...

Enum values:

bad_requestvalidation_errorinvalid_inputunprocessable_entitycooldown_failedconsent_not_activemethod_selection_errormethod_input_validation_errorlink_expired

messagestring Required

Human-readable error message

401

Object

Authentication failed

Response Attributes

error_idstring Required

Unique identifier for this error instance

request_idstring Required

Request identifier for tracking and correlation

codestring Required

Machine-readable error code for 401 errors:

unauthorized: Authentication failed or insufficient permissions

Enum values:

unauthorized

messagestring Required

Human-readable error message

Sections

Create Link

Payment Flow Types

Payment Method Selection

Body Parameters

Response

Response Attributes

Response Attributes

Response Attributes

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

Sections

Create Link

Payment Flow Types

Payment Method Selection

Body ParametersExpand all

ResponseExpand all

Response Attributes

Response Attributes

Response Attributes

What made this section unhelpful for you?

Response

What made this section unhelpful for you?

Ask an AI

Code with AI

Body Parameters

Response