Consumer credit cards

Introduction

This guide explains the integration process for Solaris' Consumer Credit Cards product. With just a few API calls and an automated credit scoring system and KYC flow, you can onboard your customers on our credit card solution and issue, activate, and manage credit cards for your customers.

Available branches

This product is currently only offered to retail customers (B2C) in Germany.

How does it work?

Customers can apply for a credit card through your solution by doing the following:

• Fulfill all legal and compliance requirements.
• Submit the required data points.
• Pass the credit scoring process.
• Complete the customer identification flow (KYC).

Additionally, you can offer the customer the option to choose between charge and revolving credit cards. However, the onboarding requirements will differ depending on the chosen card type. Read more about the difference between charge and revolving cards here.

System prerequisites

Before starting the onboarding process, implement the following requirements:

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.

Postbox

Solaris will send all documents related to credit card applications (e.g., contracts and statements) via Postbox. Therefore, it's mandatory to implement the Postbox feature before initiating the onboarding process. For instructions, check the related Postbox integration guide.

B2C SDD mandate

You need to create an B2C SDD mandate and collect the customer's signature on it to allow Solaris to charge the customer's reference account for credit card repayments each month.

The SEPA Direct Debit (SDD) mandate is the customer's authorization for Solaris to collect funds from their account in the future. Solaris will pull SDDs from the customer's reference account for credit card repayments each month.

During your sign-up, you need to collect the IBAN of the reference account from the customer. Additionally, you must create a B2C SDD mandate, which the customer must sign.

How to create the SDD mandate?

You must generate a unique SDD mandate number. The mandate_number must contain 35 characters and the first 6 must be a partner-specific string agreed upon by you and Solaris during the implementation phase. The remaining 29 may only contain the following: [A-Z], [a-z], [0-9].

Additionally, make sure to display the following information to the customer before they sign the mandate:

• Full name (First_name + last_name)
• IBAN
• Generated mandate reference
• Name of Payee: Solaris SE
• Legal text containing authorization for the mandate

Integration overview

The following diagram gives a high-level overview of the integration process for consumer credit cards. Click on each step to go to its dedicated section for full instructions:

You can integrate Solaris' consumer credit card product by completing the 10 steps explained in the following sections. Here's an overview of these steps:

Sequence diagram

The following sequence diagram gives an overview of the integration flow:

In the following sections, you can find descriptions of these steps and their related endpoints.

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

• CREDIT_CARD_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 except for Account Closure. Credit cards have their own termination process, which is described below.

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 credit card application

In this step, collect additional information from your customer related to the credit card application and pass it to Solaris using the following endpoint.

POST Create credit card application for a retail customer

This endpoint creates a credit card application and assigns it to the person with the person_id specified in the request URL. The application includes all the required information about the customer, such as their self-declared financial information, credit card type, and requested limit, which Solaris' credit scorer uses to initiate a series of credit checks.

Mandatory fields

Add the following mandatory properties in the request body:

• product_type: Credit card type. For retail, choose CONSUMER_CREDIT_CARD.

• repayment_options: An object containing the repayment options of the credit card.

  • upcoming_type: The type of credit card (e.g., revolving or charge card). Options are FULL or PARTIAL.
  • minimum_amount: Minimum amount of the used limit to be repaid at the end of each billing cycle. Only relevant in case upcoming_type is set to PARTIAL.
  • minimum_percentage: Minimum percentage of the used limit to be repaid at the end of each billing cycle. Only relevant in case upcoming_type is set to PARTIAL.

