API Reference

Endpoint

POST /v1/payments/user-session

Request Body application/json

required

Request to initiate a user session for payments.

amount required

Specifies the payment amount for the initiated transaction. Should equal 0 to capture a payment instrument for future recurring payments. The currency is defined by the studio.

Example: 19.99

scope required

Specifies where the created payment instruments will be used, as the available payment methods differ by scope.

Allowed values:

`MEMBER_ACCOUNT`	Use when initiating a payment user session to collect a payment instrument intended for future payment runs (e.g., BACS, credit card).
`ECOM`	Use when the user is making a purchase or when the payment instrument will be used for future user-initiated payments (e.g., saving a credit card for later purchases).

Example: "MEMBER_ACCOUNT"

customerId integer(int64)

This field represents the unique identifier for an existing customer within ERP. Providing this ID ensures the payment session is linked to the correct customer record. It is a mutually exclusive field with `finionPayCustomerId`, meaning you can only provide one or the other. - **Conditions for use**: This ID is required for payment sessions involving existing customers. - **Behavior when omitted**: If this field is left empty, a new customer will be treated as a “potential customer” and a `finionPayCustomerId` will be automatically generated and returned in the response. If omitted, it will not be possible to use it for existing customers. - **Mutually exclusive with**: `finionPayCustomerId`

Example: 1234567890

finionPayCustomerId string(uuid)

This field is the identifier for a customer within the Finion Pay payment service, typically used for customers who are not yet registered in ERP. Use this ID to track repeat payment sessions for a potential customer. - **Conditions for use**: This ID should only be provided for subsequent payment sessions for a customer who has been previously identified by Finion Pay but doesn’t have an ERP `customerId` yet. - **Behavior when omitted**: In the absence of a `customerId`, a new `finionPayCustomerId` will be automatically created and assigned to the user for the current session. - **Mutually exclusive with**: `customerId`

Example: "753ea8ec-c2ec-4761-824b-bc46eda3f644"

permittedPaymentChoices array[object]

List of permitted payment choices, i.e. obtained by the contract offer. Acts as a filter for the available payment methods defined by the scope

referenceText required

Allows the definition of the reference text shown on the bank statement of the customer.

Example: "Gym Joining Fee 01.07.2025"

requireDirectDebitSignature

When set to true the direct debit form will show a signature field to the user that is required to proceed. This applies to the payment methods SEPA, CH_DD and LSV.

Example: false

showExistingPaymentInstruments

When set to true the UPC component will also fetch the user's existing payment instruments. Default is true

Example: true

Responses

Response Body application/json

Response containing the user session token and its validity period for payments.

token required

The token for the user session.

Example: "CllClFmVlSCs3oe0ND0JloLWlNzdb3QseU4507gf1mSVAHqRTwzKWU"

tokenValidUntil string(date-time) required

The date and time until the token is valid.

Example: "2025-01-07T16:25:09.416924Z"

finionPayCustomerId string(uuid) required

Identifies a customer in Finion Pay, i.e. to retreive existing payment instruments.

Example: "753ea8ec-c2ec-4761-824b-bc46eda3f644"

Validation of the request failed.

Response Body application/json

Error data

errorMessage required

Resolved message in the context-specific default locale

errorCode

Key for translation files

traceId

Datadog trace id

args array[object] deprecated

Arguments referenced by format specifiers while resolving the message from translation files

typedArgs array[object] deprecated

Same as `args` but with type information

value

type

Allowed values:

TIMESTAMP BOOLEAN DATE MONTH_DAY TIME TERM TERM_LIST INTEGER DECIMAL STRING MONEY LIMITABLE_CONFIG_PROPERTY I18N_KEY I18N_KEY_LIST PERMISSION_LIST ENUM AVAILABILITY_LIST

reference

Reference to validation error

Example: "parent.child"

Authentication failed. No api-key, wrong api-key or wrong header name.

Response Body application/json

Error data

errorMessage required

Resolved message in the context-specific default locale

errorCode

Key for translation files

traceId

Datadog trace id

args array[object] deprecated

Arguments referenced by format specifiers while resolving the message from translation files

typedArgs array[object] deprecated

Same as `args` but with type information

value

type

Allowed values:

reference

Reference to validation error

Example: "parent.child"

Authorization failed. The caller has no privilege to the given resource.

Response Body application/json

Error data

errorMessage required

Resolved message in the context-specific default locale

errorCode

Key for translation files

traceId

Datadog trace id

args array[object] deprecated

Arguments referenced by format specifiers while resolving the message from translation files

typedArgs array[object] deprecated

Same as `args` but with type information

value

type

Allowed values:

reference

Reference to validation error

Example: "parent.child"

Entity does not exists.

Response Body application/json

Error data

errorMessage required

Resolved message in the context-specific default locale

errorCode

Key for translation files

traceId

Datadog trace id

args array[object] deprecated

Arguments referenced by format specifiers while resolving the message from translation files

typedArgs array[object] deprecated

Same as `args` but with type information

value

type

Allowed values:

reference

Reference to validation error

Example: "parent.child"

Concurrent modification detected. The entity was modified by another request.

Response Body application/json

Error data

errorMessage required

Resolved message in the context-specific default locale

errorCode

Key for translation files

traceId

Datadog trace id

args array[object] deprecated

Arguments referenced by format specifiers while resolving the message from translation files

typedArgs array[object] deprecated

Same as `args` but with type information

value

type

Allowed values:

reference

Reference to validation error

Example: "parent.child"

Access denied - rate limit is exceeded.

Response Body application/json

Error data

errorMessage required

Resolved message in the context-specific default locale

errorCode

Key for translation files

traceId

Datadog trace id

args array[object] deprecated

Arguments referenced by format specifiers while resolving the message from translation files

typedArgs array[object] deprecated

Same as `args` but with type information

value

type

Allowed values:

reference

Reference to validation error

Example: "parent.child"

Unexpected system error.

Response Body application/json

Error data

errorMessage required

Resolved message in the context-specific default locale

errorCode

Key for translation files

traceId

Datadog trace id

args array[object] deprecated

Arguments referenced by format specifiers while resolving the message from translation files

typedArgs array[object] deprecated

Same as `args` but with type information

value

type

Allowed values:

reference

Reference to validation error

Example: "parent.child"