Netbank Digital API (0.0.1)

Download OpenAPI specification:Download

GENERAL GUIDELINES

INTRODUCTION

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.

DEVELOPMENT ENVIRONMENTS

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)

AUTHENTICATION

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

  • Authorization URLs

ERROR HANDLING

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.

REASON FOR REJECTION

  • 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.

CODE LABEL DEFINITION
AC01 IncorrectAccountNumber Format of the account number specified is not correct
AC02 InvalidDebtorAccountNumber Debtor account number invalid or missing
AC03 InvalidCreditorAccountNumber Wrong IBAN in SCT
AC04 ClosedAccountNumber Account number specified has been closed on the bank of account's books
AC05 ClosedDebtorAccountNumber Debtor account number closed
AC06 BlockedAccount Account specified is blocked, prohibiting posting of transactions against it.
AC07 ClosedCreditorAccountNumber Creditor account number closed
AC08 InvalidBranchCode Branch code is invalid or missing
AC09 InvalidAccountCurrency Account currency is invalid or missing
AC10 InvalidDebtorAccountCurrency Debtor account currency is invalid or missing
AC11 InvalidCreditorAccountCurrency Creditor account currency is invalid or missing
AC12 InvalidAccountType Account type missing or invalid Generic usage if cannot specify between group and payment information levels
AC13 InvalidDebtorAccountType Debtor account type is missing or invalid
AC14 InvalidAgent An agent in the payment chain is invalid.
AG01 TransactionForbidden Transaction forbidden on this type of account (formerly NoAgreement)
AG02 InvalidBankOperationCode Bank Operation code specified in the message is not valid for receiver
AG03 TransactionNotSupported Transaction type not supported/authorized on this account
AG04 InvalidAgentCountry Agent country code is missing or invalid Generic usage if cannot specify between group and payment information levels
AG05 InvalidDebtorAgentCountry Debtor agent country code is missing or invalid
AG06 InvalidCreditorAgentCountry Creditor agent country code is missing or invalid
AG07 UnsuccesfulDirectDebit Debtor accounts cannot be debited for a generic reason. Code value may be used in general purposes and as a replacement for AM04 if debtor bank does not reveal its customer's insufficient funds for privacy reasons
AG08 InvalidAccessRights Transaction failed due to invalid or missing user or access right
AGNT IncorrectAgent Agent in the payment workflow is incorrect
AM01 ZeroAmount Specified message amount is equal to zero
AM02 NotAllowedAmount Specific transaction/message amount is greater than allowed maximum
AM03 NotAllowedCurrency Specified message amount is a non processable currency outside of existing agreement
AM04 InsufficientFunds Amount of funds available to cover the specified message amount is insufficient.
AM05 Duplication Duplication
AM06 TooLowAmount Specified transaction amount is less than agreed minimum
AM07 BlockedAmount Amount of funds available to cover the specified message amount is insufficient.
AM09 WrongAmount Amount received is not the amount agreed or expected
AM10 InvalidControlSum Sum of instructed amounts does not equal the control sum.
AM11 InvalidTransactionCurrency Transaction currency is invalid or missing
AM12 InvalidAmount Amount is invalid or missing
AM13 AmountExceedsClearingSystemLimit Transaction amount exceeds limits set by clearing system
AM14 AmountExceedsAgreedLimit Transaction amount exceeds limits agreed between bank and client
AM15 AmountBelowClearingSystemMinimum Transaction amount below minimum set by clearing system
AM16 InvalidGroupControlSum Control Sum at the Group level is invalid
AM17 InvalidPaymentInfoControlSum Control Sum at the Payment Information level is invalid
AM18 InvalidNumberOfTransactions Number of transactions is invalid or missing Generic usage if cannot specify between group and payment information levels
AM19 InvalidGroupNumberOfTransactions Number of transactions at the Group level is invalid or missing
AM20 InvalidPaymentInfoNumberOfTransactions Number of transactions at the Payment Information level is invalid
AM21 LimitExceeded Transaction amount exceeds limits agreed between bank and client.
ARDT AlreadyReturnedTransaction Already returned original SCT
ARPL AwaitingReply Reported when the cancellation request cannot be processed because no reply has been received yet from the receiver of the request message.
BE01 InconsistenWithEndCustomer Identification of the end customer is not consistent with associated account number (formerly CreditorConsistency).
BE04 MissingCreditorAddress Specification of creditor's address, which is required for payment, is missing/not correct (formerly IncorrectCreditorAddress).
BE05 UnrecognisedInitiatingParty Party who initiated the message is not recognised bythe end customer
BE06 UnknownEndCustomer End customer specified is not known at associated Sort/National Bank Code or does no longer exist in the books
BE07 MissingDebtorAddress Specification of debtor's address, which is required for payment, is missing/not correct.
BE08 BankError Party who initiated the message is not recognised by the end customer Returned as a result of a bank error.
BE09 InvalidCountry Country code is missing or Invalid Generic usage if cannot specifically identify debtor or creditor
BE10 InvalidDebtorCountry Debtor country code is missing or Invalid
BE11 InvalidCreditorCountry Creditor country code is missing or Invalid
BE12 InvalidCountryOfResidence Country code of residence is missing or Invalid Generic usage if cannot specifically identify debtor or creditor
BE13 InvalidDebtorCountryOfResidence Country code of debtor's residence is missing or Invalid
BE14 InvalidCreditorCountryOfResidence Country code of creditor's residence is missing or Invalid
BE15 InvalidIdentificationCode Identification code missing or invalid Generic usage if cannot specifically identify debtor or creditor
BE16 InvalidDebtorIdentificationCode Debtor or Ultimate Debtor identification code missing or invalid
BE17 InvalidCreditorIdentificationCode Creditor or Ultimate Creditor identification code missing or invalid
BE18 InvalidContactDetails Contact details missing or invalid
BE19 InvalidChargeBearerCode Charge bearer code for transaction type is invalid
BE20 InvalidNameLength Name length exceeds local rules for payment type.
BE21 MissingName Name missing or invalid Generic usage if cannot specifically identify debtor or creditor
BE22 MissingCreditorName Creditor name is missing
CH03 RequestedExecutionDateOrRequestedCollectionDateTooFarInFuture Value in Requested Execution Date or Requested Collection Date is too far in the future
CH04 RequestedExecutionDateOrRequestedCollectionDateTooFarInPast Value in Requested Execution Date or Requested Collection Date is too far in the past
CH07 ElementIsNotToBeUsedAtB-andC-Level Element is not to be used at B- and C-Level
CH09 MandateChangesNotAllowed Mandate changes are not allowed
CH10 InformationOnMandateChangesMissing Information on mandate changes are missing
CH11 CreditorIdentifierIncorrect Value in Creditor Identifier is incorrect
CH12 CreditorIdentifierNotUnambiguouslyAtTransaction-Level Creditor Identifier is ambiguous at Transaction Level
CH13 OriginalDebtorAccountIsNotToBeUsed Original Debtor Account is not to be used
CH14 OriginalDebtorAgentIsOnlyToBeUsedWithSequenceTypeFRST Original Debtor Agent is only to be used with SequenceType=FRST
CH15 ElementContentIncludesMoreThan140Characters Content Remittance Information/Structured includes more than 140 characters
CH16 ElementContentFormallyIncorrect Content is incorrect
CH17 ElementNotAdmitted Element is not allowed
CH19 ValuesWillBeSetToNextTARGETday Values in Interbank Settlement Date or Requested Collection Date will be set to the next TARGET day
CH20 DecimalPointsNotCompatibleWithCurrency Number of decimal points not compatible with the currency
CH21 RequiredCompulsoryElementMissing Mandatory element is missing
CH22 COREandB2BwithinOnemessage SDD CORE and B2B not permitted within one message
CN01 AuthorisationCancelled Authorisation is canceled.
CNOR Creditor bank is not registered Creditor bank is not registered under this BIC in the CSM
CURR IncorrectCurrency Currency of the payment is incorrect
CUST RequestedByCustomer Cancellation requested by the Debtor
DNOR Debtor bank is not registered Debtor bank is not registered under this BIC in the CSM
DS01 ElectronicSignaturesCorrect The electronic signature(s) is/are correct
DS02 OrderCancelled An authorized user has canceled the order
DS03 OrderNotCancelled The user’s attempt to cancel the order was not successful
DS04 OrderRejected The order was rejected by the bank side (for reasons concerning content)
DS05 OrderForwardedForPostprocessing The order was correct and could be forwarded for post processing
DS06 TransferOrder The order was transferred to VEU
DS07 ProcessingOK All actions concerning the order could be done by the EBICS bank server
DS08 DecompressionError The decompression of the file was not successful
DS09 DecryptionError The decryption of the file was not successful
DS0A DataSignRequested Data signature is required.
DS0B UnknownDataSignFormat Data signature for the format is not available or invalid.
DS0C SignerCertificateRevoked The signer certificate is revoked.
DS0D SignerCertificateNotValid The signer certificate is not valid (revoked or not active).
DS0E IncorrectSignerCertificate The signer certificate is not present.
DS0F SignerCertificationAuthoritySignerNotValid The authority of the signer certification sending the certificate is unknown.
DS0G NotAllowedPayment Signers are not allowed to sign this operation type.
DS0H NotAllowedAccount Signers are not allowed to sign for this account.
DS0K NotAllowedNumberOfTransaction The number of transactions is over the number allowed for this signer.
DS10 Signer1CertificateRevoked The certificate is revoked for the first signer.
DS11 Signer1CertificateNotValid The certificate is not valid (revoked or not active) for the first signer.
DS12 IncorrectSigner1Certificate The certificate is not present for the first signer.
DS13 SignerCertificationAuthoritySigner1NotValid The authority of signer certification sending the certificate is unknown for the first signer.
DS14 UserDoesNotExist The user is unknown on the server
DS15 IdenticalSignatureFound The same signature has already been sent to the bank
DS16 PublicKeyVersionIncorrect The public key version is not correct. This code is returned when a customer sends signature files to the financial institution after conversion from an older program version (old ES format) to a new program version (new ES format) without having carried out re-initialisation with regard to a public key change.
DS17 DifferentOrderDataInSignatures Order data and signatures don’t match
DS18 RepeatOrder File cannot be tested, the complete order has to be repeated. This code is returned in the event of a malfunction during the signature check, e.g. not enough storage space.
DS20 Signer2CertificateRevoked The certificate is revoked for the second signer.
DS21 Signer2CertificateNotValid The certificate is not valid (revoked or not active) for the second signer.
DS22 IncorrectSigner2Certificate The certificate is not present for the second signer.
DS23 SignerCertificationAuthoritySigner2NotValid The authority of signer certification sending the certificate is unknown for the second signer.
DS24 WaitingTimeExpired Waiting time expired due to incomplete order
DS25 OrderFileDeleted The order file was deleted by the bank server(for multiple reasons)
DS26 UserSignedMultipleTimes The same user has signed multiple times
DS27 UserNotYetActivated The user is not yet activated (technically)
DS28 ReturnForTechnicalReason Return following technical problems resulting in erroneous transactions.
DT01 InvalidDate Invalid date (eg, wrong or missing settlement date)
DT02 InvalidCreationDate Invalid creation date and time in Group Header (eg, historic date)
DT03 InvalidNonProcessingDate Invalid non bank processing date (eg, weekend or local public holiday)
DT04 FutureDateNotSupported Future date not supported
DT05 InvalidCutOffDate Associated message, payment information block or transaction was received after an agreed processing cut-off date, i.e., date in the past.
DT06 ExecutionDateChanged Execution Date has been modified in order for transaction to be processed
DU01 DuplicateMessageID Message Identification is not unique.
DU02 DuplicatePaymentInformationID The Payment Information Block is not unique.
DU03 DuplicateTransaction Transactions are not unique.
DU04 DuplicateEndToEndID End To End ID is not unique.
DU05 DuplicateInstructionID Instruction ID is not unique.
DUPL DuplicatePayment Payment is a duplicate of another payment
ED01 CorrespondentBankNotPossible Corresponding bank is not not possible.
ED03 BalanceInfoRequest Balance of payments complementary info is requested
ED05 SettlementFailed Settlement of the transaction has failed.
EMVL EMV Liability Shift The card payment is fraudulent and was not processed with EMV technology for an EMV card.
ERIN ERIOptionNotSupported The Extended Remittance Information (ERI) option is not supported.
FF01 Invalid File Format File Format incomplete or invalid
FF02 SyntaxError Syntax error reason is provided as narrative information in the additional reason information.
FF03 InvalidPaymentTypeInformation Payment Type Information is missing or invalid Generica usage if cannot specify Service Level or Local Instrument code
FF04 InvalidServiceLevelCode Service Level code is missing or invalid
FF05 InvalidLocalInstrumentCode Local Instrument code is missing or invalid
FF06 InvalidCategoryPurposeCode Category Purpose code is missing or invalid
FF07 InvalidPurpose Purpose is missing or invalid
FF08 InvalidEndToEndId End to End Id missing or invalid
FF09 InvalidChequeNumber Cheque number missing or invalid
FF10 BankSystemProcessingError File or transaction cannot be processed due to technical issues at the bank side
FOCR FollowingCancellationRequest Return following a cancellation request
FR01 Fraud Returned as a result of fraud.
FRTRF FinalResponseMandate Canceled Final response/tracking is recalled as the mandate is canceled.
ID01 CorrespondingOriginalFileStillNotSent Signature file was sent to the bank but the corresponding original file has not been sent yet.
LEGL LegalDecision Reported when the cancellation cannot be accepted because of regulatory rules.
MD01 NoMandate No Mandate
MD02 MissingMandatoryInformationIn Mandate Mandate related information data required by the scheme is missing.
MD05 CollectionNotDue Creditor or creditor's agent should not have collected the direct debit
MD06 RefundRequestByEndCustomer Return of funds requested by end customer
MD07 EndCustomerDeceased End customer is deceased.
MS02 NotSpecifiedReasonCustomerGenerated Reason has not been specified by end customer
MS03 NotSpecifiedReasonAgentGenerated Reason has not been specified by agent.
NARR Narrative Reason is provided as narrative information in the additional reason information.
NOAS NoAnswerFromCustomer No response from Beneficiary
NOCM NotCompliant Customer accounts are not compliant with regulatory requirements, for example FICA (in South Africa) or any other regulatory requirements which render an account inactive for certain processing.
NOOR NoOriginalTransactionReceived Original SCT never received
PINL PIN Liability Shift The card payment is fraudulent (lost and stolen fraud) and was processed as an EMV transaction without PIN verification.
PTNA PassedtoTheNextAgent Reported when the cancellation request cannot be accepted because the payment instruction has been passed to the next agent.
RC01 BankIdentifierIncorrect The Bank Identifier code specified in the message has an incorrect format (formerly IncorrectFormatForRoutingCode).
RC02 InvalidBankIdentifier Bank identifier is invalid or missing Generic usage if cannot specify between debit or credit account
RC03 InvalidDebtorBankIdentifier Debtor bank identifier is invalid or missing
RC04 InvalidCreditorBankIdentifier Creditor bank identifier is invalid or missing
RC05 InvalidBICIdentifier BIC identifier is invalid or missing Generic usage if cannot specify between debit or credit account
RC06 InvalidDebtorBICIdentifier Debtor BIC identifier is invalid or missing
RC07 InvalidCreditorBICIdentifier Creditor BIC identifier is invalid or missing
RC08 InvalidClearingSystemMemberIdentifier ClearingSystemMemberidentifier is invalid or missing Generic usage if cannot specify between debit or credit account
RC09 InvalidDebtorClearingSystemMemberIdentifier Debtor ClearingSystemMember identifier is invalid or missing
RC10 InvalidCreditorClearingSystemMemberIdentifier Creditor ClearingSystemMember identifier is invalid or missing
RC11 InvalidIntermediaryAgent Intermediary Agent is invalid or missing
RC12 MissingCreditorSchemeId Creditor Scheme Id is invalid or missing
RF01 NotUniqueTransactionReference Transaction reference is not unique within the message.
RR01 Missing Debtor Account or Identification Specification of the debtor’s account or unique identification needed for reasons of regulatory requirements is insufficient or missing
RR02 Missing Debtor Name or Address Specification of the debtor’s name and/or address needed for regulatory requirements is insufficient or missing.
RR03 Missing Creditor Name or Address Specification of the creditor’s name and/or address needed for regulatory requirements is insufficient or missing.
RR04 Regulatory Reason Regulatory Reason
RR05 RegulatoryInformationInvalid Regulatory or Central Bank Reporting information missing, incomplete or invalid.
RR06 TaxInformationInvalid Tax information missing, incomplete or invalid.
RR07 RemittanceInformationInvalid Remittance information structure does not comply with rules for payment type.
RR08 RemittanceInformationTruncated Remittance information truncated to comply with rules for payment type.
RR09 InvalidStructuredCreditorReference Structured creditor reference invalid or missing.
RR10 InvalidCharacterSet Character set supplied not valid for the country and payment type.
RR11 InvalidDebtorAgentServiceID Invalid or missing identification of a bank proprietary service.
RR12 InvalidPartyID Invalid or missing identification required within a particular country or payment type.
RUTA ReturnUponUnableToApply Return following investigation request and no remediation possible.
SL01 Specific Service offered by Debtor Agent Due to specific service offered by the Debtor Agent
SL02 Specific Service offered by Creditor Agent Due to specific service offered by the Creditor Agent
SL11 Creditor not on Whitelist of Debtor Whitelisting service offered by the Debtor Agent; Debtor has not included the Creditor on its “Whitelist” (yet). In the Whitelist the Debtor may list all allowed Creditors to debit Debtor bank accounts.
SL12 Creditor on Blacklist of Debtor Blacklisting service offered by the Debtor Agent; Debtor included the Creditor on his “Blacklist”. In the Blacklist the Debtor may list all Creditors not allowed to debit Debtor bank accounts.
SL13 Maximum number of Direct Debit Transactions exceeded Due to Maximum allowed Direct Debit Transactions per period service offered by the Debtor Agent.
SL14 Maximum Direct Debit Transaction Amount exceeded Due to Maximum allowed Direct Debit Transaction amount service offered by the Debtor Agent.
SP01 PaymentStopped Payment is stopped by the account holder.
SP02 PreviouslyStopped Previously stopped by means of a stop payment advice.
SVNR ServiceNotRendered The card payment is returned since a cash amount rendered was not correct or goods or a service was not rendered to the customer, e.g. in an ecommerce situation.
SYAD RequestToSettlementSystemAdministrator Cancellation requested by System Member to Settlement System Administrator to indicate that the cancellation request must not be forwarded further in the chain.
TA01 TransmissonAborted The transmission of the file was not successful – it had to be aborted (for technical reasons)
TD01 NoDataAvailable There is no data available (for download)
TD02 FileNonReadable The file cannot be read (e.g. unknown format)
TD03 IncorrectFileStructure The file format is incomplete or invalid
TECH TechnicalProblem Cancellation requested following technical problems resulting in an erroneous transaction.
TM01 InvalidCutOffTime Formerly: CutOffTime Associated message, payment information block or transaction was received after agreed processing cut-off time.
TRAC RemovedFromTracking Return following direct debit being removed from tracking process.
TS01 TransmissionSuccessful The (technical) transmission of the file was successful.
TS04 TransferToSignByHand The order was transferred to pass by accompanying note signed by hand
UPAY UnduePayment Payment is not justified.