• scoring_options: An object containing different fields relevant for the credit scoring process:

  • customer_desired_limit: The credit card limit requested by the customer, subject to the scorer's decision.
  • number_of_dependents: The number of dependents (e.g., children or spouse) who depend on the customer's income.
  • marital_status
  • net_income: The customer's net income amount in EUR after tax deduction.
  • living_situation: The customer's living situation. Possible values are LIVING_WITH_PARENTS, LIVING_IN_RENTED_HOUSE, or LIVING_IN_OWN_HOUSE.
  • living_situation_expenses: The customer's living monthly expenses (e.g., rent or mortgage, utilities, health insurance, etc.)
  • existing_credit_repayment_excluding_mortgage: A field containing information about the customer's existing debt repayments (in EUR) (excluding mortgage payments).
  • other_credit_credit_limit: If the customer has existing credit cards, include the granted limit in this field.
  • employment_since: The date when the customer started their current employment.

Request example

// POST /v1/persons/{person_id}/credit_card_applications
{
  "product_type": "CONSUMER_CREDIT_CARD",
  "repayment_options": {
    "upcoming_type": "PARTIAL",
    "upcoming_billing_cycle": "MONTHLY",
    "minimum_amount": {
        "value": 200,
        "unit": "cents",
        "currency": "EUR"
    },
    "minimum_percentage": 10
  },
  "scoring_options": {
    "customer_desired_limit": {
      "value": 5000,
      "unit": "cents",
      "currency": "EUR"
    },
    "number_of_dependents": 0,
    "marital_status": "MARRIED",
    "living_situation": "LIVING_IN_RENTED_HOUSE",
    "living_situation_expenses": {
      "value": 2000,
      "unit": "cents",
      "currency": "EUR"
    },
    "net_income_amount": {
      "value": 4000,
      "unit": "cents",
      "currency": "EUR"
    },
    "credit_repayment_excluding_mortgage_amount": {
      "value": 300,
      "unit": "cents",
      "currency": "EUR"
    },
    "other_credit_card_limit": {
      "value": 300,
      "unit": "cents",
      "currency": "EUR"
    },    
    "employment_since": "2019-08-24"
  }
}

Response example

The API call returns an object with a unique id (the application_id), including the application status (initially set to PENDING) and the remaining attributes, which will be populated during the application lifecycle.

Additionally, the call automatically triggers Solaris' credit scoring system, which scores the application and provides its decision on the credit card application, including the limit.

Click here to view the full API reference.

GET Retrieve credit card application

This endpoint returns the current status and details of an existing credit card application. For a list of possible values of the application status and their descriptions, check the appendix.

Additionally, subscribe to the webhook event CREDIT_CARD_APPLICATION to receive status updates on the application.

Request URL

GET /v1/credit_card_applications/{id}

Click here to view the full API reference.

Application status flow

The following diagram shows the different statuses and transitions for a credit card application:

Step 5: Download and send SECCI form and contract (Revolving only)

Before triggering the customer identification flow (KYC), you must download the relevant contracts, which the customer must approve. These documents include the following:

• SECCI form
• Credit card contract

The Standard European Consumer Credit Information (SECCI) form is a standardized credit form that includes the information related to a credit offer, such as creditor details, type of credit, amount, terms and conditions, etc.

In compliance with regulatory requirements, you must first send the customer the SECCI form to review and approve. Afterward, you can send them the final contract they must sign during the identification and e-signing process.

In this step, you must do the following:

1. Listen to the webhook event POSTBOX_ITEM_CREATED. Once Solaris generates the relevant documents, this webhook will be triggered with the item_id for each document.
2. Once you receive a notification from the webhook, download the relevant documents using GET Download a postbox item.
3. Display the documents to the customer on your app and collect the customer's consent as a UTC timestamp.
4. Create a confirmation for the customer's confirmation of the documents using POST Create a confirmation for a Postbox item.

1. POSTBOX_ITEM_CREATED webhook

Once the credit card application reaches the status PRE_APPROVED, Solaris will generate the SECCI form and the credit card contract and upload them to your postbox. You'll be notified via the webhook event POSTBOX_ITEM_CREATED.

Payload example

The payload will include the id (i.e., item_id) and information about the document, such as document_type, size, date, content type, etc.

The documents relevant to the credit card application will have the following document types:

• SECCI form = CREDIT_CARD_SECCI
• Credit card contract = CREDIT_CARD_CONTRACT

