Welcome to the Netbank Virtual API Technical Documentation.

This documentation/reference includes all the details regarding the API endpoints and webhooks that will allow you to integrate Netbank’s financial services into your own applications, systems, and platforms.

We strongly suggest that you read through the General Guidelines section to familiarize yourself with the overall structure and behavior of the Netbank Virtual APIs.

The API endpoints are grouped according to the product and are ordered based on the usual call sequence for easier reference. Each product, endpoint, and parameter will have a description to define the purpose of each element.

Disclaimer: We will continually update and enhance this page and its contents whenever necessary.

To know more about how to get started and the end-to-end onboarding process, you may refer to https://virtual.netbank.ph/get-started

For any questions/inquiries, you may refer to our FAQs (https://virtual.netbank.ph/faq) or reach out to the Netbank Virtual Team via the Contact Us Form found in various pages of https://virtual.netbank.ph/ and select “Request for integration support for Sandbox and UAT development” in the the “How can we help you?” dropdown.

There are 3 environments where you could use our APIs for specific purposes.

• SANDBOX (https://api-sandbox.netbank.ph)

  • Description: This environment is where you can “try” or test the request and response of our APIs to have an idea on the format and behaviour that your system needs to integrate with.

  • Purpose of Use: To simulate and test the request and response payload of the APIs so you could finalize how your system interacts with our APIs.

  • Connection to our Core: These APIs are connected to a limited are of our Core Banking System but it mimics how our APIs would accept requests and return a response.

  • Access Credentials: You can quickly and simply generate Sandbox Credentials using the Credentials Management section of your Partner Dashboard.

    • Sign-In and access the Netbank Virtual Partner Dashboard

    • Navigate to the Credentials Management section

    • Click “Generate Client ID & Secret”

    • Select “Sandbox Environment”

    • Take note of your Client ID and Client Secret

  • Requirements to get access:

    • Netbank Virtual Account (Sign Up to Netbank Virtual)

    • Sandbox Access Credentials, (Generated via the Credentials Management section of the Partner Dashboard)

• UAT (https://api-uat.netbank.ph)

  • Description: This environment is where you can perform a deeper level of testing and review to ensure that your integration with us is ready for Production-use.

  • Purpose of Use: To perform various quality assurance testing (e.g. unit, stress, performance, acceptance testing) to ensure that the integration can handle all types of Production-use scenarios.

  • Connection to our Core: These APIs are connected to the test environment of our Core Banking System that reflects the same level of capacity and behaviour as the Production environment.

  • Access Credentials: You can simply generate UAT Credentials using the Credentials Management section of your Partner Dashboard but we suggest using this environment solely for quality assurance testing-- which is done after you’ve finalized the integration setup to our APIs.

    • Sign-In and access the Netbank Virtual Partner Dashboard

    • Navigate to the Credentials Management section

    • Click “Generate Client ID & Secret”

    • Select “UAT Environment”

    • Fill out the Request for UAT Credentials form

    • Take note of your Client ID and Client Secret

  • Requirements to get access:

    • Netbank Virtual Account (Sign Up to Netbank Virtual)

    • UAT Access Credentials (Generated via the Credentials Management section of the Partner Dashboard)

    • Information on the product/service that you are building

• PROD (https://api.netbank.ph)

  • Description: This environment is where you can create live accounts and initiate live transactions.

  • Purpose of Use: To use the Netbank products and services in actual business transactions and use cases.

  • Connection to our Core: These APIs are connected to the production environment of our Core Banking System.

  • Access Credentials: You can request for Production Credentials using the Credentials Management section of your Partner Dashboard along with the Pre-Production requirements.

    • Sign-In and access the Netbank Virtual Partner Dashboard

    • Navigate to the Credentials Management section

    • Click “Generate Client ID & Secret”

    • Select “PROD Environment”

    • Fill out the Request for PROD Credentials form

    • Wait for Netbank to Approve your Prod Credentials Request

    • Take note of your Client ID and Client Secret

  • Requirements to get access:

    • Netbank Virtual Account (Sign Up to Netbank Virtual)

    • Prod Access Credentials (Generated via the Credentials Management section of the Partner Dashboard)

    • Information on the product/service that you are building

    • Banking-As-A-Service License Agreement (Signed)

    • Any other relevant agreements (Signed)

    • UAT Sign-Off (to indicate that you’ve fully tested the integration in all possible scenarios and that it’s ready for Production-Use)

The Netbank Virtual APIs utilizes OAuth 2.0–a popular and widely used protocol–to authenticate the API requests. Please use this documentation as guide on how to implement the authentication flow: https://oauth.net/2/

• Access Token

  • the Netbank APIs require an Access Token to process any type of API request (GET, POST, PUT).

  • An Access Token can be generated after successfully requesting for authorization and getting an Authorization Grant.

  • The Netbank Virtual Access Token has a default validity of 1 hour. (Netbank can grant long-lived tokens depending on the risk assessment during onboarding)

• Authorization Grant

  Netbank Virtual supports 2 ways (or “Grant Types”) to get an Authorization Grant depending on the transaction scenario and the type of authorization needed

  • If the API User is trying to access/use a Netbank Bank Account that he/she owns,

    • the API User needs to request for authorization directly from Netbank’s Authorization Server

    • the type of Authorization Grant to be used would be the “Client Credentials” (Client ID and Client Secret). Please use this documentation as guide on how to implement the authentication flow: https://oauth.net/2/

    • The Client ID and Secret for this type of Authorization Grant can be generated by accessing the Partner Dashboard and navigating to the “Credentials Management” > “Environment Access Credentials” > “Generate Client ID & Secret”

  • If the API User is trying to access/use a Netbank Bank Account of another entity/individual,

    • the API User needs to gather consent and request authorization directly from the Netbank account holder by directing the account holder to Netbank’s Authorization Server

    • the type of Authorization Grant to be used would be the “Authorization Code” (Client ID and Client Secret). Please use this documentation as guide on how to implement the authentication flow: https://oauth.net/2/

    • The Client ID and Secret for this type of Authorization Grant can be generated by accessing the Partner Dashboard and navigating to the “Credentials Management” > “Authentication Code” > “Generate Client ID & Secret”. The form needs to be filled out:

      • Name: Name/Label for your credentials

      • Environment: The development environment that you would use these credentials for. (“Sandbox”, “UAT”, “PROD”)

      • CORS URL: Describe which URL are permitted to read authorization information from a web browser

      • Redirect URL: The url where the user will be redirected after a successful authorization and where the Access Token will be posted

    • An end user's first-time multi-factor authentication (MFA) flow will consist of a three-step Security question, One Time Password (OTP) through SMS and Consent confirmation. A session cookie will stored in the user’s browser and will be valid for 30 days.

    • When users have to do re-authentication they will directly go to the OTP page if the session cookie is still valid. If no cookie is present we default to first-time MFA flow.

• Authorization URLs

  • Auth Base URL: https://auth.netbank.ph

  • Authorization URL: https://auth.netbank.ph/oauth2/auth?userid={{customer_id of the account holder}}

  • Token URL: https://auth.netbank.ph/oauth2/token

  • Scopes

    • Execute a Transaction: https://auth.netbank.bnk.to/transaction.write

    • Offline Access: offline_access

    • OpenID Connect: openid

During negative scenarios, our APIs would provide 3 identifiers to indicate what the issue is. We suggest to pattern your error handling based on these levels of reference:

• HTTP Response Status Code: This indicates the standard response of an HTTP request.

• Error Code: these are the well defined status codes that gRPC uses.

• Error Message: this will indicate the error description coming from our core system.

• Settlement Rails Error Code

ISO 20022 is a global standard for exchanging electronic messages between financial institutions. There are a lot of different messaging formats in the financial section so it is essential to make use of a common standard to get everyone on the same page.

Netbank Virtual APIs use the gRPC status codes to further classify the success or failure of an API request. **Those highlighted in blue are the codes that are mostly used by our APIs.

Idempotency simply refers to the API design principle that ensures that multiple identical API requests should return the same and original response of the initial request instead of reprocessing the operation. The Netbank Virtual APIs are designed to be idempotent in order to:

• Avoid unintentional duplicate API requests

  This protects our API users from the risk of unintentional reprocessing of transactions due to the mistake of re-sending the same API request twice or more.

• Retrieve the API Response in the event of an API Request Timeout

  This also serves as a mechanism to retrieve the original response of a request in the event that the API call has timed out due to network interruptions or other causes.

How does it work:

• Our GET APIs are idempotent by nature given that these APIs retrieve information or data from our database. As such, sending multiple identical requests will return the same response.

• Our POST and PUT APIs can be made idempotent by passing a unique id in the idempotency-key header parameter as part of the API request. Sending a request payload and a idempotency-key that is identical to a previous request and key would simply return the response of the original request without processing the second identical request.

• In case of an API request timeout, simply resend the same request with the same idempotency-key.

  • If the original request successfully pushed through and was processed in our system, the API would simply return the response of the original request.

  • If the original request did not reach our system, we would process the second request and return a response just like a regular API call.

• When you start to use our APIs either in UAT or PROD, we will create a dedicated “Branch” for you in our core banking system where all your customers, accounts, and transactions would be associated/recorded. This allows us to create a silo for your activities with us to keep it private, secure, and exclusive to your application.

PRODUCT OVERVIEW

PRODUCT OVERVIEW