npm package: @noda-ui/open-banking
Description: noda ui, open banking
Latest version: 1.0.3

# @noda-ui/open-banking

## Installation

```
npm i @noda-ui/open-banking
#or
yarn add @noda-ui/open-banking
```

## Usage

```html
<body>
  <noda-open-banking-widget id="payment-widget"><noda-open-banking-widget>
</body>
```

```typescript
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)

```

<!-- ### Usage with TypeScript

```typescript
declare module "@noda-ui/open-banking";
``` -->

### <font color="#6936d3">**OpenBankingWidgetParams**</font>

| 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         |
| email                    | 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         |

### <font color="#6936d3">**OpenBankingResult**</font>

| Field     | Type                                          | Description                               |
| --------- | --------------------------------------------- | ----------------------------------------- |
| id        | string                                        | Payment identificator in Noda system      |
| result    | 'done' \| 'failed' \| 'awaiting confirmation' | Payment status                            |
| signature | string                                        | Signature: sha256(id+status+signatureKey) |

### <font color="#6936d3">**Output events**</font>

| Event  | Type              | Description                                  |
| ------ | ----------------- | -------------------------------------------- |
| result | OpenBankingResult | triggered after receiving a payment response |

### <font color="#6936d3">**Library types**</font>

```typescript
type OpenBankingEnv = 'PRODUCTION' | 'DEVELOPMENT';
```

```typescript
type OpenBankingLanguage = 'en' | 'de' | 'es' | 'fr';
```

```typescript
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:

```html
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):

```javascript
{
    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:

```javascript
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](https://ui.noda.live/hub) to get your production keys

### **Payment UX**

Please switch the "Purchase scenarios" at [ui.noda.live/demo](https://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](https://www.npmjs.com/package/@microsoft/signalr) package in your project.

### **Alternative Payment Result**

Please see the detailed description at [docs.noda.live](https://docs.noda.live/docs/noda-pay-api/22989088c5b85-creating-a-payment#payment-result-handling).