{
    "id": "d347d967ae8c4d58b93e6698b386cae9pbxi",
    "belongs_to": "3e0b990bb0f49eb1a43904e78461c0cbcper",
    "owner_type": "Person",
    "created_at": "2022-01-04T13:45:05Z",
    "document_date": "2022-06-30",
    "document_type": "CREDIT_CARD_SECCI",
    "name": "Credit card SECCI form",
    "description": "Description",
    "customer_notification": true,
    "customer_confirmation": true,
    "document_size": 1667317,
    "document_content_type": "application/pdf"
}

2. GET Download a document for a Postbox item

Download the documents by adding the item_id returned in the webhook payload in the request URL of the following endpoint:

GET /v1/postbox/items/{item_id}/document

Click here to view the full API reference.

3. Display documents and collect customer's consent

After downloading the relevant documents, you must display these documents to the customer on your app and collect their consent.

4. POST Create a confirmation for a Postbox item

After the customer approves the documents on your app, you must create a confirmation using the following endpoint:

Request example

// POST /v1/postbox/items/{item_id}/confirmations
{
  "person_id": "28a2197ff6e04a05b6316f83a38ccper",
  "idempotency_key": "ca3a40a8-43da-11ed-b878-0242ac120002"
}

Click here to view the full API reference.

Step 6: Complete the customer identification and due diligence process

In this step, create and trigger the Know Your Customer (KYC) process for your customer and make sure the customer completes the KYC and the customer due diligence (CDD) process successfully.

6.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. For an overview of available KYC methods, check the customer KYC products overview page.

This guide explains the integration process using Bankident. Other identification methods are possible; the Solaris team will recommend the most suitable KYC method for your banking use case.

6.1.1 Create an identification

Create an identification resource for your customer by completing Step 3 of the Bankident guide.

6.1.2 Complete Bank account validation step

Prompt your customer to complete the bank account validation and payment initiation described in Step 4 of the Bankident guide.

6.1.3 Download final contract (Revolving only)

After the customer validates their bank account, Solaris will generate the final credit card contract and upload it. You'll receive a POSTBOX_ITEM_CREATED webhook notification. Once you receive the webhook notification, do the following steps:

1. Retrieve the documents the customer must sign during the QES process using GET Index documents for a person identification.
2. Download the files using GET Download a document.
3. Display the documents to the customer on your app before triggering the QES process.

4. 6.1.4 Start QES process (Revolving only)

Trigger the QES process for the customer by completing Step 5 of the Bankident guide.

6.2 Customer due diligence

For more information, check the Customer Due Diligence guide.

6.3 Screening for FATCA indicia

To comply with the Foreign Account Tax Compliance Act (FATCA), Solaris is required to perform checks to determine whether the customer is subject to US tax law. These checks are in addition to the self-declaration during the Legal and Compliance screen.

To perform the FATCA checks, parse the person and identification resources using the following endpoints:

• GET Retrieve person
• GET Retrieve person identification

Hard criteria

To determine the customer's FATCA relevance, you must screen for the following hard criteria:

• Has the customer provided a US passport as their identification document? Check the legitimation_country attribute on the identification resource.
• Is the customer a citizen of the US? Check the nationality attribute.
• Has the customer provided a residential address in the US, the US Minor Outlying Islands, or the US Virgin Islands? Check the country attribute.
• Was the customer born in the US, the US Minor Outlying Islands, or the US Virgin Islands? Check the birth_country attribute.

When to reject the customer

If any of these hard criteria attributes have the value of US or USA, you must deny banking services to the customer and stop the onboarding process. Failure to screen for these hard FATCA criteria may cause ongoing operational burdens for Solaris customer support.

Soft criteria

To further determine the customer's FATCA relevance, screen for the following soft criteria:

• Has the customer provided a US mobile number? Check the mobile_number attribute. US mobile numbers have a country code of +1.
• Is the customer's only address a PO box or a c/o address? Check the address_line_1 and address_line_2 attributes.

