npm package: @noda-ui/sdk
Description: ## Installation ``` npm i @noda-ui/sdk -S #or yarn add @noda-ui/sdk ```
Latest version: 2.0.18

# @noda-ui/sdk

## Installation
```
npm i @noda-ui/sdk -S
#or
yarn add @noda-ui/sdk
```


## Usage
```html
<body>
    <div id="root"></div>
</body>
```

```javascript
import { NodaButton } from '@noda-ui/sdk'
import '@noda-ui/sdk/lib/ndb.css'

const paymentInfo = {
    apiKey: 'string',
    result: (...args) => {},
    onHistory: (...args) => {},
    currency: 'string',
    amount: 0,
    customerId: 'string',
    shopId: 'string',
    email: 'string',
    iin: 0,
    disabled: false,
    description: 'string',
    paymentId: 'string',
    returnUrl: 'string',
    webhookUrl: 'string',
    ipAddress: 'string',
    replaceWindow: false
}

const country = 'gb'
const env = 'PRODUCTION'

const root = document.getElementById('root')

NodaButton.render(root, env)
NodaButton.update(paymentInfo, country)
NodaButton.unmount(root)
```

### Usage with TypeScript
```typescript
declare module '@noda-ui/sdk'
```


## Parameters

### PaymentInfo
| Field | Type | Description |
| ----------- | ----------- | ----------- |
| apiKey **\*required** | string | Merchant's api key, issued by Noda |
| amount **\*required** | number<decimal> | Payment amount |
| currency **\*required** | string | Payment currency in ISO_4217 format. Currently accepted: {GBP, EUR} |
| returnUrl **\*required** | string | After the payment completed, customer will be redirected into this Url |
| paymentId **\*required** | string | Order identificator in merchant's system |
| webhookUrl | string | URL where the Noda will send hooks about the payment status changes |
| 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 |
| description | string | Short order description for the customer |
| customerId | string | End-customer Id in merchant's system. That parameter can be used to find a best button appearance for the particular customer. |
| email | string | End-customer e-mail. That parameter can be used to find a best button appearance for the particular customer. |
| iin | integer<int64> | 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. |
| 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.) |
| result | function | Payment completion callback function implemented by merchant |
| onHistory | function | Billing information changes callback function implemented by merchant |
| disabled | boolean | Noda Button component state |
| replaceWindow | boolean | Will replace the current window with bank page after bank selection |
| customerEmail **\*depricated** (use email field instead) | string | End-customer e-mail. That parameter can be used to find a best button appearance for the particular customer. |

### Country
| Field | Type | Description |
| ----------- | ----------- | ----------- |
| country **\*required** | string | ISO 3166-1 alpha-2 country code |

### Environment
| Field | Type | Description |
| ----------- | ----------- | ----------- |
| env | string | App environments, for develop and production. Currently accepted: {PRODUCTION, DEVELOPMENT}. Default: {PRODUCTION} |


## Methods
| Method | Parameters | Description |
| ----------- | ----------- | ----------- |
| render | HTMLElement, Enviroment | Render method inject button in DOM node, where root is an element id. Need only once |
| update | PaymentInfo, Country | Update method changes button view, state and payment scenario |
| unmount | HTMLElement | Unmount method removes button from the selected DOM node |


## Security
Remember to use valid api token for apiKey field.

### How to obtain the keys?
**Sandbox**: 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


## Creating a Payment
In order to initiate payment, pass the payment parameters into **update** method.

### Payment UX
Depending on the additional parameters passed, payment UX will be rather country-oriented (with the bank selection at the first step) or bank-oriented (with the particular bank pre-selected). 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.

### Payment Result parameters
| Parameter | Description |
| ----------- | ----------- |
| id | Payment identificator in Noda system |
| status | Payment status: {Done, Failed} |
| signature | Signature: sha256(id+status+signatureKey) |

### 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&status=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",
    status: "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.


## Api usage
See the [Noda API docs](https://noda.stoplight.io/docs/noda-pay-api).