Dealer API

Appearance

Integration Flow Overview and User Journey ​

Note: The flow described here follows the API-based integration approach, which is designed for partners who will rely on the API to create and cancel the purchases to be able to manage them in their own systems with backend to backend communication.

This document outlines the user journey for activating a product, As an example we are using BILDplus on bild.de as a product in this documentation, from the partner's website through to the Axel Springer systems and back. It is intended for the development teams of our partners, providing a comprehensive guide on integrating with the Premium Services team's PS-Dealer and PS-Login services.

For detailed technical integration steps, refer to our Developer Guides and the latest API Reference.

The integration consists of three primary phases:

  1. User Pairing: Registration or login of the partner's user with our services, culminating in the handover of a user ID to the partner.
  2. Granting BILDplus Access: Activation of the subscription (creating the purchase on our systems).
  3. Terminating BILDplus Access: Conclusion of the subscription (cancelling the purchase on our systems).

1. User Pairing with Partner ​

Process Overview ​

The user initiates the process by attempting to activate BILDplus through a browser request, leading to a series of redirects between the partner site, PS-Dealer, and PS-Login for user authentication and data submission.

mermaid
sequenceDiagram
    participant U as User
    participant B as Browser
    participant V as Partner
    participant PSL as PS-Login
    participant PSD as PS-Dealer
    U->>B: click activate BILDplus
    B->>V: open /activate/BILDplus
    V->>B: redirect to AS-Dealer
    B->>PSD: open /partners/{partnerId}/activation
    PSD->>B: redirect to PS-Login
    B->>PSL: /login or /register
    PSL->>B: form
    U->>B: submit data
    B->>PSL: send data
    PSL->>PSD: open /partners/{partnerId}/redirect
    PSD->>B: /partner-provided-url?userId=<partner-specific-userid>

Key Steps ​

  • The user interacts with the browser to activate BILDplus.
  • The browser communicates with the partner, which then redirects to AS-Dealer.
  • PS-Dealer directs the browser to PS-Login for user authentication.
  • The user submits their login or registration data.
  • PS-Login redirects back to PS-Dealer, which then sends the user ID to the partner.

2. Granting BILDplus Access ​

Process Overview ​

This phase involves the partner requesting an access token from Cognito, then using it to create a subscription for the user in PS-Dealer.

mermaid
sequenceDiagram
    participant V as Partner
    participant C as Cognito
    participant PSD as PS-Dealer
    V->>C: get access token (oauth / client credential grant flow)
    C->>V: access_token
    V->>PSD: POST /partners/{partnerId}/purchase <access_token> <DATA>
    note right of PSD: Maps Partner's product ID to AS-product and stores subscription

Key Steps ​

  • The partner obtains an OAuth token from Cognito.
  • The partner uses the token to post purchase details to PS-Dealer.
  • PS-Dealer maps the partner's product ID to an AS-product and records the subscription.

3. Terminating BILDplus Access ​

Process Overview ​

Similar to granting access, terminating access involves the partner obtaining an OAuth token and then instructing PS-Dealer to cancel the subscription.

mermaid
sequenceDiagram
    participant V as Partner
    participant C as Cognito
    participant PSD as PS-Dealer
    V->>C: get access token (oauth / client credential grant flow)
    C->>V: access_token
    V->>PSD: DELETE /partners/{partnerId}/purchase <access_token> <DATA>
    note right of PSD: Ends subscription, remains visible as inactive in user's area

Key Steps ​

  • The partner acquires an OAuth token from Cognito.
  • The partner sends a DELETE request to PS-Dealer to end the subscription.
  • The subscription is terminated but remains listed as inactive for the user.

Key Considerations ​

  • URL Parameters: Replace {partnerId} with the actual partner ID in API calls.
  • Security Compliance: Ensure secure data transmission and adherence to data protection laws.
  • Error Management: Implement error handling for seamless integration.
  • Logging and Monitoring: Keep detailed logs and monitor integration points to resolve

issues promptly.

For further technical assistance or queries, visit our FAQ page or contact our team. We are committed to facilitating a smooth integration for our partners.