When to reject the customer

• If the answer is "Yes" to any of the soft criteria, ask the customer to clarify their phone number and/or address.

  • If the customer provides a non-US phone number and a physical address, you may onboard them.
• If the customer does not provide a non-US phone number and a physical address, you may not onboard them.

Failure to screen for soft FATCA criteria may cause ongoing operational burdens for Solaris customer support.

You can only proceed to the next steps when:

• The identification status reaches successful.
• All screening and risk checks in the CDD process have a green status.
• The FATCA screening is completed to confirm the customer is not liable for taxes in the United States.

Step 7: Finalize credit card application

After successful customer identification process, finalize the credit card application by calling the following endpoint:

POST Finalize credit card application

Call this endpoint to finalize the credit card application. This API call triggers the creation of the credit card account by Solaris. The API response will return the account ID and IBAN and the application status changes to FINALIZED. Additionally, the billing cycle start and end date will be automatically calculated.

Request URL

POST /v1/credit_card_applications/{id}/finalize

Click here to view the full API reference.

Credit card account

The account ID and IBAN returned in the payload of the previous call is the account associated with the credit card to which the credit card limit will be attached.

Check the account management guide to find details about how to manage and service accounts.

Step 8: Create reference account and set credit card limit

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.

After creating the reference account, you must attach the credit limit approved by Solaris to the credit card's account using the following endpoint.

PATCH Attach credit limit to credit card account

Request example

// PATCH /v1/credit_card_applications/{id}/limit
{
  "limit": {
    "value": 1000,
    "unit": "cents",
    "currency": "EUR"
  }
}

The API call returns the details of the application and sets the current_limit to the limit defined by you. The limit will also be attached to the associated credit card account.

Click here to view the full API reference.

Step 9: Create and activate credit card

In this step, you must create and activate the credit card. 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 or Apple Pay.

API reference

Visit the following link to find all the endpoints related to cards, including related properties and examples.

• Cards API reference

POST Create a card

This endpoint initiates the card creation process for the customer. Include the account_id along with the person_id in the request URL. Additionally, include the following properties in the request body:

• line_1: The cardholder's name which will be printed on the card. Pay attention to the special rules governing card names mentioned here.
• type: The card type. View here a list of possible card types for each customer segment.

Request URL:

POST /v1/persons/{person_id}/accounts/{account_id}/cards

Response example:

A card will be created in the system, and Solaris will issue a card creation request with SIA. The API will respond with the ID of the card and the status of PROCESSING.

{
  "id": "8febdba4912a747808ccc6f95f82aaa4",
  "status": "PROCESSING"
}

Click here to view the full API reference.

GET Retrieve card details

Before you can activate the card, make the following API call to retrieve the details of the card. The status must have the value of INACTIVE. The status change may take a few seconds after the initial POST Create card request, as Solaris submits card creation requests asynchronously to SIA.

The API will respond with the card details when the status changes to INACTIVE. Until then, the response will look the same as the one from the previous call.

Request URL:

GET /v1/cards/{card_id}

Click here to view the full API reference.

POST Activate a card

Once the card is INACTIVE and you have retrieved the details using the previous API call, you can activate the card using the following endpoint:

Request URL:

POST /v1/cards/{card_id}/activate

Click here to view the full API reference.

Cards servicing

For more information about cards servicing, check the Card creation and servicing guide.

Card push provisioning

If your customer wants to use their card in a digital wallet, such as Google Pay, Apple Pay, or Samsung Pay wallet, implement the relevant endpoints in the Card Push Provisioning guide.

Step 10: Servicing credit cards

In this section, you can find endpoints related to servicing credit cards.

PATCH Update repayment option

Your customer can change the repayment option after initial onboarding (e.g., switching from charge to revolving and vice versa).

You can update the repayment option by calling the following endpoint:

Request example

