API docs by Redocly

Finion Capital API (1.0.1)

Download OpenAPI specification:

Finion Development: finion-dev@sportalliance.com URL: https://www.finion.dev

API Reference

The Finion Capital API offers integration for the MemberCash and Finion DirectDebit products, enabling easy transfer of direct debit runs to the bank.

Concepts

Debt Claim

Debt Claims are the heart of the domain in Finion Capital, constituting the Debt-Claim Management System and representing a single, atomic claim of money against a debtor. All debt claims against a single debtor will be summed up and collected as a single transaction from the debtor's account. Debt claim might represent different types of debt. Below, you will find a table describing the different classifications that can be designated to a debt claim.

Debt Claim Type Description
PRINCIPAL_CLAIM This debt claim type refers to the primary obligation that the debtor owes to the creditor, such as a regular payment for a service or membership. For example, this could be a 50€ monthly membership fee that a member needs to pay for access to certain services or facilities.
PURCHASE_CONTRACT This debt claim type arises from a purchase contract, where the debtor owes money for goods or products acquired. An example includes various purchases made in a studio, such as a Shake, Towel, Food, or Hardware.
FLAT_FEE A flat fee pertains to a recurring, fixed charge imposed for specific services or privileges, regardless of usage. For instance, a studio might charge a recurring administration fee for members’ entrance cards.
RECEIVABLE_FOR_SERVICES Receivables for services refer to the amount owed for additional services that were provided but not covered in the original contract. Examples include extra services like Sunbathing, Sauna, or Parking which the debtor has utilized beyond what was initially agreed upon.
### Authentication The Finion Capital API uses persistent key authentication, which is separate for each client. Keys are generated during the onboarding process. To authenticate properly, you have to send the key in the 'Authorizarion' header as bearer token, e.g. ```'Authorization' : 'Bearer YOUR_API_KEY'``` We will then validate the key and verify whether it is not only valid but also matches the current client.

Idempotency

A unique payment identifier, along with unique identifiers for individual debt claims, ensures the idempotency of the offered payment service. These identifiers are part of the PaymentIntent payload and are used to de-duplicate payments.

Payment API

Both the MemberCash and Finion DirectDebit products allow submission of payment runs that utilize the SEPA Direct Debit payment scheme. This API allows the management of the payment run submission process.

Events Webhook

Allows Finion Capital to send real-time notifications to the clients. Payload of the webhook notification is minimalistic and carries just the necessary identifiers that can be later used to collect more details via Finion Capital API. To subscribe to the webhook notifications, client needs to expose webhook endpoint as specified below. Every request made by Finion Capital will use HTTPS and will contain hash value to verify the integrity and authenticity of the request (HMAC). Table below documents available event types. The number of available types is supposed to increase over time.

Event type Description Details
PAYMENT_INTENT_STATUS_CHANGED Informs about the status changes of the submitted Payment Intent paymentReference - unique identifier for the payment
See /payments/{paymentReference}
PAYMENT_COLLECTION_DATE_CHANGED Informs about collection date changes of the submitted Payment Intent paymentReference - unique identifier for the payment
See /payments/{paymentReference}
CHARGEBACK_CREATED Informs about the creation of a chargeback chargebackReference - unique identifier for the chargeback
See /chargebacks/{chargebackReference}
MEMBER_PAYMENT_RECEIVED Informs about received member payment memberPaymentReference - unique identifier for the member payment
Authorizations:
HMAC
Request Body schema: application/json
uuid
string <uuid>

unique identifier of the notification event

accountNumber
string

account number

Array of objects (Event)

An array of notification events

Responses

Request samples

Content type
application/json
{
  • "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  • "accountNumber": "string",
  • "payload": [
    ]
}

Make a payment intent

After a basic validation of the payment parameters, all contained direct debits are asynchronously processed and a PENDING status is returned. Status-Changes of the submitted payment intent will be asynchronously communicated via the webhook-endpoint that was individually setup'd for the client. Repeated submissions of the same payment (identified by the paymentReference) are not possible and will be rejected and asynchronously communicated via the webhook.

Authorizations:
ApiKey
Request Body schema: application/json
required
paymentReference
required
string (PaymentReference) [ 0 .. 100 ] characters

Unique, stable/non-changing identifier of the PaymentIntent (e.g. UUID/GUID). The provided reference is used by the client to check the status of the payment and is also used for webhook-callbacks to inform the client about acceptance/rejection of given DebtClaims. The client must only provide this identifier once, every subsequent payment (e.g. re-submitting already-rejected DebtClaims after data-correction) is required to provide a new, different, unique paymentReference

