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 30 Days. (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 365 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.

Virtual Collection Accounts (VCA) is one of Netbank’s Banking-as-a-Service solutions that enables you, our Partners, to accept fully- traceable bank transfer payments from clients.

Through this solution, you are able to freely generate and assign reference numbers that act as virtual accounts that you can provide to your payors. These virtual accounts act as beneficiary account numbers for payors to transfer funds to.

The funds credited to virtual accounts are settled in your Netbank Corporate Account, enabling easier reconciliation.

To illustrate, let’s suppose you have a Netbank Corporate Bank Account Number which is 123-111-99999-1.

Instead of providing that account number to your payors, you can assign a Virtual Collection Account to a payor as a destination account when they make payments via fund transfer. For the purposes of this illustration, let’s say that the VCA assigned to customer A is “999971234567”.

When the payment to VCA “999971234567” is made, funds are credited to your Netbank Corporate Bank Account Number 123-111- 99999-1. Since both the assignment and generation of the VCA was done on your end, you should now be able to reconcile what the payment is for or who the payment was from.

There are generally no (or very minimal) APIs needed to integrate VCAs, making it a very flexible plug-and-play solution for Partners looking to implement a collection solution.

You also can receive notifications directly from our system to yours via webhooks as soon as we receive the inbound transaction.

Generating Virtual Collection Accounts do not require any API integration. Instead, it is a standard format of generating the accounts that simply need to be followed. VCA numbers are generally 12-digit numbers that are comprised of:

5-digit Partner Alias + 7-digit Reference Number

Netbank will assign the 5-digit Partner Alias while the rest of the VCA number can freely be assigned by you or your system.

To enable Netbank to assign your Partner Alias, you will need to provide Netbank your nominated Netbank Corporate Account that will receive the payments credited to VCAs.

Virtual Collection Accounts are highly-flexible.

You can use VCAs by assigning them on a per-invoice basis where your payors will remit to different VCAs per transaction.

On the flipside, you can use VCAs by assigning them similar to a dedicated bank account where your users will remit to the same VCA for all of their transactions.

However you decide, Netbank does not need to be notified on your preferred use-case.

The VCA being a collection solution, allows for easier payment reconciliation. As you have visibility of the VCA that your payors are crediting, once funds are received, tagging payables as paid is much easier. This also eliminates the extra step for payors to send a proof of payment.

For fintechs and businesses looking to roll out a collection solution that is readily available to as many payors as possible, VCAs are recognized by the rails of Instapay and Pesonet. This means that payors, using their own banking or e-wallet apps, can immediately transfer funds to VCAs. There is no need to integrate separately with popular platforms like GCash, Maya, Unionbank or BPI which can be tedious, costly and time-consuming.

As VCAs are essentially a masking of your Netbank Corporate account, whenever a fund transfer occurs, they are settled directly with Netbank. The settlement schedule follows solely that of Instapay and Pesonet, eliminating clearing delays that are commonly experienced with other payment aggregators where there is normally further batching and crediting.

The user journey of paying a VCA is simple and straightforward: users log on to their favorite banking or e-wallet apps (GCash, Maya, Unionbank, BDO, BPI, etc)

1. Select the option where can perform a fund transfer (normally labelled “Transfer” or “Send Money to Other Banks”),

2. Look for “Netbank” in the list of banks,

3. Enter the amount, the account name of your Netbank Corporate Account and the VCA as the destination account number.

There are several ways to confirm if a payment into a VCA has been received, allowing for great flexibility for system and operational integration for your apps/platforms or workflow.

1. Via the Channel Transactions page of the Netbank Virtual Partner Dashboard, you can view funds you have received in the UAT and PRODUCTION environment under the Collect Tab. Transaction details are displayed in an easy-to-understand and straightforward tabular format that includes the destination VCA that the funds were paid to.

   

2. We can register an endpoint that you will expose in order to receive credit notification webhooks. You may refer to the documentation on webhooks here for further information.

3. Via our Retrieve Bank Account Transaction History API endpoint, you can use a VCA number in the path parameter to obtain a list of transactions. Kindly refer to our API documentation for further details.

Generating QRPH images for Virtual Collection Accounts is also possible. Kindly refer to our API documentation here.

You can use a specific Virtual Collection Account as the “destination_account” in the Generate QRPH Image endpoint. This way, payors would not have to manually type in their target VCA when performing a fund transfer but instead, upload or scan a QR image. This minimizes or even eliminates the possibility of payors transferring to erroneous account details.

There is little to no API integration that would need to be done to implement Virtual Collection Accounts to your system.

In order to commence testing, you may contact your Client Success Manager via support@netbank.ph or an alternative communication point that they have established for you to receive assistance during integration. Your client Success Managers would ask you for

1. The UAT bank account account (that you have opened via the Netbank Virtual Partner Dashboard) where your assigned 5-digit Partner Alias would be associated and

2. A URL endpoint that you have exposed where we can push credit notification webhooks.

To simulate incoming transfers in the UAT environment, kindly utilize Netbank’s Process Account-To-Account Fund Transfer API. You can open and nominate another UAT bank account and designate it as your source account.

Feel free to reach out to your Client Success Managers for assistance on testing and other questions.

PRODUCT OVERVIEW

PRODUCT OVERVIEW