// PATCH /v1/credit_card_applications/{id}
{
  "repayment_options": {
    "upcoming_type": "PARTIAL",
    "minimum_amount": {
      "value": 100,
      "unit": "cents",
      "currency": "EUR"
    },
    "minimum_percentage": 3
  },
  "statement_with_details": true
}

Click here to view the full API reference.

GET Index a credit card bill

Call this endpoint to retrieve a credit card bill.

Request URL

GET /v1/credit_card_bills/{bill_id}

Click here to view the full API reference.

Step 11: Terminating credit cards

This section describes how credit card termination works and how to use the related API endpoints.

Credit card termination process

Here is a summary of the termination process:

1. Either you, the customer (via your frontend), or Solaris initiates the termination.

   • If Solaris initiated the termination, then you will receive a notification on the CREDIT_CARD_APPLICATION_TERMINATION webhook event and you must immediately notify the customer about the termination.
   • If the customer initiated the termination, then your application must call the POST Terminate a credit card application endpoint. This will create a credit card application termination resource.

2. Solaris' system will trigger a termination and calculate a legal closure date for the credit card.

   • If the credit card has a negative balance, then Solaris will generate a final bill and trigger a SEPA Direct Debit (SDD) from the customer's reference account.
   • If the credit card has a positive balance, then Solaris will initiate a payout to the attached reference account.
3. You will receive notifications on the CREDIT_CARD_APPLICATION_TERMINATION webhook event when the status of the credit card application termination changes. If the termination succeeds, the credit card will be closed. If it fails, then Solaris Customer Support will provide assistance.

Pre-termination checks

Solaris will check for the following criteria before terminating a credit card:

• The credit card is in dunning.
• The credit card has CARD_TRANSACTION or CARD_DIRECT_DEBIT bookings from the past 45 days.
• The credit card has reservations with the status OPEN.
• The credit card has bookings with a valuta date in the future.
• The last SDD was triggered less than 56 days ago.

If any of these criteria are met, then the technical closure of the credit card may be delayed.

POST Terminate a credit card application

This endpoint initiates a termination request for an existing credit card.

Termination requests can be revoked within 5 business days of their initiation. After that, the termination can not be reversed. See the endpoint below for instructions on how to revoke a termination request.

Request URL:

POST /v1/credit_card_applications/{application_id}/terminate

Required properties:

• reason: The reason for terminating the credit card.

Click here to view the full documentation.

POST Revoke a termination request

This endpoint revokes a request to terminate a credit card.

Request URL:

POST /v1/credit_card_terminations/{id}/revoke

Click here to view the full documentation.

What's next?

Congratulations! You've successfully integrated Solaris' Credit Cards product.

Check the following appendices section for additional information on enums and testing data.

Useful resources

Check the following links for additional related guides and API reference documentation:

• Credit cards API reference documentation
• Reference accounts API reference documentation
• Bankident Identification
• Account management guide
• Card creation & servicing guide
• SEPA Transfers Overview
• SEPA Direct Debit Transfers

Appendix I: Enums

Credit card application status

The following table includes the enums for the field status and their descriptions in the credit card application resource. For example, it's available when you call the GET Retrieve credit card application.

Document types

The following table includes the possible values for the field document_type and their descriptions.

Appendix II: Bankident flow

Bankident testing data

Test scenarios

Your solution must consider the following edge cases for Bankident:

• The user data was not found.
• The user's IBAN could not be matched to the provided name.
• The account provided is a JOINT account (i.e., shared account).
• An authorized person on the account (i.e., someone who does not own the account) attempts to identify.
• Timeout of 10 minutes between payment initiation and finalization of QES.

You can test edge cases with the following mocked IBANs:

Happy path test scenario

Complete the following steps to simulate a successful identification workflow with Bankident on Sandbox.

1. Create a person

Create a person resource using the following endpoint and add the following fields in the request body.

Request

