@noda-ui/open-banking
Installation
npm i @noda-ui/open-banking
#or
yarn add @noda-ui/open-banking
Usage
<body>
<noda-open-banking-widget id="payment-widget"><noda-open-banking-widget>
</body>import "@noda-ui/open-banking/lib/index.js";
import "@noda-ui/open-banking/lib/styles/styles.css";
const $payment = document.querySelector("#payment-widget");
const params: OpenBankingWidgetParams = {
// * Required
apiKey: string;
amount: number;
returnUrl: string;
currency: string;
paymentId: string;
// * Not Required
language: OpenBankingLanguage;
env: OpenBankingEnv;
webhookUrl: string;
shopId: string;
description: string;
customerId: string;
email: string;
iin: number;
ipAddress: string;
fullWidth: boolean;
disabledPaymentButton: boolean;
country: string;
}
$payment.initWithParams(params);
$payment.addEventListener("result", (event: OpenBankingResult) => {
console.log("event after pay: ", event.detail); // OpenBankingResult
});
// * If you need change params
$payment.setParams(params: OpenBankingPaymentParams)
#or
const paramKey: keyof OpenBankingPaymentParams = 'amount';
const paramValue: typeof OpenBankingPaymentParams['amount'] = 100
const isRestartPayment: boolean = false;
$payment.setParam(paramKey, paramValue, isRestartPayment)OpenBankingWidgetParams
| Field | Type | Description | Default |
|---|---|---|---|
| apiKey *required | string | Merchant's api key, issued by Noda | null |
| amount *required | number | Payment amount | null |
| returnUrl *required | string | After the payment completed, customer will be redirected into this Url | null |
| currency *required | string | Payment currency in ISO_4217 format. | null |
| paymentId *required | string | Order identificator in merchant's system | null |
| language | OpenBankingLanguage | Widget Language | "en" |
| env | OpenBankingEnv | App environments, for develop and production. Currently accepted: {PRODUCTION, DEVELOPMENT} | "PRODUCTION" |
| skipRedirect | boolean | Redirect to "returnUrl" after payment result event | false |
| webhookUrl | string | URL where the Noda will send hooks about the payment status changes | null |
| shopId | string | Merchant's shop identificator, issued by Noda. If you have more than one online shop, this parameter helps to analyse the payments afterwards | null |
| description | string | Short order description for the customer | null |
| customerId | string | End-customer Id in merchant's system. That parameter can be used to find a best button appearance for the particular customer. | null |
| string | End-customer e-mail. That parameter can be used to find a best button appearance for the particular customer. | null | |
| iin | number | IIN (first six digits) of the end-customers credit card used earlier at the merchant's checkout. This parameter helps to define end-customer Bank and propose to pay with that bank. | null |
| ipAddress | string | End-customer IP Address. That parameter can be used to detect a customer's country (for example, for EUR payments - Spain, Germany, France etc.) | null |
| fullWidth | boolean | Full width on screen for payment button | false |
| disabledPaymentButton | object | Disabled payment button | false |
| country | object | ISO 3166-1 alpha-2 country code | null |
OpenBankingResult
| Field | Type | Description |
|---|---|---|
| id | string | Payment identificator in Noda system |
| result | 'done' | 'failed' | 'awaiting confirmation' | Payment status |
| signature | string | Signature: sha256(id+status+signatureKey) |
Output events
| Event | Type | Description |
|---|---|---|
| result | OpenBankingResult | triggered after receiving a payment response |
Library types
type OpenBankingEnv = 'PRODUCTION' | 'DEVELOPMENT';type OpenBankingLanguage = 'en' | 'de' | 'es' | 'fr';interface OpenBankingPaymentParams {
amount?: number;
returnUrl?: string;
currency?: string;
paymentId?: string;
webhookUrl?: string;
shopId?: string;
description?: string;
customerId?: string;
email?: string;
iin?: number;
ipAddress?: string;
country?: string;
}Payment Result handling
You can receive payment result with the following options:
- Parameters in returnUrl After the payment completed, customer will be redirected into returnUrl with the Payment Result parameters in query string:
https://{domain}?id=63c507d9-4f19-46d0-ac37-5b7d4f6fe040&result=done&signature=6ec13bda02080a4006223c1ba9d8fa97e2de0a1ca782d95d63f4b69789117cc6- Receive a hook into webhookUrl If you passed webhookUrl earlier, you will receive the hook as POST request with the Payment Result parameters as JSON body (example):
{
id: "63c507d9-4f19-46d0-ac37-5b7d4f6fe040",
result: "done",
signature: "6ec13bda02080a4006223c1ba9d8fa97e2de0a1ca782d95d63f4b69789117cc6"
}For the returnUrl and webhookUrl handling methods, make sure to implement the proper payment control procedures
Control procedures
If you're using returnUrl and/or webhookUrl for the results handling, it is mandatory to implement a simple control procedure in order to prevent fraudulent behaviour. After receiving the results you will need to do the following:
- Verify the payment signature parameter The signature can be verified with the following algorythm:
signature == sha256(id + status + signatureKey);-
Check the duplicates of signatures
You will need to make sure the payment result belongs to the concrete order you are about to proceed. Intruders can not create a valid Signature unless they know your SignatureKey. However, they can intercept the result message and then re-use its Signature. In order to prevent this action, you will need to implemenent anti-duplication control algorythm. For example, you can compare the paymentId of the current order and in the payment result.
Security
Remember to use valid api token for apiKey field.
How to obtain the keys?
Sanodaox: use 24d0034-5a83-47d5-afa0-cca47298c516 for DEVELOPMENT environment. Live: use 808e683e-9383-4717-8148-02e74b63b1f8 for testing purposes.
Please consider, that this is a real payment routing which is set up to charity organisations complete the onboarding at ui.noda.live/hub to get your production keys
Payment UX
Please switch the "Purchase scenarios" at ui.noda.live/demo in order to overview the different behavior.
If you've used some additional parameters (for example - IP, IIN, CustomerID and so on) previosly, for the same purchase, we highly recommend pass the same additional parameters, in order to keep the consistent UX for the customers.
Webpack 5 Issues
During the integration process, you might face multiple issues with webpack 5. This issue is caused due to the fact that some packages have certain dependencies, which are not present within the browser environment by webpack 5. Hence, you require certain node polyfills to be added to your project, while overriding the configurations to enable their usage. When that is done, your project should run without any issues.
An alternative solution to the problem is to install @microsoft/signalr package in your project.
Alternative Payment Result
Please see the detailed description at docs.noda.live.