@nnoda-ui/web-component
Installation
npm i @noda-ui/web-component -S
#or
yarn add @noda-ui/web-component
Usage
<body>
<noda-widget></noda-widget>
</body>import '@noda-ui/web-component';
import '@noda-ui/web-component/lib/styles.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 component = document.querySelector('noda-widget')
const update = (params, env, country) => {
if (component) {
if (params.onHistory) {
window.on__ndb__history = params.onHistory;
}
if (params.onResult) {
window.on__ndb__result = params.onResult;
}
component.params = JSON.stringify({ env, country: country.toUpperCase(), ...params });
}
}
const unmount = () => {
component.remove()
}
update(paymentInfo)Usage with TypeScript
declare module '@noda-ui/web-component'Parameters
PaymentInfo
| Field | Type | Description |
|---|---|---|
| apiKey *required | string | Merchant's api key, issued by Noda |
| amount *required | number | 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. |
| string | End-customer e-mail. That parameter can be used to find a best button appearance for the particular customer. | |
| iin | integer | 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 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 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):
{
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.