@noda-ui/sdk
v2.0.18
Published
## Installation ``` npm i @noda-ui/sdk -S #or yarn add @noda-ui/sdk ```
Downloads
26
Readme
@noda-ui/sdk
Installation
npm i @noda-ui/sdk -S
#or
yarn add @noda-ui/sdkUsage
<body>
<div id="root"></div>
</body>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
declare module '@noda-ui/sdk'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. | | email | 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.