Decoupled cards for consumers

Solaris' Decoupled Cards enable customers to benefit from a modern debit card without opening a new bank account or manually transferring funds to use the card to make purchases.

This guide explains the integration process of decoupled cards for consumers, including the key concepts and the necessary endpoints for creating, activating, and servicing decoupled cards .

Introduction

Product specifications

A decoupled card is a debit card with an attached credit limit set according to a risk-based scoring system and linked to the customer's external bank account (i.e., the reference account). Customers can use the available limit to make purchases using the card. The negative balance is settled daily from the customer's external reference account via SEPA Direct Debit (SDD).

Decoupled cards are subject to account and transaction fees, and they can be issued in physical or virtual form. They are currently available to retail customers in Germany with a limit from EUR 100 to EUR 1,000, depending on the customer's credit score.

User journey

A decoupled card combines a card, account, and credit limit. The user journey looks as follows:

1. The customer applies for a decoupled card with Solaris and agrees to the terms and conditions, credit checks, and account snapshot.
2. After passing the credit checks stage, the customer is offered a decoupled card with a specific credit limit (i.e., an overdraft limit).
3. The customer goes through the customer identification process (KYC).

4. After a successful identification, you will create an internal bank account (with type DECOUPLED_CARD_PERSONAL) for the customer. The offered credit limit is attached to this account and linked to the associated debit card.

   • Note This account is only used in the context of a decoupled card and is not considered a full payments account.
5. The customer specifies an external reference account and signs a SEPA Direct Debit (SDD) mandate, which authorizes Solaris to debit the reference account with an SDD whenever the decoupled card credit limit is used. The SDD amount equals the used amount.
6. Whenever the customer uses the card credit limit to make a purchase or withdrawal, the internal account balance goes negative. Afterward, an SDD of the used amount will be debited from the reference account on the same day and transferred to the customer's internal account to settle the negative balance.

The following diagram gives a general overview of the decoupled cards onboarding process:

Credit scoring

Solaris uses an automated credit scorer to analyze and score consumer decoupled card applications. The credit scorer uses different information to score applications, including credit records, account snapshots, and other necessary information.

The scorer performs different credit checks throughout the application lifecycle, such as:

• Initial scoring: Checks the credit record obtained from external credit bureaus, such as SCHUFA.
• Verification: Checks the account snapshot to verify the financial information provided in the decoupled card application.

Accounts

A decoupled card involves different bank accounts:

1. Reference account: The customer's external bank account from which the SDD is pulled to settle the internal account balance when the customer makes purchases with the decoupled card.

   • Note: Customers can have multiple reference accounts tied to their decoupled card. Consult your Partner Manager for more information about setting up multiple reference accounts.
2. Internal account: An internal Solaris account created for a decoupled card. The overdraft (i.e., the credit limit available on the card) is attached to this account. Solaris credits the funds from the customer's reference account to this account via SDD to settle any negative balance.

3. (Optional) Round-up account: The customer can opt for a round-up account associated with the decoupled card. The customer specifies a round-up amount for each purchase (e.g., rounding up the purchase amount to the nearest value). In this case, the SDD includes the purchase amount (transferred to the internal account) and the round-up amount (transferred to the round-up account).

   • Note: This account can only be used in the manual SDD orchestration setup.

Decoupled card usage

The customer can use the decoupled card for the following use cases:

• Card payments and ATM cash withdrawals using the credit limit available on the internal account.
• Topping up the card's account with cash by transferring money from their external reference account to the internal card account.
• Transferring any positive balance on the card's account back to their reference account.

SDD orchestration

Solaris uses SEPA Direct Debit (SDD) to settle the internal account balance from the customer's external reference account. The SDD amount equals the amount the customer used from the card's credit limit.

Depending on your needs, you can choose between two options for how the SDD should be orchestrated:

• Automatic SDD orchestration: In this setup, Solaris handles the money flow between the reference account and the internal account. The SDD is triggered automatically each day for any negative balance. You do not need to implement any endpoints.
• Manual SDD orchestration: In this setup, you can have more control over when the SDD is triggered and the amount to be debited from the customer's reference account. However, this setup requires additional configurations. Consult your Partner Manager for more information.

System prerequisites

Before starting the onboarding process, please implement the following prerequisites:

1. Technical setup:

Set up your environment and get your authentication keys. For step-by-step instructions, check the Technical setup guide.