POST /v1/persons
{
    "salutation": "MR",
    "first_name": "Leander",
    "last_name": "Zierfisch",
    "address": {
        "line_1": "BERLINER STR. 45",
        "line_2": "",
        "postal_code": "14169",
        "city": "Berlin",
        "country": "DE"
    },
    "birth_date": "1978-07-15",
    "birth_city": "Aachen",
    "birth_country": "DE",
    "nationality": "DE",
    "email": "person@example.com",
    "employment_status": "EMPLOYED",
    "fatca_relevant": "false",
    "fatca_crs_confirmed_at": "2019-01-01T00:00:00Z",
    "terms_conditions_signed_at": "2019-01-01T00:00:00Z",
    "own_economic_interest_signed_at": "2019-01-01T00:00:00Z"
}

2. Create and verify a mobile number

You can follow the same steps mentioned in the guide and use the static values.

3. Create an identification

Create an identification resource and specify the identification method as bank in the request body of the following endpoint. Add the person_id returned from the previous API call to the request URL. Additionally, include the iban for a successful identification

Request example

POST /v1/persons/{person_id}/identifications
{
  "method": "bank",
  "iban": "DE11110101010100000020",
  "terms_and_conditions_signed_at": "2020-07-07T11:36:29.000Z"
}

4. Trigger the identification

To trigger the identification flow, call the following endpoint and add the person_id and the identification id returned from the previous API calls to the request URL.

Request example

PATCH /v1/persons/{person_id}/identifications/{id}/request

Response

{
    "id": "a7a57dadfcc83117b5c3b72f4113be25cidt",
    "reference": null,
    "url": "https://fts-payment-initiation-wizard.solaris-sandbox.de/index.html?wizard_session_key=bfo5r16AMLlt6ZEX9Oh3JUWIkTelorupBwzIlJRR&interface_id=da05",
    "status": "pending",
    "completed_at": null,
    "method": "bank",
    "proof_of_address_type": null,
    "proof_of_address_issued_at": null,
    "iban": "DE11110101010100000020",
    "terms_and_conditions_signed_at": "2020-07-07T11:36:29.000Z",
    "authorization_expires_at": null,
    "confirmation_expires_at": null,
    "estimated_waiting_time": null
}

5. Complete the payment transfer step

Go to the URL returned in the previous call and enter any number for the account number and the banking PIN and click NEXT. This screen simulates a login screen, in which the customer must log into their online banking and authorize a 5-cent transfer to validate the account ownership.

After clicking NEXT, another screen will pop up and you have to enter any TAN number to authorize the transaction. This screen simulates the screen in which the customer must enter the SMS OTP they received on their verified mobile number to authorize the transaction.

6. Complete the QES step

After successful payment transfer, complete the QES process by doing the following steps:

1. Call PATCH Start e-signing process. Add the person_id and identification id in the request URL.

Request

PATCH /v1/persons/{person_id}/identifications/{id}/authorize

Response

{
    "id": "a7a57dadfcc83117b5c3b72f4113be25cidt",
    "reference": null,
    "url": "https://fts-payment-initiation-wizard.solaris-sandbox.de/index.html?wizard_session_key=bfo5r16AMLlt6ZEX9Oh3JUWIkTelorupBwzIlJRR&interface_id=da05",
    "status": "confirmation_required",
    "completed_at": null,
    "method": "bank",
    "proof_of_address_type": null,
    "proof_of_address_issued_at": null,
    "iban": "DE11110101010100000020",
    "terms_and_conditions_signed_at": "2020-07-07T11:36:29.000Z",
    "authorization_expires_at": "2022-08-11T08:38:21.000Z",
    "confirmation_expires_at": "2022-08-11T08:37:23.000Z",
    "current_reference_token": "1234-5678",
    "estimated_waiting_time": null
}

2. Call PATCH Confirm e-signing process. Add the person_id and identification id in the request URL.

Request

PATCH /v1/persons/{person_id}/identifications/{id}/confirm

Response

