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

How data flows to your bank:

Unlike a DC, which calls PayNet's APIs, your bank primarily operates 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.1 specification.

PayNet OFP exposes two server components relevant to you:

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

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

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 Banks 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:

Send email to PayNet xxxxxxxxx. (PayNet to prepare Instruction)

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:

Send email to PayNet xxxxxxxxx. (PayNet to prepare Instruction)

Your bank 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 bank 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 bank 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)

These webhooks are triggered before any financial data is exchanged. They cover the moment a consent request arrives at your bank through to the point where your customer has authenticated and made their decision. Your bank 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 bank with the details of that consent. Your bank must be ready to receive and process this notification.

Endpoint your bank 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 bank 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 bank 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 bank's authorization page. This is where your customer logs in, selects accounts to share, and approves or rejects the consent.

Endpoint your bank 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 bank's Resource Server webhooks. Your bank 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 bank must:

1. Validate the incoming JWS signature on the request (signed by PayNet using your bank'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.1 for the complete field definitions.

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 bank and a live DC in a controlled bilateral pairing session.

⚠️ Prerequisite: Your bank 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."
}