product
required
string (Product)
Enum: "MEMBERCASH" "FINION_DIRECTDEBIT"

Finion Capital-Product

accountNumber
required
string = 8 characters [0-9]{8}

8-digit Account-Number assigned by Finion Capital to the client account that is typically a single physical location.

collectionDate
required
string <date>

Date on which the collection should occur, e.g. the SEPA Direct Debit will occur. If the date is invalid and can not be used (e.g. Sundays or special Holidays are used), Finion Capital will select the next working collection-date. If you provide 01.01.2020 for a SEPA DirectDebit Offer, Finion Capital will discard that date silently (because SEPA DirectDebit is not processable on that holiday) and instead automatically choose 02.01.2020 as collectiondate. If you provide 06.01.2020, Finion Capital will use that date for a SEPA DirectDebit

required
Array of objects (Debtor) [ 0 .. 100000 ] items

list of debtors

Responses

Request samples

Content type
application/json
{
  • "paymentReference": "33540612-6170-4a97-818d-15636ce3effe",
  • "product": "MEMBERCASH",
  • "accountNumber": "20123400",
  • "collectionDate": "2023-04-05",
  • "debtors": [
    ]
}

Response samples

Content type
application/json
{
  • "paymentReference": "33540612-6170-4a97-818d-15636ce3effe",
  • "status": "PENDING"
}

Get the result of a payment

Will stay in PENDING status until the payment has been fully accepted/rejected. If setup, the client will receive a Webhook-notification with the same payload about the status-details

Authorizations:
ApiKey
path Parameters
paymentReference
required
string (PaymentReference) [ 0 .. 100 ] characters
Example: 33540612-6170-4a97-818d-15636ce3effe

Unique, stable/non-changing identifier of the PaymentIntent (e.g. UUID/GUID). The provided reference is used by the client to check the status of the payment and is also used for webhook-callbacks to inform the client about acceptance/rejection of given DebtClaims. The client must only provide this identifier once, every subsequent payment (e.g. re-submitting already-rejected DebtClaims after data-correction) is required to provide a new, different, unique paymentReference

Responses

Response samples

Content type
application/json
{
  • "paymentReference": "58c8e533-5a7a-4c66-b0b7-763e903b4605",
  • "status": "ACCEPTED",
  • "debtClaims": [
    ]
}

Get payment execution status

Provides result of payment execution - its status and actual collection date.

Authorizations:
ApiKey
path Parameters
paymentReference
required
string (PaymentReference) [ 0 .. 100 ] characters
Example: 33540612-6170-4a97-818d-15636ce3effe

Unique, stable/non-changing identifier of the PaymentIntent (e.g. UUID/GUID). The provided reference is used by the client to check the status of the payment and is also used for webhook-callbacks to inform the client about acceptance/rejection of given DebtClaims. The client must only provide this identifier once, every subsequent payment (e.g. re-submitting already-rejected DebtClaims after data-correction) is required to provide a new, different, unique paymentReference

Responses

Response samples

Content type
application/json
{
  • "paymentReference": "58c8e533-5a7a-4c66-b0b7-763e903b4605",
  • "status": "COLLECTED",
  • "collectionDate": "2025-01-28"
}

Lists chargebacks

Returns a list of chargebacks that have been created in the system.
The returned list is sorted by the creation date in descending order.
See /payments/chargebacks/{chargebackReference} for more details on a specific chargeback.

Authorizations:
ApiKey
query Parameters
cursor
string

Cursor to paginate through the result set

size
integer <int32> <= 100

Number of items per page

createdAfter
string <date>
createdBefore
string <date>

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get a chargeback by reference

Chargebacks might be caused by various reasons that are described in the table below.

Reason Code Description
MCCB01 Chargeback created upon studio's request
MCCB02 Legal representative details are missing
MCCB03 IBAN is invalid since the last payment run
MCCB04 Closed account before collection
MCCB05 Debt claim is too old
MCCB06 Client is insolvent
MCCB07 Not specified
MCCB08 Collection of the debt was unsuccessful
MCCB09 Automatic chargeback created upon an agreement with the client
MCCB10 Chargeback of a debt claim issued in the period when a studio was closed down
MCCB11 Special agreement with the client
MCCB12 Unsuccessful collection of high risk debt claim
MCCB13 SEPA creditor ID is invalid
MCCB14 Missing reply to the enquiry


