The PayNet Open Finance Platform (OFP) enables secure, user-consented sharing of financial data between institutions. As a Data Provider, your institution sits at the heart of this ecosystem, you are the source of truth for your customers' financial data.

How data flows to your institution:

Unlike a DC, which calls PayNet's APIs, as a Data Provider you primarily operate as a server that PayNet calls. PayNet OFP forwards requests to your endpoints (called webhooks) for actions like user authentication, consent notification, and data retrieval. Your responsibility is to implement these webhook endpoints correctly and respond according to the v1.2.2 specification.

PayNet OFP exposes two server components relevant to you:

• Authorization Server (AS): manages the consent and authentication flow; your institution receives redirect webhooks and consent notifications from this component

• Resource Server (RS): forwards data requests (accounts, balances, transactions) from DCs to your institution

Before you start, you can simulate the User Experience as an End User starting from DC Simulator, Paynet Aggregator, and DP Simulator, for Consent Initiation up to Retrieve Balance Flow.

Run this Journey

1. Access Paynet DC Simulator at https://dc-sim.uat.inet.ofm.my
2. Start the Linking Account Process as per the UX Flow above
3. DP Login credentials are:
   • Username: paynet
   • Password: paynet

In this period, PayNet will support manual onboarding for participants into PayNet Open Finance Platform.

PayNet OFP enforces financial-grade security protocols. As a DP, you are required to upload certificates for the following two protocols.

How to Submit the Certificates:

Detailed instructions on how to submit the certificates will be provided during the onboarding process.

PayNet needs to know where to send requests. You must register the base URLs for both your Authorization Server and Resource Server endpoints.

How to Submit the API Base URL:

Detailed instructions on how to submit the API Base URL will be provided during the onboarding process.

All endpoints marked ✅ require Mutual TLS (mTLS). For outbound calls from your DP to PayNet, present your registered client certificate. For inbound webhook endpoints called by PayNet, your server must require and validate the client certificate presented by PayNet. Access tokens issued over mTLS are sender-constrained, so the same certificate used during token issuance must be presented on protected calls.

Your institution must provide a user-facing authorization interface, this is the login and consent approval page your customers see when they are redirected from a DC's application.

At minimum, this should include:

• Login Page: where the user authenticates with their credentials
• Account Selection Screen: where the user selects which accounts to share with the DC
• Consent Review Screen: where the user reviews and either approves or rejects the data sharing request
• Result Screen: confirmation or rejection message after the user makes their decision

Refer to the sample of UI mockup provided below for the expected screen flows as a Data Provider:

As a DP, your role is fundamentally different from a DC. Rather than calling APIs, you are building the APIs that PayNet will call. The table below summarises every endpoint your institution must implement.

1. All Authorization Server Endpoints
2. Resource Server Endpoints, for Drop 1:
   • Webhook Consent Event
   • Webhook Account Balance
   • Update Consent (DP call PayNet)

For Authorization Server token issuance, PayNet OFP supports two FAPI 2.0 client authentication methods for Data Providers:

• private_key_jwt
• tls_client_auth (Mutual TLS / mTLS)

Method 1: private_key_jwt

Use these parameters when requesting tokens with JWT client authentication.

The signed JWS must comply with the following structure.

JWS Header

JWS Body (Claims)

Method 2: tls_client_auth

When using mTLS client authentication, your DP establishes mTLS and includes:

Endpoint Authentication Summary (DP)

DP → PayNet OFP (Outbound)

PayNet OFP → DP (Inbound Webhooks)

Important for DP webhook endpoints: While these endpoints do not require outbound client authentication by the DP, the DP must protect all webhook endpoints with Mutual TLS and validate the incoming JWS signature using the appropriate certificate (PN cert for consent events; DC cert for account webhooks).

These webhooks are triggered before any financial data is exchanged. They cover the moment a consent request arrives at your institution through to the point where your customer has authenticated and made their decision. Your institution must handle both correctly for the consent to reach an authorized state.

Sequence Overview

Step 3 to 4: Receiving & Handling a Consent Event

