CDR Gateway Integration Guide

This guide will show how to integrate CDR Gateway and Frollo Link Web to allow users to provide consent to collect CDR data.

  1. Setup Frollo Link Web
  2. User Management
    1. Create User
  3. Authentication & Redirect
    1. Passwordless Authentication Token
    2. Redirect User
    3. Finish User Journey
  4. CDR Data
    1. Webhooks
    2. Fetching Transaction Data

Setup Frollo Link Web

The first step is to make sure your CDR Gateway and Frollo Link Web instance are configured appropriately. You will also need a set of credentials to access the Management API. We recommend using the Client Credential OAuth2 grant type but API key can also be used. See Authentication for more details.

Use the checklist below to validate:

  • Client ID - Client ID to be used by your platform to request an access token
  • Client Secret - Client Secret to be used by your platform to request an access token
  • Frollo Link Web Consent URL - To initiate the consent process for the user e.g. https://frollo.staging.link.cdr.systems/consent/link/start
  • Frollo Link Web Dashboard URL - To allow the user to update and revoke consents after the initial process e.g. https://frollo.staging.link.cdr.systems/consent/dashboard
  • Redirect URL - Optionally configure a redirect URL to take the user back to your application after consent is complete
  • Webhook Endpoint - Provide the webhook Events endpoint we will call with events e.g. https://example.com/inbound/api/events
  • Branding - Any branding customisations to the whitelabel Frollo Link Web instance

User Management

Next we need to create a user in the Frollo CDR Gateway to associate the consents and CDR data. All data within the Frollo system will be tied back to this User object allowing you to then fetch data based on an internal or external identifier.

Create User

The Create User endpoint on the Management API should be used to create the user. Make sure a suitable unique external identifier is used to aid lookup of the user later.

Optionally fields such as email and phone number can be sent to aid customer service lookup in the future.

Example request:

{
	"external_id": "D28D21C2-E607-46E4-9431-73EF9F4D608B",
	"first_name": "John",
	"last_name": "Smith",
	"email": "john.smith@example.com",
	"mobile_number": "0400111222",
	"primary_currency": "AUD"
}

Once the user has been created successfully you will receive a payload including the Frollo User ID - this should be saved as it will be needed to reference other APIs in a User context.

Example response:

{
    "id": 22788,
    "external_id": "D28D21C2-E607-46E4-9431-73EF9F4D608B",
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@example.com",
    "primary_currency": "AUD"
}

Authentication & Redirect

Next we need the user to provide consent and link their accounts. Here we’ll show the usage of Frollo Link Web via Passwordless Authentication to provide the user with a seamless experience.

Alternatively the user can be sent to the standard email and password login page - https://frollo.staging.link.cdr.systems/login

Passwordless Authentication Token

The first step is to use the Get Passwordless Authentication Token endpoint to obtain a token on behalf of the user. This requires use of the Client API via the Management API. See here for more details on how this is used.

The token can be requested as follows and will be used in the request to Frollo Link Web to authenticate the user seamlessly.

Example request:

Headers

X-User-Id: 22788

POST /api/admin/client/v2/user/auth/web

<Empty Body>

The token will then be returned in the response:

{
  authorisation_code: "f2224a1a-1752-4807-803a-977ff973ff68"
}

Redirect User

The final step is to redirect the user to Frollo Link Web pages using the token to authorise them. The token is single use and expires after a set time.

Alternatively this URL and token combination can also be sent to the user via email.

Example request:

GET https://frollo.staging.link.cdr.systems/consent/link/start?authorisation_code=f2224a1a-1752-4807-803a-977ff973ff68

The user will then automatically be authenticated and can link their CDR account.

Frollo Link Web Providers

Finish User Journey

Once the user has finished the consent process and linking their accounts they will be redirected back to the link configured earlier once they click done. You can then continue the user journey within your application.

You will receive the event CONSENT_LINKING_COMPLETE when the user clicks the finished button. If the user exits the browser or does not click finish you will not receive this event. Not all data will be synced at this point and you should wait for the event CONSENT_SYNC_COMPLETE. See below for more details.

Frollo Link Web Finish

CDR Data