The list is supposed to grow over time as new reasons for chargebacks are identified.
In case of Finion Direct Debit, reason code and descriptions will hold SEPA reversal details as stated in EPC173-14/Version 7.0.

Authorizations:
ApiKey
path Parameters
chargebackReference
required
string (ChargebackReference) [ 0 .. 100 ] characters
Example: cb_3354061261704a97818d15636ce3effe

The reference of the chargeback to retrieve.

Responses

Response samples

Content type
application/json
{
  • "chargebackReference": "cb_3354061261704a97818d15636ce3effe",
  • "chargebackReasonCode": "AM04",
  • "chargebackReason": "Insufficient Funds",
  • "chargebackAmount": {
    },
  • "totalFeeAmount": {
    },
  • "chargebackFees": [
    ],
  • "createdAt": "2019-08-24",
  • "chargedBackDebtClaims": [
    ]
}

Get member payment

Returns SEPA details of received member payment

Authorizations:
ApiKey
path Parameters
memberPaymentReference
required
string (MemberPaymentReference) [ 0 .. 100 ] characters
Example: f8864f6d-7e22-4138-86e5-8782d42560ee

Unique, stable/non-changing technical identifier of the Member Payment.

Responses

Response samples

Content type
application/json
{
  • "issuerIban": "GB33BUKB20201555555555",
  • "issuerName": "string",
  • "amount": {
    },
  • "remittanceInfo": "string",
  • "bookingDate": "2019-08-24"
}

Dunning API

MemberCash offering includes the management of dunning runs. This API provides an overview of the status of the debt collection process.

Get status of debtor's debt

Returns the current status of the debtor's debt

Authorizations:
ApiKey
path Parameters
uniqueDebtorReference
required
string (UniqueDebtorReference) [ 0 .. 100 ] characters
Example: f8864f6d-7e22-4138-86e5-8782d42560ee

Unique, stable/non-changing technical identifier of the Debtor. The client must guarantee to keep this identifier stable over all offers, changing this identifier after the debtor was submitted for the first time is a violation of the contractual agreement with Finion Capital

Responses

Response samples

Content type
application/json
{
  • "openAmount": 0,
  • "uniqueDebtorReference": "f8864f6d-7e22-4138-86e5-8782d42560ee"
}

Re-send login link

Sends an email to a debtor with login link to payment portal where he can pay off his debt

Authorizations:
ApiKey
Request Body schema: application/json
required
uniqueDebtorReference
required
string (UniqueDebtorReference) [ 0 .. 100 ] characters

Unique, stable/non-changing technical identifier of the Debtor. The client must guarantee to keep this identifier stable over all offers, changing this identifier after the debtor was submitted for the first time is a violation of the contractual agreement with Finion Capital

Responses

Request samples

Content type
application/json
{
  • "uniqueDebtorReference": "f8864f6d-7e22-4138-86e5-8782d42560ee"
}

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "requestId": "string"
}

Contracts API

This API provides a details of a contract.

Get contract details

Returns basic parameters of the contract that is linked with the API Key used to authenticate.

Authorizations:
ApiKey

Responses

Response samples

Content type
application/json
{
  • "startDate": "2019-08-24",
  • "endDate": "2019-08-24",
  • "product": "MEMBERCASH",
  • "directDebitBankAccount": {
    },
  • "lastPaymentProcessedOn": "2019-08-24"
}

API Lifecycle & versioning

As our platform and products evolve, so too does our API. We are committed to continuous improvement, while ensuring minimal disruptions to your operations and integration efforts.

Minor Changes

Aligned with this commitment, we maintain backward compatibility for all minor updates. Any changes from version 1.x to 1.y are designed to enhance functionalities without disrupting your current integration. These backward compatible changes include extending our API with new endpoints and resources and also extending existing responses with additional data.

Major Changes

Backward-incompatible changes signify a major API update, transitioning from 1.x to 2.0. We acknowledge that such changes may necessitate adjustments to your API integration. Therefore, these changes are not made lightly.

When such an update occurs, we will ensure providing timely communication about the updates. Our team will take a proactive approach, extending their support to guide you through the transition, complete with comprehensive documentation.

Understanding that a transition period is essential for a smooth shift, we will continue supporting the old API version for six months after the deployment of the major update. This grace period ensures you have sufficient time to adapt to the new version. Following this period, the old version (1.x series) will be deprecated, totally discontinued, and will eventually become unavailable.

Changelog

v1.0.1

  • Additional payment intent status - CANCELLED

v1.0.0

  • Launched Payment API v1