Ozone

Open Finance Malaysia Developer Portal

Introduction

Getting started

Overview

This guide will help you get started with integrating to the Open Finance Malaysia (OFM) platform to test your use cases as a Data Consumer.

Registration Process for Sandbox

Step 1: Register Your Organization

  1. Contact PayNet through the Contact Us page to initiate the registration process
  2. Provide your organization details.
  3. Optionally, provide technical details (your jwks_uri and redirect_uri). Initially, PayNet can provide test resources for these and you may modify these later.

Step 2: Obtain test certificates or create your own certificates

To make your onboarding easier, PayNet can provide you with a starter pack of digital certificates for testing purposes and a hosted JWKS that hosts your public keys.

Alternatively, you can follow the instructions provides in Creating your digital certificates to generate your own signing and encryption certificates and host the public keys on your own JWKS.

You will need the following certificates:

  • Transport Certificate: For mutual TLS authentication
  • Signing Certificate: For JWS request signing
  • Encryption Certificate: For receiving JWE encrypted responses

Certificate Requirements:

  • RSA key with minimum 2048-bit length
  • Valid for at least 12 months
  • In the Sandbox environment, self-signed certificates are acceptable

Step 3: Configure Your Application

Data Consumer Configuration:

  1. client_id: You will receive a unique client_id from PayNet. This is your technical identifier used in OIDC flows.
  2. dc_id: You will receive a unique dc_id from PayNet. This is your legal identifier and used to identify you to other ecosystem participants.
  3. Redirect URIs: You may register your OAuth redirect URIs or use pre-configured ones provided by PayNet
  4. Webhook URL: Optionally, register your webhook endpoint for consent events

Step 4: Implement API Integration

For Data Consumers:

  1. Discovery: Retrieve PayNet's OpenID Connect configuration from its well-known endpoint

  2. Implement OAuth Flows:

    • Authorization Code Grant for user consent
    • Client Credentials Grant for consent management
    • Refresh Token Grant for token refresh

  3. Implement Webhook Endpoint:

    • Handle POST /consents/events
    • Validate JWS signatures
    • Return 200 OK acknowledgment

  4. Implement Data Retrieval:

    • Call resource server APIs with access tokens
    • Verify and decrypt JWE responses
    • Handle errors and retries

Security Setup

Mutual TLS Configuration

  1. Install Certificates: Install your transport certificate and private key
  2. Configure TLS: Configure your HTTP client for mutual TLS
  3. Certificate Validation: Implement certificate chain validation
  4. Certificate Monitoring: Monitor certificate expiration dates

JWS Signing Setup

  1. Load Signing Key: Load your signing certificate and private key
  2. Implement Signing: Sign requests/responses per specification
  3. Key ID (kid): Use certificate thumbprint as key ID
  4. Verify Signatures: Verify incoming JWS signatures

JWE Encryption Setup (Data Consumers)

  1. Load Encryption Key: Load your encryption certificate and private key
  2. Publish Public Key: Ensure public key is available for Data Providers
  3. Decrypt Responses: Implement JWE decryption for responses
  4. Key Rotation: Plan for encryption key rotation

Testing in Sandbox

Before going to production, test your integration in the Sandbox environment:

Sandbox Environment Details

URLs for the Sandbox environment will be made available on registration.

Sandbox Features

  • Test Data Providers with sample data
  • Test user accounts and credentials
  • Relaxed certificate requirements (self-signed allowed)
  • Extended token lifetimes for testing
  • Detailed error messages and logging

Test Scenarios

  1. Happy Path: Complete consent creation and data retrieval
  2. Error Handling: Test various error scenarios
  3. Token Expiry: Test token refresh flow
  4. Consent Revocation: Test consent lifecycle management
  5. Webhook Events: Test webhook event handling
  6. Security: Test certificate validation and signature verification

For detailed sandbox instructions, see Sandbox Guide.

API Endpoints Overview

Authorization Server APIs

  • GET /.well-known/openid-configuration - OpenID Connect discovery
  • GET /jwks - JSON Web Key Set
  • POST /par - Pushed Authorization Request
  • GET /authorize - Authorization endpoint
  • POST /token - Token endpoint
  • POST /introspect - Token introspection
  • POST /revoke - Token revocation
  • GET /userinfo - User information

Resource Server APIs

  • GET /providers - List Data Providers
  • GET /consents/{consentId} - Retrieve consent
  • POST /consents/{consentId}/revoke - Revoke consent
  • POST /consents/{consentId}/suspend - Suspend consent
  • POST /consents/{consentId}/reactivate - Reactivate consent
  • GET /accounts/{accountId} - Get account
  • GET /accounts/{accountId}/balances - Get balances
  • GET /accounts/{accountId}/transactions - Get transactions

For detailed API documentation, see DC API Developers Guide.

Integration Flows

1. Authorization Code Grant Flow

Used for creating user consents:

  1. Send Pushed Authorization Request (PAR)
  2. Redirect user to authorization endpoint
  3. User authenticates and grants consent
  4. Exchange authorization code for tokens
  5. Access user data with access token

2. Refresh Token Flow

Used for obtaining new access tokens:

  1. Detect expired access token
  2. Send token request with refresh_token grant
  3. Receive new access token
  4. Continue accessing data

Used for revoking consents:

  1. Obtain client credentials grant access token
  2. Send revocation request
  3. Receive confirmation
  4. PayNet notifies Data Provider

Security Best Practices

  1. Certificate Management:

    • Store private keys in HSM or secure vault
    • Rotate certificates before expiry
    • Monitor certificate validity

  2. Token Security:

    • Store tokens encrypted at rest
    • Never log tokens in plain text
    • Implement token refresh logic
    • Revoke tokens on logout

  3. Request/Response Security:

    • Always verify JWS signatures
    • Validate certificate chains
    • Check timestamp claims
    • Use unique request IDs

  4. Error Handling:

    • Don't expose sensitive information in errors
    • Log security events
    • Implement rate limiting
    • Handle failures gracefully

API Rate Limits

PayNet OFP may rate limit requests from Data Consumers to ensure fair usage.

Request Correlation

Use x-fapi-interaction-id header for request correlation:

  • Generate unique ID for each request
  • Include in all related API calls
  • Use for troubleshooting and support

If you require support on a particular request, include the x-fapi-interaction-id in your support request.

Support and Resources

To contact support, please see the Contact Us page.

Next
DC Sandbox
Powered by ozoneapi

© 2026 Open Finance Malaysia Developer Portal. All rights reserved.