2. Legal and compliance screens:

Build the necessary legal and compliance screens in your sign-up flow to collect your customers' consent to the necessary legal and compliance requirements. The Legal and compliance screens guide contains step-by-step instructions on how to create these screens and what they must contain.

The following screens are required to onboard B2C and freelancer customers for Digital Banking & Cards:

1. Terms and Conditions
2. Customer information
3. Economic interest
4. Person tax information (Only for customers in Germany)
5. FATCA indication
6. Self-declaration as a politically exposed person (PEP). (Only for customers in France, Italy, and Spain)
7. Compliance screen

Record the customer's consent on each screen as a UTC timestamp (e.g., 2019-01-01T00:00:00Z). Afterward, you must pass each timestamp in its respective field to Solaris.

• Collect the customer's consent to Solaris's Terms and Conditions and store the timestamp in the terms_conditions_signed_at field.
• Collect the customer's consent to data processing and store the timestamp in the data_terms_signed_at field.
• Collect the customer's economic interest declaration and store the timestamp in the own_economic_interest_signed_at field.
• Collect the customer's FATCA indication and store it in the fatca_relevant field. Store the timestamp in the fatca_crs_confirmed_at field.

Integration overview

Onboard retail customers for decoupled cards by completing the following steps:

You can find details descriptions of these steps and their related endpoints in the following sections.

Webhooks

Solaris recommends subscribing to the following webhook events to better automate your processes. For detailed instructions on implementing Solaris webhooks, check the webhooks documentation.

• ACCOUNT_BLOCK
• ACCOUNT_CLOSURE
• ACCOUNT_CLOSURE_REQUEST
• BOOKING
• CARD_LIFECYCLE_EVENT
• CARD_AUTHORIZATION
• CARD_AUTHORIZATION_DECLINE_V2
• CARD_AUTHORIZATION_RESOLUTION
• CARD_FRAUD_CASE_PENDING
• CARD_FRAUD_CASE_TIMEOUT
• IDENTIFICATION
• PERSON_CHANGED
• PERSON_DELETED
• PERSON_SEIZURE_CREATED
• PERSON_SEIZURE_DELETED
• PERSON_SEIZURE_FULFILLED
• PERSON_SEIZURE_UPDATED
• PERSON_MOBILE_NUMBER_CREATED
• PERSON_MOBILE_NUMBER_DELETED
• PERSON_TAX_IDENTIFICATION_CHANGED
• POSTBOX_ITEM_CREATED
• POTENTIAL_ACCOUNT_BLOCKING
• SCA_CHALLENGE

• ACCOUNT_LIMIT_CHANGE
• ACCOUNT_SNAPSHOT
• SDD_COLLECTION_APPLICATION

Mandatory features

You must integrate all the mandatory features for Digital Banking & Cards highlighted in the Onboarding requirements guide before going live with your solution.

Step 1: Collect customer data and create person resource

In this step, you must collect the mandatory data points from the customer in your sign-up flow, including all the timestamps of the customer's consent to the legal and compliance screens.

Afterward, pass all the data points to Solaris by creating a person resource to represent your customer.

API reference

For a complete list of endpoints, properties, and examples related to the person resource, visit the following links:

• Person resource API reference:

  • POST Create person
  • GET Retrieve a person
  • PATCH Update person

Related webhook events

• PERSON_CHANGED
• PERSON_DELETED

POST Create person

Call this endpoint to create a person resource for your customer, and add the following mandatory data points in the request body:

Mandatory data points for retail customers in Germany

• salutation
• first_name
• last_name

• address

  • line_1
  • line_2
  • postal_code
  • city
  • country
• mobile_number: This field is only used to pass the mobile number to our KYC provider IDnow for the Videoident KYC flow. To create and verify a mobile number for your customer, you need to use the dedicated mobile number endpoints.
• birth_date
• birth_city
• birth_country
• nationality
• employment_status
• fatca_relevant
• fatca_crs_confirmed_at
• terms_conditions_signed_at
• data_terms_signed_at
• own_economic_interest_signed_at

• tax_information

  • marital_status

Request URL

POST /v1/persons

Click here to view the full API reference.

PATCH update person

This endpoint updates one or more properties on a person resource. You can only update the following properties using this endpoint:

• title
• salutation
• address (line_1, line_2, postal_code, city, state, country)
• contact_address (line_1, line_2, postal_code, city, state, country)
• employment_status
• job_title
• email
• tax_information (tax_assessment, marital_status)
• fatca_relevant
• fatca_crs_confirmed_at
• business_purpose
• industry
• industry_key
• own_economic_interest_signed_at
• aml_confirmed_on (only with today or tomorrow's date)
• expected_monthly_revenue_cents
• vat_number
• website_social_media
• business_trading_name
• nace_code
• business_address_line_1
• business_address_line_2
• business_postal_code
• business_city
• business_country
• annual_income_range
• data_terms_signed_at
• branch
• birth_province
• birth_post_code
• socioprofessional_category
• purpose_of_account_opening
• main_income_source
• work_country
• work_province
• self_declared_as_pep
• international_operativity_expectation
• registration_number

Request URL

PATCH /v1/persons/{id}

Click here to view the full API reference

Step 2: Create and verify mobile number

In this step, collect the customer's mobile number in your sign-up flow and then create a mobile number resource and verify it by sending an SMS OTP to the customer's mobile number. Afterward, the customer enters the received OTP in your frontend to verify their number.

Mobile number resource

Creating and verifying a mobile number for your customer is a crucial step in the customer onboarding process. With a verified mobile number, customers can use SMS OTPs to complete two-factor authentication (2FA) challenges, which is a requirement for Strong Customer Authentication (SCA).

API reference

Visit the following link to find all the endpoints related to the mobile number resource, including related properties and examples.

• Mobile number resource API reference

Related webhook events

• PERSON_MOBILE_NUMBER_CREATED
• PERSON_MOBILE_NUMBER_DELETED

POST Create mobile number

Collect the customer's mobile number and pass it to Solaris using the following API call, and include the customer's person_id in the request URL.

Request example:

POST /v1/persons/{person_id}/mobile_number
{
  "number": "+15550101"
}

Response example:

The API returns a mobile_number resource with a unique id and attaches it to the person resource.

{
    "id": "91e4d939d781b8eb30d1ee86809761c2cmno",
    "number": "+15550101",
    "verified": false
}

Click here to view the full API reference.

POST Authorize mobile number

Use the following endpoint to verify the ownership of the provided mobile phone number. The endpoint initiates a one-time-password (OTP) flow: Solaris sends a six-digit OTP to the customer's number, and then they must enter it in your UI.

Request example:

POST /v1/persons/{person_id}/mobile_number/authorize
{
  "number": "+15550101"
}

Response example:

{
    "id": "91e4d939d781b8eb30d1ee86809761c2cmno",
    "number": "+15550101",
    "verified": false
}

Click here to view the full API reference..

POST Confirm mobile number

Use this endpoint to submit the SMS OTP the customer received on their mobile number to finalize the mobile number authorization process. You must add the customer's number and token (i.e., the SMS OTP) in the request body. Afterward, the mobile number will be verified and can be used in the context of Strong Customer Authentication (SCA).

Request example:

POST /v1/persons/{person_id}/mobile_number/confirm
{
  "number": "+15550101",
  "token": "212212"
}

Response example:

{
    "id": "91e4d939d781b8eb30d1ee86809761c2cmno",
    "number": "+15550101",
    "verified": true
}

Click here to view the full API reference.

Mobile number management

For more information about how to manage mobile numbers, check the related guide.

Step 3: Create customer tax identification

In this step, collect the relevant tax information from the customer and create a tax identification resource for them.

API reference

For a complete list of endpoints, properties, and examples related to the person tax identification resource, visit the following links:

• Person tax identifications API reference:

  • POST Create person tax identification
  • GET Retrieve person tax identification
  • PATCH Update person tax identification

Related webhook events

• PERSON_TAX_IDENTIFICATION_CHANGED

POST Create person tax identification

Call this endpoint to create a person tax identification for the customer with the person_id specified in the request URL. Collect the following tax information from your customers and pass them to Solaris in the request body:

• number
• country
• primary

If the customer has not submitted their TIN to your solution yet (i.e., the value of number is null), then include the following properties in the request:

• reason_no_tin: Possible values are NOT_ASSIGNED_YET, NOT_ASSIGNED_BY_COUNTRY, OTHER.
• reason_description: Applies only if the reason_no_tin is OTHER.
• tax_id_type: (Only for Spain) Possible values are NIE and NIF.

Request example:

POST /v1/persons/{person_id}/tax_identifications

Click here to view the full API reference.

Tax ID testing data

You can use the following test values for the TIN to test these endpoints on Sandbox:

Step 4: Create person credit record

In this step, you must create a consumer credit record and link it to the person resource of the relevant customer.

What is a credit record?

The credit record contains the customer's credit data and history. Creating a credit record is usually required in lending products integrations as it's used for credit scoring to determine the customer's creditworthiness and eligibility.

Integrate the following endpoints to create credit records for your retail customers.

API reference

Visit the following link to find all the endpoints related to the credit record resource, including related properties and examples.

• Credit record resource API reference

To create a credit record for your customer, you can use one of the following endpoints depending on your customer type. You can create a credit record in two ways:

1. Via Solaris:

To create a credit record via Solaris, set the source field to solarisBank in the request body and Solaris will pull the customer's record directly from SCHUFA.

2. Manual upload:

In this case, you will collect the credit record manually through SCHUFA and/or other third-party service providers and upload the file to Solaris. Set the source field to partner and include the file content in the file field (Base64-encoded).

POST Create a credit record for a retail customer

Request URL

POST /v1/persons/{person_id}/credit_records

Click here to view the full API reference

POST Create a credit record for a freelancer

Request URL

POST /v1/freelancers/persons/{person_id}/credit_records

Click here to view the full API reference

GET Retrieve a credit record

This endpoint returns the information about a customer's existing credit record, including the status and validity of the credit record. Add the person_id and the credit_record_id in the request URL. If the status of the credit record is expired, you must create a new one for the customer.

Request URL

GET /v1/persons/{person_id}/credit_records/{credit_record_id}

Click here to view the full API reference

Step 5: Create SDD collection application

In this step, you must create a SEPA Direct Debit (SDD) collection application for the customer and include the credit record ID created in the previous step.

POST Create SDD collection application

This endpoint creates an SDD collection application and assigns it to the person with the person_id specified in the request URL. In addition, you must include the credit_record_id you created in the previous step in the request body.

Request URL

//POST /persons/{person_id}/sdd_collection_applications
{
  "credit_record_id": "fbb7d15fa4c54ba0b077592665ef04a4ccrd"
}

The API will return an object containing a unique ID for the SDD collection application as well as the application's status, which is initially set to initial_scoring_pending. You must use this id in later API calls as the value of sdd_collection_application_id.

Scoring

This API call automatically triggers the credit scoring system, which scores the application and credit record and provides its decision in the decision field.

Rejected application

In case of rejection, the application status changes to rejected and decision will be set to REJECTED. You must abort the onboarding process in this case.

Approved application

If Solaris' scorer approves the SDD application, the application status changes to account_snapshot_pending and the decision value will change to OFFERED. Afterward, you can proceed to Step 6 to create an account snapshot.

Click here to view the full API reference.

GET Retrieve customer SDD collection application

Call this endpoint to retrieve a customer's SDD application and track the application lifecycle through the status field. Additionally, subscribe to the webhook event SDD_COLLECTION_APPLICATION to receive status updates about the application.

Check the appendix for a list of possible values and descriptions for the status field. Additionally, check the application status flow here.

Request URL

GET /persons/{person_id}/sdd_collection_applications/{sdd_collection_application_id}

Click here to view the full API reference.

Application status flow

The following diagram describes the status flow of an SDD application:

Step 6: Create account snapshot

Once the application status changes to account_snapshot_pending, you need to create an account snapshot for the customer and link it to their SDD collection application.

What is an account snapshot?

The account snapshot contains a breakdown of the customer's account information, such as balance, transactions, bookings, and recurrent repayment amounts over a certain period of time. Creating an account snapshot is usually required in lending products integrations as it's used for credit scoring to verify the customer's financial data.

Integrate the following endpoints to create account snapshots for your customers.

API reference

Visit the following link to find all the endpoints related to the account snapshot resource, including related properties and examples.

• Account snapshot resource API reference

POST Create an account snapshot for a customer

This endpoint creates an account snapshot for the customer with the person_id specified in the request URL. You can create an account snapshot in different ways by specifying the source of the account snapshot.

1. Account snapshot via FinTech systems

You can create an account snapshot via FIN_TECH_SYSTEMS by completing the following steps:

1. Integrate the FIN_TECH_SYSTEMS wizard container in your solution by following their documentation.

2. Call the following endpoint and add the following properties in the request body:

   • source: FIN_TECH_SYSTEMS
   • iban: (Optional) you can add the IBAN of the customer's account.
3. The API call will return a wizard_session_key, which you must enter in the FIN_TECH_SYSTEMS wizard container to start the account snapshot session.
4. The customer enters their bank credentials to initiate the account snapshot.

Request example

POST /v1/persons/{person_id}/account_snapshots
{
    "source": "FIN_TECH_SYSTEMS"
}

Response example

The API call returns a resource with a unique ID, the account_snapshot_id, as well as the wizard_session_key.

{
    "wizard_session_key": "Hm7jUSC7XU2nQjPqJO8dl39eDkdjtOdCtywcmv3x",
    "location": null,
    "id": "8df2a8ba713c43dc9cb481b9cceed487snap",
    "account_id": null
}

2. Account snapshot via Finreach

You can create an account snapshot via FinX by completing the following steps:

1. Integrate the FinX widget in your solution by following their documentation.

2. Call the following endpoint and add the following properties in the request body:

   • source: FINREACH
3. The API call will return a location, which is a URL to which you must redirect your customer to enter their bank credentials to initiate the account snapshot.

Request example

POST /v1/persons/{person_id}/account_snapshots
{
  "source": "FINREACH"
}

Response example

The API call returns a resource with a unique ID, the account_snapshot_id, as well as URL to which you must redirect the customer.

{
    "wizard_session_key": null,
    "location": "https://ui.solaris-i.prod.finleap.cloud?token=xxxxxx",
    "id": "8df2a8ba713c43dc9cb481b9cceed487snap",
    "account_id": null
}

3. Account snapshot via partner

If you want to upload the details of an account snapshot you've created (e.g., if you already have your own connection with FIN_TECH_SYSTEMS or FINREACH), specify the source of the account snapshot file as partner and add the account snapshot data in the snapshot_data field.

Request example

POST /v1/persons/{person_id}/account_snapshots
{
    "source": "PARTNER",
    "snapshot_data": {
    "account": {
        "bank_name": "",
        "bic": "",
        "country_id": "",
        "description": "",
        "holder": "John Smith",
        "iban": "DE92370601930002130041",
        "joint_account": false
    },
    "balance": {
        "balance": 3720.20,
        "currency": "EUR",
        "date": "2022-02-03",
        "limit": 0
    },
    "date": "2022-02-03",
    "days": 90,
    "turnovers": [
        {
            "amount": 4000.05,
            "booking_date": "2022-02-01",
            "counter_bic": "",
            "counter_holder": "Salary company",
            "counter_iban": "DE89500105177323343587",
            "currency": "EUR",
            "purpose": [
                "LOHN / GEHALT 01/22"
            ],
            "tags": [],
            "CrifCategory": "RE_05"
        },
        {
            "amount": 4000.05,
            "booking_date": "2022-01-02",
            "counter_bic": "",
            "counter_holder": "Salary company",
            "counter_iban": "DE89500105177323343587",
            "currency": "EUR",
            "purpose": [
                "LOHN / GEHALT 12/21"
            ],
            "tags": [],
            "CrifCategory": "RE_05"
        },
        {
            "amount": 4000.05,
            "booking_date": "2021-12-01",
            "counter_bic": "",
            "counter_holder": "Salary company",
            "counter_iban": "DE89500105177323343587",
            "currency": "EUR",
            "purpose": [
                "LOHN / GEHALT 11/21"
            ],
            "tags": [],
            "CrifCategory": "RE_05"
        },
              {
            "amount": 4000.05,
            "booking_date": "2021-11-05",
            "counter_bic": "",
            "counter_holder": "Salary company",
            "counter_iban": "DE89500105177323343587",
            "currency": "EUR",
            "purpose": [
                "LOHN / GEHALT 10/21"
            ],
            "tags": [],
            "CrifCategory": "RE_05"
        }
    ]
}
}

Response example

The API call returns a resource with a unique ID, the account_snapshot_id.

{
  "wizard_session_key": null,
  "location": null,
  "id": "0a3f28733f9a4842842aae2804f80eb4snap",
  "account_id": null
}

4. Account snapshot via Solaris

You can create an account snapshot via Solaris for internal accounts by specifying the source as SOLARISBANK and adding the customer's account_id in the request body.

Request example

{
  "source": "SOLARISBANK",
  "account_id": "adc123a45d6d7cf8fbfeed537ba919d5cacc"
}

Response example

The API call returns a resource with a unique ID, the account_snapshot_id.

POST /v1/persons/{person_id}/account_snapshots
{
  "wizard_session_key": null,
  "location": null,
  "id": "0a3f28733f9a4842842aae2804f80eb4snap",
  "account_id": "adc123a45d6d7cf8fbfeed537ba919d5cacc"
}

Click here to view the full API reference

GET Retrieve a customer's account snapshot

This endpoint returns the information about a customer's existing account snapshot, including the status and validity of the account snapshot. Add the person_id and the account_snapshot_id in the request URL. If the status of the account snapshot is expired, you must create a new one for the customer.

Additionally, subscribe to the webhook event ACCOUNT_SNAPSHOT to receive notifications when the status of an account snapshot changes.

Request URL

GET /v1/persons/{person_id}/account_snapshots/{account_snapshot_id}

Click here to view the full API reference

PUT Link customer account snapshot to SDD collection application

After creating an account snapshot, call this endpoint to attach it to the SDD collection application by adding the account_snapshot_id to the request body.

Request URL

// PUT /persons/{person_id}/sdd_collection_applications/{sdd_collection_application_id}/account_snapshot
{
  "account_snapshot_id": "0a3f28733f9a4842842aae2804f80eb4snap"
}

Once linked, the application status will change to account_snapshot_verification_pending. Calling this endpoint also sends a webhook notification on the SDD_COLLECTION_APPLICATION event.

Additionally, this action triggers the credit scoring system to perform the final verification step on the customer's bank account to determine the overdraft limit based on the customer's income, expenses, and recurring credit repayments. After successful verification, the application status changes to offered.

Click here to view the full API reference.

Step 7: Complete the customer identification and due diligence process

In this step, you must trigger the Know Your Customer (KYC) process for your customer and ensure they pass all the mandatory screening checks.

7.1 Customer identification

All customers must be successfully identified using a suitable KYC method to be onboarded for any of Solaris' products.

Solaris offers different identification methods based on the product, region, and customer type. You can use the following identification methods to identify customers for decoupled cards:

• Bankident (Only for customers with a German IBAN).
• Video identification (Only for customers with supported identification documents).

7.2 Customer due diligence (CDD)

For more information, check the Customer Due Diligence guide.

Step 8: Set up customer internal account

In this step, you must create the internal account for the customer and attach the approved credit limit. Then, when the customer uses their decoupled card to make a purchase, the balance of this account will go negative, and the customer's external reference account will be debited in the amount of the negative balance. The SDD will be credited to this account for settlement.

The customer can top up this account and transfer any positive balance back to the reference account.

Account opening process

To open an account for your customer, visit the following links to find more information about the account opening process:

For this product, you need to open an account with the type DECOUPLED_CARD_CONSUMER.

• Account opening guide
• Account opening API reference

PUT Link internal account to SDD collection application

This endpoint attaches the created internal account to the SDD collection application. You must add the account_id returned from the previous process in the request body.

Request URL

// PUT /persons/{person_id}/sdd_collection_applications/{sdd_collection_application_id}/account
{
  "account_id": "cb752d28214bcfea4c285de600ad0105cacc"
}

Click here to view the full API reference.

Afterward, Solaris will attach the credit limit to the account, which the customer can use via the decoupled card.

Step 9: Create reference account and SDD mandate

In this step, you must create a reference account for the customer. The reference account will be used as the account in the SDD mandate, from which Solaris will pull the SDD payments.

Reference accounts API reference

Visit the following link to find all the endpoints related to the reference account resource, including related properties and examples.

• Reference accounts resource API reference:

  • POST Create a reference account for a person
  • GET Index reference accounts for a person

POST Create reference account

After creating the SDD mandate, you must create a reference account resource for the customer and link it to the internal account. You must add the customer's person_id and account_id in the request URL. You must add the external account details and the signed mandate information in the request body.

You must include the following properties in the request body:

• name: The customer's name on their external bank account.
• iban: The IBAN of the external bank account from which the SDD will be debited.
• mandate_number: The number of the SDD mandate the customer signed.
• mandate_signature_date: The date when the customer signed the SDD mandate.

Request URL

// POST /v1/persons/{person_id}/accounts/{account_id}/reference_accounts
{
 	"name": "Max Mustermann",
  "iban": "DE32110101001000000029",
 	"mandate_number": "SAMPAY7D226d32882d11Eb8DcD0242Ae2F4",
 	"mandate_signature_date": "2016-04-20"
}

The API call returns an object with a unique ID, which is the reference account ID. The status field refers to the reference account's status. Possible values are ACTIVE and INACTIVE.

Click here to view the full API reference.

Step 10: Create and activate decoupled card

Now that you have fully onboarded your customer, you can create a card for them. The customer can choose between different card types, such as a physical or a virtual card, with the option to tokenize the card to be used in any e-wallet, such as Google Pay, Apple Pay, or Samsung Pay. Check the Cards Creation and Servicing guide for instructions on how to issue and service cards.

Step 11: Servicing decoupled cards

This section includes information about actions customers may take after receiving their decoupled card. Customers can request the following:

• Change the reference account.
• Request a change on the credit limit available on the card.
• Disable the credit limit available on the card.
• Issue payouts to the reference account. Only in the case of having positive balance.

Change the reference account

If the customer wants to change the reference account associated with the SDD collection, please repeat Step 9: Create reference account and SDD mandate. Please be aware that you must create a new SDD mandate for the new reference account and collect the customer's signature on it.

Change the SDD collection limit

Customers can request an SDD collection limit change or disable the SDD collection limit entirely from the account. Implement the following endpoints in your solution to do so.

POST Create an SDD collection limit on the customer account

This endpoint creates a new SDD collection limit and attaches it to the account specified in the request URL. You must add the following properties to the request body:

• limit: The amount of the credit limit to be attached to the account in EURO.
• limit_type: The type of SDD collection limit. Use CUSTOMER_REQUEST.

Request URL

// POST /persons/{person_id}/accounts/{account_id}/sdd_collection_limits
{
  "limit": {
    "value": 10000,
    "unit": "cents",
    "currency": "EUR"
  },
  "limit_type": "CUSTOMER_REQUEST"
}

Click here to view the full API reference.

DELETE Disable the SDD collection limit on the customer account

This endpoint disables the active SDD collection limit from the customer's account specified in the request URL. You must add the following properties to the request body:

• limit_type: The type of SDD collection limit. Value is CUSTOMER_REQUEST.

Request URL

// DELETE /persons/{person_id}/accounts/{account_id}/sdd_collection_limits
{
  "limit_type": "CUSTOMER_REQUEST"
}

Click here to view the full API reference.

Issue payouts to reference account

If the customer tops up the balance on the internal account associated with their decoupled card to a positive value, they can transfer the positive balance back to their reference account. To do so, implement the following endpoints in your solution:

POST Initiate a payout to a specific reference account

This endpoint initiates a payout to a reference account associated with a specific customer. In the request URL, you must include the customer's person_id, the account_id (of the internal account), and the reference_account_id. In the request body, you must include the following properties:

• reference: A field to add your unique reference for the transaction.
• end_to_end_id: Your unique identifier for the transaction, which will be routed throughout the whole payment process.
• amount: The payout amount, including value, unit, and currency.
• description: Field to add additional description for the transaction.

Request URL

POST /v1/persons/{person_id}/accounts/{account_id}/reference_accounts/{reference_account_id}/payouts

Response example

The API call returns an object with a unique ID for the payout and the status of the payout, which can be accepted, executed, or declined. Once the payout is executed, a new booking will be created on the account and a BOOKING webhook notification will be sent.

{
  "id": "12312312312pyo",
  "reference": "unique_partner_reference",
  "status": "accepted",
  "amount": {
    "value": 10000,
    "unit": "cents",
    "currency": "EUR",
  },
  "end_to_end_id": "123123123",
  "reference_account_id": "1231231239ref",
  "description": "Withdrawl SPAY - DD.MM.YYYY"
}

Click here to view the full API reference.

GET Retrieve a single reference account payout

This endpoint retrieves the details of a specific payout made to a reference account. You must add the payout id in the request URL.

Request URL

GET /v1/persons/{person_id}/accounts/{account_id}/reference_account_payouts/{id}

Click here to view the full API reference.

Appendix I: Enums

SDD collection application status

The following table includes the possible values for the SDD collection application status field and their descriptions.