The PayNet Open Finance Platform (OFP) is a Financial-grade API (FAPI) platform based on OpenID Connect and OAuth 2.0 standards. It enables secure, user-consented sharing of financial data between institutions.

There are three main parties involved:

1. Data Consumer (DC): Your application, requests financial data on behalf of an end user (e.g. for PFM or lending use cases)
2. Data Provider (DP): The institution that holds the user's financial data (e.g. a bank)
3. PayNet OFP: The intermediary platform that manages consent, authentication, and secure data exchange

PayNet OFP exposes two key server components:

• Authorization Server (AS): manages user consent, authentication, and issues access tokens
• Resource Server (RS): serves financial data (accounts, balances, transactions) when a valid access token is presented

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 uses multiple certificate-based security protocols. You must submit the appropriate certificates for each protocol.

Protocols requiring certificates:

How to Submit the Certificates and Redirection URL:

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

Client Credentials are used for machine-to-machine (M2M) calls specifically, when your DC system calls PayNet without direct end-user involvement (e.g. consent management operations).

How to Get these Credentials:

After submitting your Security Certificates and Redirection URL, you will receive an email reply containing your credentials the next business day.

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

Your DC application must provide a user-facing interface that guides the end user through the account linking and consent journey. At minimum, this should include:

• Account Linking Screen: Entry point where the user initiates the account linking process
• Data Provider Selection Screen: Allows the user to choose which bank/institution to link
• Consent Review Screen: Clearly presents what data is being requested and for how long, before submission
• Consent Confirmed Screen: shown after successful authorization, confirming the accounts linked
• Consent Rejected Screen: shown if the user declines or an error occurs during authorization
• Account Data Display: displays retrieved financial data (e.g. balance) once consent is active

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

Positive Scenario: End User Approves Consent

Negative Scenario: End User Rejects/Cancels Consent

Your backend must implement the following endpoints:

1. All Authorization Server Endpoints
2. Resource Server Endpoints, for Drop 1:
   • Providers
   • Retrieve Consent
   • Account Balance
3. Consent Webhook receiver

Download OpenAPI/Swagger

PayNet OFP supports two FAPI 2.0 client authentication methods for Data Consumers. Your DC may use either method based on what was registered during onboarding.

• private_key_jwt
• tls_client_auth (Mutual TLS / mTLS)

Method 1: private_key_jwt

For this method, include the following x-www-form-urlencoded parameters in authenticated Authorization Server requests.