{
    "id": "a7a57dadfcc83117b5c3b72f4113be25cidt",
    "reference": null,
    "url": "https://fts-payment-initiation-wizard.solaris-sandbox.de/index.html?wizard_session_key=bfo5r16AMLlt6ZEX9Oh3JUWIkTelorupBwzIlJRR&interface_id=da05",
    "status": "confirmed",
    "completed_at": null,
    "method": "bank",
    "proof_of_address_type": null,
    "proof_of_address_issued_at": null,
    "iban": "DE11110101010100000020",
    "terms_and_conditions_signed_at": "2020-07-07T11:36:29.000Z",
    "authorization_expires_at": "2022-08-11T08:38:21.000Z",
    "confirmation_expires_at": "2022-08-11T08:37:23.000Z",
    "current_reference_token": "1234-5678"
}

3. Afterward, call GET Retrieve a person identification and the response should include a successful status and the signed documents with their IDs.

Request

GET /v1/persons/{person_id}/identifications/{id}

Response

{
    "id": "a7a57dadfcc83117b5c3b72f4113be25cidt",
    "reference": null,
    "url": "https://fts-payment-initiation-wizard.solaris-sandbox.de/index.html?wizard_session_key=bfo5r16AMLlt6ZEX9Oh3JUWIkTelorupBwzIlJRR&interface_id=da05",
    "status": "successful",
    "completed_at": "2022-08-11T08:29:43.000Z",
    "method": "bank",
    "proof_of_address_type": null,
    "proof_of_address_issued_at": null,
    "address": null,
    "documents": [
        {
            "id": "a6585ea2b053a69fb705a0eb963084cfcdoc",
            "name": "a7a57dadfcc83117b5c3b72f4113be25cidt_prepared_for_signing_kyc_report.pdf",
            "content_type": "application/pdf",
            "document_type": "QES_DOCUMENT",
            "size": 88139,
            "customer_accessible": false,
            "created_at": "2022-08-11T08:25:11.000Z"
        },
        {
            "id": "4d1aa91e091e375e30e94de4ab1cf0f4cdoc",
            "name": "SIGNED_a7a57dadfcc83117b5c3b72f4113be25cidt_prepared_for_signing_kyc_report.pdf",
            "content_type": "application/pdf",
            "document_type": "SIGNED_QES_DOCUMENT",
            "size": 88139,
            "customer_accessible": false,
            "created_at": "2022-08-11T08:29:43.000Z"
        }
    ],
    "iban": "DE11110101010100000020",
    "terms_and_conditions_signed_at": "2020-07-07T11:36:29.000Z",
    "authorization_expires_at": "2022-08-11T08:38:21.000Z",
    "confirmation_expires_at": "2022-08-11T08:37:23.000Z",
    "current_reference_token": "1234-5678"
}

Bankident rejection reasons and error codes

The following table includes the possible failure reasons for Bankident. These failure reasons are also relevant for Bankident+ method.

Bankident FAQs

The following are common questions and answers related to the integration process of Bankident solution. If you have other questions or use cases not mentioned in this guide, contact your Partner Manager for support.

How many attempts with different IBANs can one "person" submit leading to receiving generic error messages on the identification creation?

20 attempts.

Does the user have to provide a DE IBAN or can it also be an IBAN with a different country code?

Currently, only German IBANs are supported for Bankident. If your customer doesn't have a German IBAN, check the other available identification methods here.

Can the user get their mobile phone number identified using every country code? Or does it have to be +49 for germany? Do you have a list of country codes allowed?

All country codes are supported except for Iran and North Korea.

Can the user have an address outside of Germany? If yes, which countries are allowed?

Yes, the user can have any kind of address. However, the probability that SCHUFA will correctly identify the person will decrease, since SCHUFA checks depend on the person's registered address.

How long is an SMS token valid?

The SMS authorization of the QES process is valid for 10 minutes.

Can a successful identification be "reused" by different companies?

There's no technical restrictions on reusing an identification. However, GDPR measures related to data cleanup must be defined.

Is there any timeout set for finishing the bank connection widget?

There is a 10-minute timeout.