npm - @paydock/client-sdk - Versions diffs - 0.0.3 → 0.1.2-beta - Mend

@paydock/client-sdk 0.0.3 → 0.1.2-beta

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (531) hide show

package/docs/wallet-cba-buttons-examples.md ADDED Viewed

@@ -0,0 +1,388 @@
+## Wallet Buttons
+You can find description of all methods and parameters [here](https://www.npmjs.com/package/@paydock/client-sdk#wallet-buttons-simple-example)
+Wallet Buttons allow you to easily integrate different E-Wallets into your checkout.
+Currently supports ApplePay, Google Pay and Paypal Smart Buttons Checkout.
+If available in your client environment, you will display a simple button that upon clicking it the user will follow the standard flow for the appropriate Wallet. If not available an event will be raised and no button will be displayed.
+## Wallet Buttons simple example
+### Container
+```html
+<div id="widget"></div>
+```
+You must create a container for the Wallet Buttons. Inside this tag, the button will be initialized.
+Before initializing the button, you must perform a POST request to `charges/wallet` from a secure environment like your server. This call will return a token that is required to load the button and securely complete the payment. You can find the documentation to this call in the PayDock API documentation.
+### Initialization
+The following is the minimum required initialization parameters for Apple Pay:
+```javascript
+let button = new paydock.WalletButtons(
+    "#widget",
+    token,
+    {
+        amount_label: "Total",
+        country: "DE",
+    }
+);
+button.load();
+```
+```javascript
+// ES2015 | TypeScript
+import { WalletButtons } from '@paydock/client-sdk';
+var button = new WalletButtons(
+    '#widget',
+    token,
+    {
+        amount_label: 'Total',
+        country: 'DE',
+    }
+);
+button.load();
+```
+Paypal wallet do not require any meta sent to the wallet, so the following is enough for initialization:
+```javascript
+let button = new paydock.WalletButtons(
+    "#widget",
+    token,
+    {}
+);
+button.load();
+```
+```javascript
+// ES2015 | TypeScript
+import { WalletButtons } from '@paydock/client-sdk';
+var button = new WalletButtons(
+    '#widget',
+    token,
+    {}
+);
+button.load();
+```
+### Setting environment
+Current method can change environment. By default environment = sandbox.
+Bear in mind that you must set an environment before calling `button.load()`.
+```javascript
+button.setEnv('sandbox');
+```
+### Full example
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Title</title>
+</head>
+<body>
+    <h2>Payment using PayDock Wallet Button!</h2>
+    <div id="widget"></div>
+</body>
+<script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
+<script>
+        let button = new paydock.WalletButtons(
+            "#widget",
+            token,
+            {
+                amount_label: "Total",
+                country: "DE",
+            }
+        );
+        button.load();
+</script>
+</html>
+```
+## Wallet Buttons advanced example
+### Checking for button availability
+If the customer's browser is not supported, or the customer does not have any card added to their Google Pay or Apple Pay wallets, the button will not load. In this case the callback onUnavailable() will be called. You can define the behavior of this function before loading the button.
+```javascript
+button.onUnavailable(() => console.log("No wallet buttons available"));
+```
+### Forcibly closing the checkout
+### Performing actions when shipping info is updated
+In Paypal and ApplePay via MPGS integrations after each shipping info update the `onUpdate(data)` will be called with the selected shipping address information (plus selected shipping method for Paypal). Merchants should handle this callback, recalculate shipping costs in their server by analyzing the new data, and submit a backend to backend request to `POST charges/:id` with the new total amount and shipping amount (you can find the documentation of this call in the PayDock API documentation).
+For Paypal integration specifically, if shipping is enabled for the wallet button and different shipping methods were provided in the create wallet charge call, Merchants must ensure that the posted `shipping.amount` to `POST charges/:id` matches the selected shipping option amount (value sent in when initializing the wallet charge). In other words, when providing shipping methods the shipping amount is bound to being one of the provided shipping method amount necessarily. Bear in mind that the total charge amount must include the `shipping.amount`, since it represents the full amount to be charged to the customer.
+After analyzing the new shipping information, and making the post with the updated charge and shipping amounts if necessary, the `button.update({ success: true/false })` wallet button method needs to be called to resume the interactions with the customer. Not calling this will result in unexpected behavior.
+```javascript
+button.onUpdate((data) => {
+    console.log("Updating amount via a backend to backend call to POST charges/:id");
+	// call `POST charges/:id` to modify charge
+	button.update({ success: true });
+});
+```
+For ApplePay via MPGS integration specifically, you must return the new `amount` and new `shipping_options` If new options are needed based on the updated shipping data. Before the user authorizes the transaction with Touch ID, Face ID, or passcode, you receive redacted address information (address_country, address_city, address_state, address_postcode), this data can be used to recalculate the amount and new shipping options. (https://developer.apple.com/documentation/apple_pay_on_the_web/applepaypayment/1916097-shippingcontact)
+```javascript
+button.onUpdate((data) => {
+    console.log("Updating amount via a backend to backend call to POST charges/:id");
+	// call `POST charges/:id` to modify charge
+	button.update({
+        success: true,
+        body: {
+            amount: 15,
+            shipping_options: [
+                {
+                    id: "NEW-FreeShip",
+                    label: "NEW - Free Shipping",
+                    detail: "Arrives in 3 to 5 days",
+                    amount: "0.00"
+                },
+                {
+                    id: "NEW - FastShip",
+                    label: "NEW - Fast Shipping",
+                    detail: "Arrives in less than 1 day",
+                    amount: "10.00"
+                }
+            ]
+        }
+    });
+});
+```
+### Performing actions after the payment is completed
+After the payment is completed, the onPaymentSuccessful(data) will be called if the payment was successful. If the payment was not successful, the function onPaymentError(data) will be called. If fraud check is active for the gateway, a fraud body was sent in the wallet charge initialize call and the fraud service left the charge in review, then the onPaymentInReview(data) will be called.
+All three callbacks return relevant data according to each one of the scenarios.
+```javascript
+button.onPaymentSuccessful((data) => console.log("The payment was successful"));
+```
+```javascript
+button.onPaymentInReview((data) => console.log("The payment is on fraud review"));
+```
+```javascript
+button.onPaymentError((data) => console.log("The payment was not successful"));
+```
+### Events
+The above events can be used in a more generic way via de `on` function, and making use
+of the corresponding event names.
+```javascript
+button.on(EVENT.UNAVAILABLE, () => console.log("No wallet buttons available"));
+button.on(EVENT.UPDATE, (data) => console.log("Updating amount via a backend to backend call to POST charges/:id");
+button.on(EVENT.PAYMENT_SUCCESSFUL, (data) => console.log("The payment was successful"));
+button.on(EVENT.PAYMENT_ERROR, (data) => console.log("The payment was not successful"));
+```
+This example shows how to use these functions for **Apple**:
+_(Required `meta` fields: `amount_label`, `country`. Optional `meta` fields: `wallets`)_
+### Full example
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Title</title>
+</head>
+<body>
+    <h2>Payment using PayDock Wallet Button!</h2>
+    <div id="widget"></div>
+</body>
+<script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
+<script>
+    let button = new paydock.WalletButtons(
+        "#widget",
+        charge_token,
+        {
+            amount_label: "Total",
+            country: "DE",
+            wallets: ["google", "apple"],
+        }
+    );
+    button.setEnv('sandbox');
+    button.onUnavailable(() => console.log("No wallet buttons available"));
+    button.onPaymentSuccessful((data) => console.log("The payment was successful"));
+    button.onPaymentError((data) => console.log("The payment was not successful"));
+    button.onPaymentInReview((data) => console.log("The payment is on fraud review"));
+    button.load();
+</script>
+</html>
+```
+This example shows how to use these functions for **Paypal Smart Checkout Buttons**:
+_(Required `meta` fields: - . Optional `meta` fields: `request_shipping`, `pay_later`, `standalone`, `style`)_
+### Full example
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Title</title>
+</head>
+<body>
+    <h2>Payment using PayDock Wallet Button!</h2>
+    <div id="widget"></div>
+</body>
+<script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
+<script>
+    let button = new paydock.WalletButtons(
+		"#widget",
+		charge_token,
+		{
+			request_shipping: true,
+			pay_later: true,
+			style: {
+				layout: 'horizontal',
+				color: 'blue',
+				shape: 'rect',
+				label: 'paypal',
+			},
+		}
+	);
+    button.setEnv('sandbox');
+    button.onUnavailable(() => console.log("No wallet buttons available"));
+    button.onUpdate((data) => {
+		console.log("Updating amount via a backend to backend call to POST charges/:id");
+		// call `POST charges/:id` to modify charge
+		button.update({ success: true });
+	});
+    button.onPaymentSuccessful((data) => console.log("The payment was successful"));
+    button.onPaymentError((data) => console.log("The payment was not successful"));
+    button.onPaymentInReview((data) => console.log("The payment is on fraud review"));
+    button.load();
+</script>
+</html>
+```
+This example shows how to use these functions for **ApplePay via MPGS**:
+_(Required `meta` fields: `amount_label`, `country`. Optional `meta` fields: `raw_data_initialization`, `request_shipping`, `style.button_type`)_
+### Full example
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Title</title>
+</head>
+<body>
+    <h2>Payment using PayDock Wallet Button!</h2>
+    <div id="widget"></div>
+</body>
+<script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
+<script>
+    let button = new paydock.WalletButtons(
+        "#widget",
+        charge_token,
+        {
+            amount_label: "Total",
+            country: 'DE',
+            request_shipping: true,
+            style: {
+                button_type: 'buy',
+            },
+            shipping_options: [
+                {
+                    id: "FreeShip",
+                    label: "Free Shipping",
+                    detail: "Arrives in 5 to 7 days",
+                    amount: "0.00"
+                },
+                {
+                    id: "FastShip",
+                    label: "Fast Shipping",
+                    detail: "Arrives in 1 day",
+                    amount: "10.00"
+                }
+            ]
+        }
+    );
+    button.setEnv('sandbox');
+    button.onUnavailable(() => console.log("No wallet buttons available"));
+    button.onPaymentSuccessful((data) => console.log("The payment was successful"));
+    button.onPaymentError((data) => console.log("The payment was not successful"));
+    button.load();
+</script>
+</html>
+```
+Also, for **ApplePay via MPGS** you can initialize the `ApplePayPaymentRequest` with your own values instead of using the default ones. Below you can see an example on how to initialize the `ApplePayPaymentRequest` with the `raw_data_initialization` meta field:
+### Raw data initialization example
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Title</title>
+</head>
+<body>
+    <h2>Payment using PayDock Wallet Button!</h2>
+    <div id="widget"></div>
+</body>
+<script src="https://app-sandbox.paydock.com/v1/widget.umd.js" ></script>
+<script>
+    let button = new paydock.WalletButtons(
+        "#widget",
+        charge_token,
+        {
+            raw_data_initialization: {
+                countryCode: "AU",
+                currencyCode: "AUD",
+                merchantCapabilities: ["supports3DS","supportsCredit","supportsDebit"],
+                supportedNetworks: ["visa","masterCard","amex","discover"],
+                requiredBillingContactFields: ["name","postalAddress"],
+                requiredShippingContactFields:["postalAddress","name","phone","email" ],
+                total: {
+                    label: "Total",
+                    amount: "10",
+                    type: "final",
+                }
+            },
+            amount_label: "Total",
+            country: 'DE',
+            request_shipping: true,
+            style: {
+                button_type: 'buy',
+            },
+            shipping_options: [
+                {
+                    id: "FreeShip",
+                    label: "Free Shipping",
+                    detail: "Arrives in 5 to 7 days",
+                    amount: "0.00"
+                },
+                {
+                    id: "FastShip",
+                    label: "Fast Shipping",
+                    detail: "Arrives in 1 day",
+                    amount: "10.00"
+                }
+            ]
+        }
+    );
+    button.setEnv('sandbox');
+    button.onUnavailable(() => console.log("No wallet buttons available"));
+    button.onPaymentSuccessful((data) => console.log("The payment was successful"));
+    button.onPaymentError((data) => console.log("The payment was not successful"));
+    button.load();
+</script>
+</html>
+```

package/docs/widget-examples.md ADDED Viewed

@@ -0,0 +1,271 @@
+## Widget
+You can find description of all methods and parameters [here](https://www.npmjs.com/package/@paydock/client-sdk#widget-simple-example)
+A payment form where it is possible to enter card data/bank accounts and then receive a one-time
+token for charges, subscriptions etc. This form can be customized, you can customize the fields and set styles.
+It is possible in real-time to monitor the actions of user with widget and get information about payment-source using events.
+## Widget simple example
+### Container
+```html
+<div id="widget"></div>
+```
+You must create a container for the widget. Inside this tag, the widget will be initialized
+### Initialization
+```javascript
+var widget = new paydock.HtmlWidget('#widget', 'publicKey');
+widget.load();
+```
+```javascript
+// ES2015 | TypeScript
+import { HtmlWidget } from '@paydock/client-sdk';
+var widget = new HtmlWidget('#widget', 'publicKey');
+widget.load();
+```
+Then write only need 2 lines of code in js to initialize widget
+### Full example
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Title</title>
+    <style>iframe {border: 0;width: 100%;height: 300px;}</style>
+</head>
+<body>
+    <form id="paymentForm">
+        <div id="widget"></div>
+        <input name="payment_source_token" id="payment_source_token" type="hidden">
+    </form>
+    <script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
+    <script>
+        var widget = new paydock.HtmlWidget('#widget', 'publicKey');
+        widget.onFinishInsert('input[name="payment_source_token"]', 'payment_source');
+        widget.load();
+    </script>
+</body>
+</html>
+```
+## Widget advanced example
+### Customization
+```javascript
+widget.setStyles({
+  background_color: 'rgb(0, 0, 0)',
+  border_color: 'yellow',
+  text_color: '#FFFFAA',
+  button_color: 'rgba(255, 255, 255, 0.9)',
+  font_size: '20px'
+ });
+```
+This example shows how you can customize to your needs and design
+### Customization from html
+```html
+<div id="widget"
+  widget-style="text-color: #FFFFAA; border-color: #yellow"
+  title="Payment form"
+  finish-text="Payment resource was successfully accepted"></div>
+```
+This example shows how you can set style and texts from html
+### Settings
+```javascript
+widget.setRefId('id'); // your unique identifier to identify the data
+widget.setFormFields(['phone', 'email']); // add additional fields for form of widget
+widget.setSupportedCardIcons(['mastercard', 'visa']); // add icons of supported card types
+```
+This example shows how you can use a lot of other methods to settings your form
+### Error handling
+## Overview
+Error events are emitted when an error occurs during widget operations. These events provide detailed information about the error, including its category, cause, and contextual details.
+## Error Event Structure
+### Base Properties
+| Property | Type | Description |
+|----------|------|-------------|
+| `event` | `string` | Always set to `"error"` |
+| `purpose` | `string` | Indicates the purpose of the action that triggered the error event (e.g., `"payment_source"`) |
+| `message_source` | `string` | Source of the message (e.g., `"widget.paydock"`) |
+| `ref_id` | `string` | Reference ID for the operation |
+| `widget_id` | `string` | Unique identifier of the widget instance |
+| `error` | `object` | Error object containing error information |
+### Error Object Properties
+The `error` object contains detailed information about the error:
+| Property | Type | Description |
+|----------|------|-------------|
+| `category` | `string` | High-level error classification |
+| `cause` | `string` | Specific error cause |
+| `retryable` | `boolean` | Indicates if the operation can be retried |
+| `details` | `object` | Additional error context |
+## Error Categories
+| Category | Description |
+|----------|-------------|
+| `configuration` | Configuration-related errors |
+| `identity_access_management` | Authentication and authorization errors |
+| `internal` | Internal system errors |
+| `process` | Process and operation errors |
+| `resource` | Resource-related errors |
+| `validation` | Input validation errors |
+## Error Causes
+| Cause | Category | Description |
+|-------|----------|-------------|
+| `aborted` | `process` | Operation was aborted |
+| `access_forbidden` | `identity` | Access to resource is forbidden |
+| `already_exists` | `validation` | Resource already exists |
+| `canceled` | `process` | Operation was canceled |
+| `invalid_configuration` | `configuration` | Invalid widget configuration |
+| `invalid_input` | `validation` | Invalid input provided |
+| `not_found` | `resource` | Requested resource not found |
+| `not_implemented` | `process` | Requested feature not implemented |
+| `rate_limited` | `process` | Too many requests |
+| `server_busy` | `process` | Server is too busy to handle request |
+| `service_unreachable` | `process` | Unable to reach required service |
+| `unauthorized` | `identity` | Authentication required |
+| `unknown_error` | `internal` | Unexpected error occurred |
+| `unprocessable_entity` | `validation` | Valid input but cannot be processed |
+## Error Details Object
+| Property | Type | Description |
+|----------|------|-------------|
+| `cause` | `string` | Matches the top-level error cause |
+| `contextId` | `string` | Context identifier (usually matches widget_id) |
+| `message` | `string` | Human-readable error message |
+| `timestamp` | `string` | ISO 8601 timestamp of when the error occurred |
+## Example
+```javascript
+widget.hideUiErrors(); // hide default UI errors and handle errors by listening to error events with widget.on('error')
+widget.on('error', (error) => {
+    console.log(error);
+    // {
+    //     "event": "error",
+    //     "purpose": "payment_source",
+    //     "message_source": "widget.paydock",
+    //     "ref_id": "",
+    //     "widget_id": "d4744f30-dcf5-168e-7f78-c8273a3401d4",
+    //     "error": {
+    //         "category": "process",
+    //         "cause": "service_unreachable",
+    //         "details": {
+    //             "cause": "service_unreachable",
+    //             "contextId": "d4744f30-dcf5-168e-7f78-c8273a3401d4",
+    //             "message": "The service is not availabe",
+    //             "timestamp": "2025-02-13T09:30:21.157Z"
+    //         },
+    //         "retryable": false
+    //     }
+    // }
+});
+```
+## Handling Errors (Tips)
+When handling errors, consider:
+1. Check the `retryable` flag to determine if the operation can be retried
+2. Use the `category` for high-level error handling logic
+3. Use the `cause` for specific error handling cases
+4. The `contextId` can be used for error tracking and debugging
+5. The `timestamp` helps with error logging and debugging
+### Full example
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8">
+ <title>Title</title>
+ <style>iframe {border: 0;width: 100%;height: 400px;}</style>
+</head>
+<body>
+<form id="paymentForm">
+    <div id="widget"
+        widget-style="text-color: #FFFFAA; border-color: #yellow"
+        title="Payment form"
+        finish-text="Payment resource was successfully accepted">
+    </div>
+    <div
+        id="error"
+        style="
+            display: none;
+            max-width: 600px;
+            margin: 16px auto;
+            padding: 16px 20px;
+            border-radius: 8px;
+            background-color: #FEF2F2;
+            border: 1px solid #FEE2E2;
+            box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+            font-family: system-ui, -apple-system, sans-serif;
+            color: #991B1B;
+            line-height: 1.5;
+            font-size: 14px;
+        "
+        title="error"
+        >
+        <div style="display: flex; align-items: flex-start; gap: 12px;">
+            <div>
+                <h4 style="margin: 0 0 4px 0; font-size: 14px; font-weight: 600;">Access Error</h4>
+                <div id="error-message"></div>
+            </div>
+        </div>
+    </div>
+</form>
+<script src="https://widget.paydock.com/sdk/latest/widget.umd.js" ></script>
+<script>
+ var widget = new paydock.HtmlWidget('#widget', 'publicKey', 'gatewayId');
+ widget.setSupportedCardIcons(['mastercard', 'visa']);
+ widget.setFormFields(['phone', 'email']);
+ widget.setRefId('custom-ref-id');
+    widget.onFinishInsert('input[name="payment_source_token"]', 'payment_source');
+    widget.on('error', ({ error }) => {
+        document.getElementById('error-message').textContent = error.details.message;
+        document.getElementById('error').style.display = 'block';
+    });
+ widget.load();
+</script>
+</body>
+</html>
+```