The signed JWS must use PS256, and its kid must match your registered certificate thumbprint (x5t#S256).

JWS Header

JWS Body (Claims)

Method 2: tls_client_auth

For this method, the DC authenticates using mTLS and provides the following parameter:

When a token is issued over mTLS, it is sender-constrained. The same client certificate must be presented on subsequent Resource Server calls using that token.

Endpoint Authentication Summary (DC)

The table below shows whether endpoint-level client authentication is required and which method applies.

Use this flow when your DC backend needs to call PayNet on its own behalf, for example, to retrieve consent information or perform consent lifecycle management (get, revoke).

Endpoint:

POST https://{AS_URL}/v1/oauth/token
Content-Type: application/x-www-form-urlencoded
x-fapi-interaction-id: <UUID>

Request Parameters:

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

curl --location --request POST 'https://{AS_URL}/v1/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'x-fapi-interaction-id: <UUID>' \
  --cert /path/to/client.crt \
  --key /path/to/client.key \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=<YOUR_CLIENT_ID>' \
  --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
  --data-urlencode 'client_assertion=<SIGNED_CLIENT_ASSERTION_JWT>'

Successful Response (200):

PayNet returns an access_token. Use this token as a Bearer token in subsequent M2M API calls (e.g. consent retrieval, consent revocation).

This is the first step in the user-facing consent journey. Your DC backend sends a Pushed Authorization Request (PAR) to PayNet to register the consent parameters securely before redirecting the user.

Sequence Overview

DC Responsibilities are:

Step 2: Send the PAR Request

Endpoint:

POST https://{AS_URL}/v1/oauth/par
Content-Type: application/x-www-form-urlencoded

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

curl --location --request POST 'https://{AS_URL}/v1/oauth/par' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'x-fapi-interaction-id: <UUID>' \
  --cert /path/to/client.crt \
  --key /path/to/client.key \
  --data-urlencode 'client_id=<YOUR_CLIENT_ID>' \
  --data-urlencode 'request=<SIGNED_JAR_JWT>'

Step 3: Redirect the User

PayNet responds with a request_uri. Your DC must then redirect the end user's browser to PayNet's /authorize endpoint with the client_id and request_uri as query parameters.

Step 4: PayNet Redirects to the DP

PayNet redirects the user's browser to the Data Provider's (DP's) authorization page (HTTP 303). The user logs in at their bank, selects which accounts to share, reviews the consent, and approves or rejects.

Step 8: Handle the Callback

After the user completes authorization at the DP, PayNet redirects the user back to your redirect_url with an authorization_code and state parameter appended.

⚠️ Security check: Validate that the state value in the callback matches what you originally sent in the PAR request. Also validate the iss parameter matches the PayNet AS issuer URL from the .well-known endpoint.

Step 9: Completing Authorization & Exchanging the Authorization Code for Tokens

Once your DC receives the authorization_code from the redirect callback, your backend must immediately exchange it for tokens.

Endpoint:

POST https://{AS_URL}/v1/oauth/token
Content-Type: application/x-www-form-urlencoded
x-fapi-interaction-id: <UUID>

Request Parameters:

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

curl --location --request POST 'https://{AS_URL}/v1/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'x-fapi-interaction-id: <UUID>' \
  --cert /path/to/client.crt \
  --key /path/to/client.key \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code=<AUTHORIZATION_CODE>' \
  --data-urlencode 'redirect_uri=<YOUR_REDIRECT_URI>' \
  --data-urlencode 'client_id=<YOUR_CLIENT_ID>' \
  --data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
  --data-urlencode 'client_assertion=<SIGNED_CLIENT_ASSERTION_JWT>' \
  --data-urlencode 'code_verifier=<PKCE_CODE_VERIFIER>'

Successful Response (200):

⚠️ code_verifier is mandatory for Authorization Code flow. Omitting it will result in an invalid_grant error.

🔒 The authorization_code is single-use and short-lived. Exchange it immediately. PayNet invalidates it after use.

💡 Token Refresh: When the access_token expires, send a POST /token request with grant_type=refresh_token and the stored refresh_token to obtain a new access_token without requiring the user to re-authorize.

Once you have a valid access_token, you can call the Resource Server to retrieve financial data.

Sequence Overview

Retrieve Consent

Retrieve the existing consent record using Consent ID of the account linked. DC may use this endpoint to obtain the list of accounts associated with that consent, before then able to retrieve the balance data of each accounts.

GET https://{RS_URL}/v1/consents/{consent_id}
Authorization: Bearer {access_token}
x-fapi-interaction-id: <UUID>
x-signature: <JWS signed header>
x-enc-kid: <KID of your DC encryption certificate>

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

curl -X GET 'https://rs.paynet-ofp.com/v1/consents/c8f1a2b3-4d5e-6f7a-8b9c-0d1e2f3a4b5c' \
  --cert   'dc-client.crt' \
  --key    'dc-client.key' \
  --cacert 'paynet-ca.crt' \
  -H 'x-fapi-interaction-id: f47ac10b-58cc-4372-a567-0e02b2c3d479' \
  -H 'authorization: Bearer eyJhbGciOiJQUzI1NiIsImtpZCI6ImRjLXNpZy0wMSJ9..<access_token>' \
  -H 'x-fapi-signature: eyJhbGciOiJQUzI1NiIsImtpZCI6ImRjLXNpZy0wMSIsImlzcyI6ImRjLTEyMyIsImp0aSI6ImY0N2FjMTBiLTU4Y2MtNDM3Mi1hNTY3LTBlMDJiMmMzZDQ3OSIsImlhdCI6MTcwOTYwNjQwMH0..<signature>'

Get Account Balance Endpoint:

GET https://{RS_URL}/v1/accounts/{account_id}/balances
Authorization: Bearer {access_token}
x-fapi-interaction-id: <UUID>
x-signature: <JWS signed header>
x-enc-kid: <KID of your DC encryption certificate>

Key Request Headers:

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

curl --location --request GET 'https://{RS_URL}/v1/accounts/{account_id}/balances' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'x-fapi-interaction-id: <UUID>' \
  --header 'x-signature: <SIGNED_JWS>' \
  --header 'x-enc-kid: <DC_ENCRYPTION_CERT_KID>' \
  --cert /path/to/client.crt \
  --key /path/to/client.key

Response:

The response is returned as a JWE (encrypted) payload wrapped inside a JWS (signed) envelope. Your DC must:

1. Verify the JWS signature using the DP's public certificate
2. Decrypt the JWE payload using your DC's private encryption key

Balance Object fields include:

💡 The same pattern applies to other Resource APIs later: GET Account and GET Account Transactions follow the same authentication, signing, and decryption requirements.

This section applies to both Data Consumer (DC) and Data Provider (DP) integrations and summarizes security controls required by PayNet OFP.

The platform uses X.509 certificates published via JWKS endpoints for signature verification and encryption key discovery.

During key rotation, previous and new keys may coexist with different kid values. Cache JWKS responses for a maximum of 15 minutes.

mTLS is required for financial-grade transport security. Both parties authenticate each other at the TLS layer.

• Sender-constrained tokens are bound to the certificate used during token issuance.
• Resource Server calls must present the same certificate used when obtaining the access token.
• Inbound webhook endpoints must require and validate the caller certificate.

Missing-callout endpoints clarified

The following Authorization Server endpoints require mTLS:

• POST /v1/oauth/introspect
• POST /v1/oauth/revoke
• GET /v1/oauth/userinfo

JWS ensures integrity and non-repudiation of payloads.

• Header uses alg=PS256.
• kid identifies the signing certificate thumbprint (x5t#S256).
• Time claims (nbf, iat, exp) and jti help prevent replay attacks.

This is your primary integration test and should be completed before any live DP pairing. It uses PayNet's pre-built Mock DP, allowing you to test the full end-to-end flow in a controlled environment.

Pre-work Checklist

Before starting, confirm the following are complete:

• All prerequisites steps have been completed (certificates uploaded, credentials generated)
• Your DC application has been built for your target use case (PFM or Lending) based on API Spec v1.2.2
• Your redirect URL is correctly registered and accessible

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 DC testing purpose.

Definition of Done

Your integration is considered complete for this phase when all of the following have been demonstrated with your Certificates and Credentials:

• Consent initiated successfully: Your DC can initiate a consent request and receive an OAuth authorization code from PayNet
• Tokens issued: Your DC can exchange the authorization code for access_token, refresh_token, and id_token
• Resource API functional: Your DC can call at least one Resource API (e.g. Get Balance) using a valid access_token and successfully decrypt and display the response

This phase tests interoperability with a ready DP in a controlled bilateral pairing session.

⚠️ Important prerequisite: The Data Provider must have also passed testing before this phase can proceed.

How to proceed:

Once the above prerequisite is met, contact PayNet to schedule and align a bilateral testing session with a Real DP. PayNet will facilitate the pairing and provide guidance on the specific test scenarios to execute.

Returned in error responses from authorization and token endpoints.

Error Response Body

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

When receiving HTTP 429 (Too Many Requests), implement retry with exponential backoff to avoid overwhelming the platform.

The PayNet Open Finance Platform exposes a FAPI 2.0–compliant Authorization Server (AS) for OAuth 2.0 and OpenID Connect flows. Integrators should use discovery to obtain all AS endpoints and metadata instead of hardcoding URLs.

For this environment the AS issuer is https://api.as.sit.v1.inet.ofm.my.

Using the discovery (issuer) endpoint

1. Start from the issuer URL You will receive the AS base URL (issuer) for your environment (e.g. from the Partner Dashboard or onboarding). The issuer is the logical identifier of the AS and must match the iss claim in tokens and authorization responses.

2. Fetch the discovery document Request the OpenID Connect / OAuth 2.0 metadata at:

   • https://api.as.sit.v1.inet.ofm.my/.well-known/openid-configuration This document (see OpenID Connect Discovery 1.0 and RFC 8414) contains:
   • issuer — the AS issuer URL (validate that it matches the iss in responses and tokens).
   • authorization_endpoint, token_endpoint, jwks_uri, pushed_authorization_request_endpoint, userinfo_endpoint, and optionally introspection_endpoint, revocation_endpoint.
   • Supported algorithms, scopes, response types, and other capabilities.

3. Use the URLs from the discovery response Use these values for all subsequent requests (authorization, token exchange, PAR, UserInfo, JWKS). Do not hardcode paths; environments may differ.