When a DC initiates a consent request (by calling PayNet's PAR endpoint), PayNet immediately notifies your institution with the details of that consent. Your institution must be ready to receive and process this notification.

Endpoint your institution must expose:

POST https://{DP_URL}/v1/consents/events

What the payload contains:

🔒 This is the request from PayNet to your DP which must be made over mTLS using the certificate bound to your client_id.

curl --location --request POST 'https://{DP_URL}/v1/consents/events' \
  --cert /path/to/client.crt \
  --key /path/to/client.key \
  --cacert /path/to/ca.crt \
  --header 'Content-Type: application/json' \
  --header 'x-fapi-interaction-id: 550e8400-e29b-41d4-a716-446655440000' \
  --header 'x-fapi-signature: eyJhbGciOiJQUzI1NiIsImtpZCI6IkFCQ0RFRkdISUpLTE1OT1BRUlNUVVZXWFlaYWJjZGVmZ2g....<JWS_COMPACT_SERIALIZATION>' \
  --data-raw '{
    "event_type": "consent_status_updated",
    "data": {
      "consent_id": "550e8400-e29b-41d4-a716-446655440001",
      "dc_id": "dc-550e8400-e29b-41d4-a716-446655440002",
      "dp_id": "dp-550e8400-e29b-41d4-a716-446655440003",
      "id_type": "nric",
      "hashed_id_number": "eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eA==",
      "consent_type": "account_access_consent",
      "consent_purpose": "pfm",
      "permissions": [
        "read_accounts",
        "read_balances",
        "read_transactions"
      ],
      "expiration_datetime": "2025-12-31T23:59:59Z",
      "status": "authorized",
      "accounts": [
        {
          "account_id": "acc-550e8400-e29b-41d4-a716-446655440010",
          "account_reference": "1234567890",
          "account_name": "Savings Account"
        }
      ],
      "created_at": "2025-03-05T08:00:00Z",
      "updated_at": "2025-03-05T09:00:00Z",
      "updated_by": "data_provider_user"
    }
  }'

What your institution must do:

1. Validate the incoming JWS signature
2. Store the consent record against the consent_id
3. Respond with HTTP 200 to acknowledge receipt

⚠️ This endpoint is called at every stage of the consent lifecycle, creation, modification, and revocation. Your institution must handle all event types and update your internal consent state accordingly.

Step 7: Authenticating the User (Authorization Webhook)

After the DC's user initiates the consent flow, PayNet redirects the user's browser to your institution's authorization page. This is where your customer logs in, selects accounts to share, and approves or rejects the consent.

Endpoint your institution must expose:

GET https://{DP_URL}/v1/oauth/authorize

PayNet will supply the following in the request:

🔒 This is the request from PayNet to your DP which must be made over mTLS using the certificate bound to your client_id.

curl --location --request GET \
  'https://{DP_URL}/v1/oauth/authorize?consent_id=550e8400-e29b-41d4-a716-446655440001&redirect_uri=https%3A%2F%2Fopenfinance.paynet.my%2Fv1%2Foauth%2Fcallback&signature=eyJhbGciOiJQUzI1NiIsImtpZCI6IkFCQ0RFRkdISUpLTE1OT1BRUlNUVVZXWFlaYWJjZGVmZ2g....<JWS_COMPACT_SERIALIZATION>' \
  --cert /path/to/dp-client.crt \
  --key /path/to/dp-client.key \
  --cacert /path/to/ca.crt \
  --max-redirs 0 \
  --verbose

Step 9: Update consent to PayNet

1. If the user approves: call PayNet's Update Consent endpoint (POST /v1/consents/{consent_id}) with the authorized account list and updated consent status, then redirect the user's browser to the redirect_uri
2. If the user rejects: update the consent status to rejected and redirect the user to the redirect_uri with an appropriate error

🔒 This request must be made over mTLS using the certificate bound to your client_id.

curl --location --request PATCH \
  'https://{RS_URL}/v1/consents/550e8400-e29b-41d4-a716-446655440001' \
  --cert /path/to/dp-client.crt \
  --key /path/to/dp-client.key \
  --cacert /path/to/ca.crt \
  --header 'Content-Type: application/json' \
  --header 'x-fapi-interaction-id: 550e8400-e29b-41d4-a716-446655440000' \
  --header 'x-fapi-signature: eyJhbGciOiJQUzI1NiIsImtpZCI6IkFCQ0RFRkdISUpLTE1OT1BRUlNUVVZXWFlaYWJjZGVmZ2g....<JWS_COMPACT_SERIALIZATION>' \
  --data-raw '{
    "status": "authorized",
    "id_token": "eyJhbGciOiJQUzI1NiIsImtpZCI6ImRwLWtleS1pZC0wMDEifQ.eyJpc3MiOiJodHRwczovL2RwLmJhbmsuY29tIiwic3ViIjoidXNlci0xMjM0NTYiLCJhdWQiOiJkYy01NTBlODQwMC1lMjliLTQxZDQtYTcxNi00NDY2NTU0NDAwMDIiLCJleHAiOjE3NDE2Nzc0MDAsImlhdCI6MTc0MTY3NjgwMCwiYXV0aF90aW1lIjoxNzQxNjc2NzAwLCJpZF90eXBlIjoibnJpYyIsImhhc2hlZF9pZF9udW1iZXIiOiJlSGg0ZUhoNGVIaDRlSGg0ZUhoNGVIaDRlSGg0ZUhoNGVIaDRlSGg0ZUE9PSJ9.<DP_PRIVATE_KEY_SIGNATURE>",
    "user_identity": {
      "id_type": "nric",
      "hashed_id_number": "eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eHh4eA=="
    },
    "accounts": [
      {
        "account_id": "acc-550e8400-e29b-41d4-a716-446655440010",
        "account_number": "1234567890",
        "account_name": "My Savings Account"
      }
    ]
  }'