The final step is to fetch CDR data once synced from the Data Holders and fully enriched.

Webhooks

Once data for a Data Holder is synced an event will be sent to your webhook endpoint indicating data is available. See Events endpoint for details on implementing the correct webhook payload format.

The event CONSENT_SYNC_COMPLETE will be sent to the Events webhook endpoint with the User ID, Consent ID and Account IDs that have been received. These can then be used to filter and fetch transaction data.

Example payload:

{
  "common": {
    "eventKey": "CONSENT_SYNC_COMPLETE",
    "state": "triggered",
    "userId": 22788,
    "accountId": 45456,
    "externalUserId": "D28D21C2-E607-46E4-9431-73EF9F4D608B",
    "userEventId": 9112789,
    "firstName": "John"
  },
  "payload": {
		"CONSENT_ID": 3972,
		"PROVIDER_ACCOUNT_IDS": 863531,
    "ACCOUNT_IDS": [
      965,
      966,
      967
    ]
  }
}

If any consents fail you may also receive CONSENT_SYNC_FAILED events indicating what issues occurred.

Fetching Consent Data

(Optional) If you require data about the consent given by the user, for example permissions or sharing duration, you can fetch the Consent information. Calls should be made to the Get Consent endpoint using the Consent ID returned in the webhook.

Example payload:

{
    "id": 6458,
    "provider_id": 5083,
    "provider_account_id": 987,
    "status": "active",
    "sharing_started_at": "2020-11-03",
    "sharing_duration": 31449600,
    "permissions": [
        "transaction_details",
        "account_details"
    ],
    "additional_permissions": {},
    "delete_redundant_data": true,
    "confirmation_pdf_url": "https://frollolabs-staging.frollo.us/api/v2/cdr/consents/123/pdfs/confirmation",
    "context": "c6f6efde-25e5-4eba-ad88-b5c68a8b4ff6"
}

Fetching Transaction Data

The final step is to fetch the CDR data your require. The List Transactions endpoint on the Management API can be filtered by Account IDs to return transactions for that user. Transactions are paginated and will be returned in batches of up to 500 at a time.

Example request:

GET /api/admin/transactions?account_ids=965,966,967

Example response:

{
  "data": [
    {
      "id": 1,
      "account_id": 1,
      "base_type": "credit",
      "status": "posted",
      "transaction_date": "2016-10-09",
      "post_date": "2016-10-10",
      "amount": {
        "amount": "1635.44",
        "currency": "AUD"
      },
      "description": {
        "original": "0150 Amazon  Santa Ana CA 55.73USD",
        "user": "New Toy",
        "simple": "Amazon Purcahse"
      },
      "budget_category": "income",
      "category_id": 1,
      "category_name": "Groceries",
      "category_image_url": "https://logo.png",
      "merchant": {
        "id": 1,
        "name": "Woolworths",
        "phone": "(02) 5689 3423",
        "website": "https://www.woolworths.com.au",
        "mage_url": "https://woolworths.png",
        "location": {
          "formatted_address": "10 Falcon St, Crows Nest NSW 2065, Australia",
          "line_1": "10 Falcon St",
          "line_2": "Suite 2 Level 3",
          "line_3": "Building 2 MLC",
          "suburb": "Crows Nest",
          "state": "NSW",
          "postcode": 2065,
          "country": "Australia",
          "latitude": -33.827499,
          "longitude": 151.201699
        }
      },
      "memo": "test",
      "included": true,
      "bill_id": 1,
      "goal_id": 1,
      "bill_payment_id": 1,
      "user_tags": [],
      "biller": {
        "code": "BPAY code",
        "name": "BPAY Biller name",
        "crn": "Customer Reference Number",
        "apca_number": "Sender APCA Number"
      },
      "payee": "Receiver of funds",
      "payer": "Sender of funds",
      "type": "The type of the transaction e.g. interest_charged"
    }
  ],
  "paging": {
    "cursors": {
      "before": "1577647183_278049",
      "after": "1577647183_278048"
    },
    "previous": "api/v2/aggregation/transactions/?before=1577647183_278049",
    "next": "api/v2/aggregation/transactions/?after=1577647183_278048",
    "total": 60
  }
}