Client Implementation

You must implement SCA (Strong Customer Authentication) as the primary authentication method. Alternative methods (SAML 2.0, OIDC) may be available depending on your use case.

Primary Method: SCA (Strong Customer Authentication)

Recommended for: PSD2-compliant strong authentication with full control over the authentication experience.

1. Provide SCA Authentication URL to Treezor

Provide your SCA authentication page URL to Treezor:

https://auth.your-agent.com/sca

This is the HTTPS URL where Treezor will redirect PSUs for authentication.

2. SCA Flow

When a TPP initiates OAuth2 authorization:

Treezor redirects the PSU to your SCA authentication page:

https://auth.your-agent.com/sca?state={state_id}

The state parameter is a unique identifier for this authentication session.

Your SCA page must:
- Display your authentication interface to the PSU
- Authenticate the PSU with strong authentication (2FA, biometrics, OTP, etc.)
- Generate an SCA proof token after successful authentication
Your back end posts the authentication result to Treezor callback with the /oauth/callback/sca endpoint.

CURL

bash

curl -X POST "https://{clientName}.{stage}.openbanking.treezor.co/oauth/callback/sca" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "{state_id}",
    "userId": "{user_identifier}",
    "sca": "{sca_proof_token}"
  }'

Treezor validates the SCA proof and completes the OAuth2 flow by redirecting the PSU back to the TPP.

3. SCA Proof Requirements

The SCA proof is a JWS (JSON Web Signature) token generated by Treezor's SDK or WebAuthn integration. It cryptographically proves the PSU authenticated successfully.

Requirements:

Generated using Treezor Mobile SDK or Web Native (WebAuthn)
Signed with PSU's private key from their SCA Wallet
Single-use and short-lived (expires in minutes)
Must use 2 of 3 authentication factors: something the user has (device), is (biometric), or knows (PIN/password)

Treezor validates the proof automatically when you POST to the callback endpoint.

Alternative Methods

SAML 2.0: Enterprise SSO with existing SAML Identity Provider. Contact Treezor support to configure.

OIDC (OpenID Connect): Coming soon. Contact Treezor support for availability.

As a Treezor Client, you can manage PSU consents for Open Banking services.

List User Consents

Retrieve all active consents for a user (requires consent scope with Client Credentials grant):

Endpoint: /services/consents?userId={userId}

CURL

bash

curl -X GET "https://{clientName}.{stage}.openbanking.treezor.co/services/consents?userId={userId}" \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Request-ID: {unique-request-id}"

Base URL: https://{clientName}.{stage}.openbanking.treezor.co (non-secure domain)

Response:

CURL

json

{
  "consents": [{
    "id": "consent_123",
    "name": "My Banking App",
    "userId": "user_456",
    "status": "ACTIVE",
    "services": ["AISP"],
    "accounts": ["account_789"],
    "onboardingDate": "2025-01-15T10:00:00Z",
    "lastAuthenticateDate": "2025-01-20T14:30:00Z",
    "lastTPPAccess": "2025-01-20T15:00:00Z"
  }]
}

Endpoint: /services/consents?userId={userId}"

CURL

bash

curl -X PUT "https://{clientName}.{stage}.openbanking.treezor.co/services/consents/{consentId}/revoke" \
  -H "Authorization: Bearer {access_token}" \
  -H "X-Request-ID: {unique-request-id}"

Webhook Notification:

When a consent is revoked, a webhook is sent to your registered URL:

JSON

json

{
  "object": "consent",
  "objectId": "consent_123",
  "type": "revoke",
  "webhook": "openbanking.consent.revoke",
  "objectPayload": {
    "consents": [{
      "id": "consent_123",
      "status": "REVOKED",
      "revokeDate": "2025-01-20T14:25:00Z"
    }]
  }
}

Configuration Management

Updating Your Configuration

To update your authentication configuration:

Prepare your configuration (SCA or SAML JSON)
Contact Treezor support with the new configuration
Test in staging environment first
Verify OAuth2 flow completes successfully
Deploy to production after validation

Configuration Validation

After updating configuration:

Test complete OAuth2 authorization flow
Verify PSU authentication works correctly
Check callback responses are processed
Review logs for any errors

Testing

Staging Environment

Test your authentication in the staging environment:

OAuth URL: https://{clientName}.ppd.secure.openbanking.treezor.co/oauth

Test Scenarios

Successful Authentication
- User authenticates successfully
- Verify callback is called correctly
- Check authorization code is issued
Failed Authentication
- User cancels authentication
- Invalid credentials
- Expired state
Security Tests
- Replay attack prevention
- Invalid SCA proof
- Expired authentication

Troubleshooting

Common Issues

SCA: "Invalid proof"

Verify you're using Treezor SDK/WebAuthn correctly
Check SCA Wallet status is ACTIVE (not LOCKED or DELETED)
Ensure proof is generated immediately before callback POST
Verify userId matches the wallet owner
Check authentication method is not NONE for PSD2 operations
Confirm wallet has not exceeded failed authentication attempts (3 max)

SCA: "Wallet locked"

User exceeded maximum PIN/authentication attempts
Use unlock endpoint or contact Treezor support
Implement account recovery flow for users

SCA: "Wallet not found"

User has not enrolled in SCA yet
Wallet was deleted
Wrong userId provided

"State not found"

State expires after 10 minutes
Verify state is passed correctly through flow
Check for URL encoding issues
Contact Treezor support if issue persists

Logging

Log all authentication events:

Authentication requests received
SCA proofs generated
Callback posts to Treezor
Errors and validation failures

Include in logs:

Timestamp
User identifier (hashed)
State parameter
Success/failure status
Error messages

SCA API Documentation

For detailed SCA implementation:

SCA Introduction: https://docs.treezor.com/guide/strong-customer-authentication/introduction.html
User Enrollment: https://docs.treezor.com/guide/strong-customer-authentication/user-enrollment.html
Mobile SDK: https://docs.treezor.com/guide/strong-customer-authentication/sdk.html
Web Native: https://docs.treezor.com/guide/strong-customer-authentication/introduction.html#web-native

Endpoints

Endpoint	Description
`/core-connect/sca/scawallets`	Create SCA wallet
`/core-connect/sca/scawallets?userId={userId}`	List user SCA wallets
`/core-connect/sca/scawallets/{scaWalletId}`	Retrieve SCA wallet details
`/core-connect/sca/scawallets/{scaWalletId}/lock`	Lock SCA Wallet
`/core-connect/sca/scawallets/{scaWalletId}/resetPin`	Reset PIN
`/core-connect/sca/scawallets/{scaWalletId}`	Delete SCA Wallet

More details about SCA-related endpoints are available in the Treezor API Documentation, Strong Customer Authentication section.

Client Implementation ​

Primary Method: SCA (Strong Customer Authentication) ​

1. Provide SCA Authentication URL to Treezor ​

2. SCA Flow ​

3. SCA Proof Requirements ​

Alternative Methods ​

Consent Management ​

List User Consents ​

Revoke Consent ​

Configuration Management ​

Updating Your Configuration ​

Configuration Validation ​

Testing ​

Staging Environment ​

Test Scenarios ​

Troubleshooting ​

Common Issues ​

Logging ​

SCA API Documentation ​

Endpoints ​

Client Implementation

Primary Method: SCA (Strong Customer Authentication)

1. Provide SCA Authentication URL to Treezor

2. SCA Flow

3. SCA Proof Requirements

Alternative Methods

Consent Management

List User Consents

Revoke Consent

Configuration Management

Updating Your Configuration

Configuration Validation

Testing

Staging Environment

Test Scenarios

Troubleshooting

Common Issues

Logging

SCA API Documentation

Endpoints