Skip to main content

Implementation Guidelines for Service Provider in Onboarding

This comprehensive factsheet serves as your primary guide for a successful integration with the bLink platform. It consolidates essential resources, tools, documentation, and critical considerations for seamless implementation. Additionally, it provides insights into common questions and lessons learned from previous participants. This guideline is tailored for the implementation of AIS and PSS APIs. Use this resource to prepare, execute, and optimize your integration, maximizing the value of your bLink platform experience.

Resources and Tools​

Use the links and tools below to start your bLink integration.

Required resources for Implementation​

AIS / PSS APIs and Swiss Payment Standards​

bLink APIs adhere to Swiss Payment Standards guidelines for:

OpenWealth APIs​

bLink APIs adhere to the standards defined by the OpenWealth Association:

Registration Requirements for Connectivity​

To establish a connection to bLink’s testing environment:

Note: SIX provides their client certificates, which must be registered in the provider’s trust store.

Key API Implementation Considerations​

Apply these baseline rules to keep your implementation compliant, consistent, and operationally smooth.

Field Inclusion​

While API specifications differentiate between required and optional fields, optional fields must be included whenever relevant information is available. These fields are defined as optional only because they may not apply universally.

Full Endpoint Support​

Implement all AIS and PSS endpoints (both in JSON and XML format) to ensure full functionality and seamless interaction with all consumers.

Data Consistency​

Ensure that all IDs (e.g., account identifiers) allocated through the APIs remain consistent across all tokens and consents used to access the data. This consistency ensures reliable data handling and consumer interactions.

Error Handling​

Implement error responses per bLink specifications. Use the commonErrorResponse structure: {type, title, detail, instance}.

API Version Management​

New AIS and PSS API versions are released in November in alignment with Swiss-Payment-Standards (SPS) release cycles (Details are documented in bRelease Management Process). Maintain parallel versioning to ensure continuity during transitions.

Token Validation​

For invalid or expired tokens, respond with 401 Unauthorized, include a relevant problem definition, and the WWW-Authenticate response header according to RFC6750.

Platform Module​

Use the resources and requirements below to use the platform module in accordance with bLink’s specification:

  • Link to API Specification
  • Link to bLink Doc - API Reference
  • Synchronize the directory of clients at least once a day, as updates will occur regularly.
  • Participant IDs include an environment identifier: test (X) or production (P) and follow these structures:
    • Service Provider: IID{X/P}01234 (Always includes bank clearing number as suffix)
    • Service User: CID{X/P}0123456789 (Environment-specific suffix)

Use the resources and requirements below to implement the consent flow in accordance with bLink’s Consent Specification.

Resources​

Functional Requirements and Recommendations​

  • Dynamic authorization of Service Users is mandatory.
    • Access to new Service Users must be granted at Go-Live
  • Consents are granted according to the scopes included in the authorization request. The Service Provider may let the user refine the consent by use case (scope), account relationships or by selecting individual accounts.
  • Facilitate overarching consent for all accounts within the user's e-banking contract.
  • Allow users to manage consent for all accounts within their e-banking contract by using multiple tokens. Each token can represent a specific account or group of accounts.
  • Enable users to edit existing consents and handle account changes automatically.
  • Support self-service integration without requiring bank intervention.

Technical Requirements​

  • Validate requested scopes and verify that the SU is authorized to request them.
  • Return error=invalid_scope for unsupported scopes.
  • Run all consent flow tests in the SU Simulator’s Automated Testing section to verify compliance with the Consent Specification.
  • Ensure tokens adhere to defined lifetimes

Account Information Service​

Use the resources and requirements below to implement the AIS API to ensure a reliable service and a good user experience.

Ressources​

Functional Requirements​

  • Provide historical data (24 months) at initial consent in at least one format (JSON or XML).
  • Offer intraday data for /balance and /transactions endpoints.
  • Include multiple updates for booked transactions and balances during the day.

Technical & Content Requirements​

JSON​

  • While API specifications differentiate between required and optional fields, optional fields must be included whenever relevant information is available. These fields are defined as optional only because they may not apply universally.
  • Carefully review all descriptions and definitions in the API specifications, including attribute mapping to the SPS Guidelines.
  • Additional resource: Refer to the Factsheet in the SFTI GitHub for clarification on /transaction endpoint behavior.

XML​

  • Schema: Use the camt.053.001.08.xsd schema exclusively.
    • Populate "IBAN", "dateFrom", and "dateTo" as per AIS v5 conditions.
  • Multiple Retrievals: Enable statements to be retrieved multiple times, per User, across Service Users or consent sessions.
  • Timing: Reflect data from the user's consent date onward (or earlier for backward statements).
  • Important Note: Several banks offer XML statements through existing channels with user-specific configurations. For the purpose and use of the bLink Account & Payment Service, these settings must be reset and reconfigured to comply with the platform requirements:
    • Existing Configurations do not apply: User settings for other services must not affect bLink.
    • Batch Booking Breakdown: Ignore external batch-booking breakdown instructions in camt.054, and deliver details in camt.053.
    • Full Transaction Details: Always deliver detailed (d-level) transaction information.
    • Immediate Availability: Statements must be ready as soon as possible, once the user connects via bLink.
    • Backward Compatibility: Where feasible, generate historical statements for pre-onboarding periods.
    • Double Pickup: Ensure that a statement remains available for multiple retrievals.

Payment Submission Service​

Use the resources and requirements below to implement the PSS API to ensure a reliable service and a good user experience.

Ressources​

Functional Requirements​

  • Align payment processing with e-banking processes to ensure consistency in user experience.
  • Reflect accurate payment statuses (ACCP, PART, RJCT) based on SPS guidelines. Payment Status
  • Payments with status ACWC - Accepted with Change must not be rejected. Uses must perform corrections directly in e-Banking.
  • Payments with status PART - Partially Accepted must process only the accepted payments.
  • Assign a unique submissionId for each payment and include it with a relative path in the location header and in the body of the response.

XML​

  • bLink Supports xsd schema pain.001.001.09.ch.03.xsd and pain.002.001.10.xsd

Additional Notes for Successful Integration​

Last updated on