HTTP RESPONSE CODES

Code Label Description
200 OK Processing is successful
400 BAD REQUEST The request payload has a missing parameter and/or invalid format
403 FORBIDDEN The call does not have the proper authentication
404 NOT FOUND The resource that is being retrieved is not existing
500 INTERNAL SERVER ERROR There is an issue in processing the request

ERROR CODES

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.

Code Label Description
0 OK Not an error; returned on success.
1 CANCELLED The operation was cancelled, typically by the caller.
2 UNKNOWN Unknown error. For example, this error may be returned when a Status value received from another address space belongs to an error space that is not known in this address space. Also errors raised by APIs that do not return enough error information may be converted to this error.
3 INVALID_ARGUMENT The client specified an invalid argument. Note that this differs from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name)
4 DEADLINE_EXCEEDED The deadline expired before the operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long
5 NOT_FOUND Some requested entity (e.g., file or directory) was not found. Note to server developers: if a request is denied for an entire class of users, such as gradual feature rollout or undocumented allowlist, NOT_FOUND may be used. If a request is denied for some users within a class of users, such as user-based access control, PERMISSION_DENIED must be used.
6 ALREADY_EXISTS The entity that a client attempted to create (e.g., file or directory) already exists.
7 PERMISSION_DENIED The caller does not have permission to execute the specified operation. PERMISSION_DENIED must not be used for rejections caused by exhausting some resource (use RESOURCE_EXHAUSTED instead for those errors). PERMISSION_DENIED must not be used if the caller can not be identified (use UNAUTHENTICATED instead for those errors). This error code does not imply the request is valid or the requested entity exists or satisfies other pre-conditions.
8 RESOURCE_EXHAUSTED Some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
9 FAILED_PRECONDITION The operation was rejected because the system is not in a state required for the operation's execution. For example, the directory to be deleted is non-empty, an rmdir operation is applied to a non-directory, etc. Service implementors can use the following guidelines to decide between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE: (a) Use UNAVAILABLE if the client can retry just the failing call. (b) Use ABORTED if the client should retry at a higher level (e.g., when a client-specified test-and-set fails, indicating the client should restart a read-modify-write sequence). (c) Use FAILED_PRECONDITION if the client should not retry until the system state has been explicitly fixed. E.g., if an "rmdir" fails because the directory is non-empty, FAILED_PRECONDITION should be returned since the client should not retry unless the files are deleted from the directory.
10 ABORTED The operation was aborted, typically due to a concurrency issue such as a sequencer check failure or transaction abort. See the guidelines above for deciding between FAILED_PRECONDITION, ABORTED, and UNAVAILABLE.
11 OUT_OF_RANGE The operation was attempted past the valid range. E.g., seeking or reading past end-of-file. Unlike INVALID_ARGUMENT, this error indicates a problem that may be fixed if the system state changes. For example, a 32-bit file system will generate INVALID_ARGUMENT if asked to read at an offset that is not in the range [0,2^32-1], but it will generate OUT_OF_RANGE if asked to read from an offset past the current file size. There is a fair bit of overlap between FAILED_PRECONDITION and OUT_OF_RANGE. We recommend using OUT_OF_RANGE (the more specific error) when it applies so that callers who are iterating through a space can easily look for an OUT_OF_RANGE error to detect when they are done.
12 UNIMPLEMENTED The operation is not implemented or is not supported/enabled in this service.
13 INTERNAL Internal errors. This means that some invariants expected by the underlying system have been broken. This error code is reserved for serious errors.
14 UNAVAILABLE The service is currently unavailable. This is most likely a transient condition, which can be corrected by retrying with a backoff. Note that it is not always safe to retry non-idempotent operations.
15 DATA_LOSS Unrecoverable data loss or corruption.
16 UNAUTHENTICATED The request does not have valid authentication credentials for the operation.

API TIMEOUT HANDLING AND IDEMPOTENCY

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 s