Once a user has approved consent, a DC can request financial data through PayNet. PayNet forwards these requests to your institution's Resource Server webhooks. Your institution must retrieve the relevant data, encrypt it using the DC's JWE certificate, and return it wrapped inside a JWS-signed response.

Sequence Overview

Account Balances Webhook

POST https://{DP_URL}/v1/accounts/{account_id}/balances

PayNet forwards a balance request from a DC. Your institution must:

1. Validate the incoming JWS signature on the request (signed by PayNet using your institution's cert kid)
2. Look up the balance for the account_id
3. Encrypt the balance data using the DC's encryption certificate (x-enc-kid)
4. Return the encrypted payload wrapped in a JWS

Balance data to return:

🔒 This is the request from PayNet to your DP which must be made over mTLS using the certificate bound to your client_id.

curl --location --request GET \
  'https://{DP_URL}/v1/accounts/acc-550e8400-e29b-41d4-a716-446655440010/balances?consent_id=550e8400-e29b-41d4-a716-446655440001' \
  --cert /path/to/paynet-client.crt \
  --key /path/to/paynet-client.key \
  --cacert /path/to/ca.crt \
  --header 'x-fapi-interaction-id: 550e8400-e29b-41d4-a716-446655440000' \
  --header 'x-enc-kid: <base64url-SHA256-thumbprint-of-DC-cert>' \
  --header 'x-fapi-signature: eyJhbGciOiJQUzI1NiIsImtpZCI6IkFCQ0RFRkdISUpLTE1OT1BRUlNUVVZXWFlaYWJjZGVmZ2g....<JWS_COMPACT_SERIALIZATION>'

💡 The same request-validation and JWS-wrapped JWE response pattern applies to the Account and Account Transactions webhooks. Refer to the full DP API Spec v1.2.2 for the complete field definitions.

This section applies to Data Consumers and Data Providers. It summarizes certificate usage, mTLS requirements, message signing, and security-related HTTP headers.

During certificate rotation, old and new keys may coexist with different kid values. Cache JWKS responses for up to 15 minutes.

mTLS is mandatory for protected integration paths.

• Outbound DP calls to PayNet must present your registered client certificate.
• Inbound webhook calls from PayNet must be protected by server-side mTLS certificate validation.
• Sender-constrained tokens require using the same certificate across token issuance and protected API calls.

mTLS Requirements by Endpoint (DP)

JWS protects message integrity and provides non-repudiation.

• Use PS256 for signatures.
• Set kid to the certificate thumbprint (x5t#S256) used to sign payloads.
• Validate iat/nbf/exp and replay-sensitive jti.

This is your primary integration test which will be initiated from Mock Data Consumer.

Pre-work Checklist

Before signalling readiness to test, confirm the following:

• All prerequisites steps are complete (certificates uploaded, base URLs registered)
• All mandatory webhook endpoints are implemented and accessible
• Your authorization UI (login, account selection, consent approval) is functional
• Your endpoints are protected by mTLS and return correctly signed/encrypted responses

Backend Initiated Test

1. Inform PayNet that your DP implementation is ready for testing. PayNet will coordinate directly with you to initiate the test.
2. PayNet will share a PyTest suite to initiate DC call with mock DC credentials setup
3. Update the API Base URL and Certificates to direct PayNet OFP calls into your DP

End-to-End Test Journey

The following table describes each step of the test, which party drives it, and the expected outcomes as per UI, Backend API, and API Integration Guide in the previous sections. You can focus on the bold rows for your DP testing purpose.

Definition of Done

Your build is considered complete for this phase when all of the following have been demonstrated with your Certificates and Base URL setup:

• Consent handled successfully: Your DP exposes the Consent Event endpoint (POST /v1/consents/events), validates the incoming JWS signature, and returns the correct response
• User authenticated properly: Your DP exposes the Authorize endpoint (GET /v1/oauth/authorize), and your end user is correctly redirected through the DP authentication flow through to the point of consent approval or rejection
• PayNet updated: Your DP calls Update Consent (PATCH /v1/consents/{consent_id}) to PayNet appropriately, with a positive status on approval and a negative status on rejection
• Resource API functional: Your DP's Get Balance endpoint (GET /v1/accounts/{account_id}/balances) is functional and returns the correct encrypted and signed response

This phase verifies interoperability between your institution and a live DC in a controlled bilateral pairing session.

⚠️ Prerequisite: Your institution must have **passed all tests as a DP** before this phase can begin.

How to proceed:

Contact PayNet to schedule a bilateral testing session with a Real DC. PayNet will identify a suitable DC partner, facilitate the pairing, and provide guidance on the specific scenarios to execute together.

Returned in error responses from authorization and token endpoints.

Error Response Body

{
  "error": "invalid_grant",
  "error_description": "The authorization code has expired."
}