@paydock/client-sdk 1.103.1 → 1.104.1-beta

package/docs/wallet-buttons.md

@@ -0,0 +1,424 @@
+## Classes
+
+<dl>
+<dt><a href="#WalletButtons">WalletButtons</a></dt>
+<dd><p>Class WalletButtons to work with different E-Wallets within html (currently supports Apple Pay, Google Pay, Google Pay™ and Apple Pay via Stripe, Flypay, Flypay V2, Paypal, Afterpay)</p>
+</dd>
+</dl>
+
+## Constants
+
+<dl>
+<dt><a href="#EVENT">EVENT</a> : <code>object</code></dt>
+<dd><p>List of available event&#39;s name in the wallet button lifecycle</p>
+</dd>
+</dl>
+
+## Interfaces
+
+<dl>
+<dt><a href="#IWalletMeta">IWalletMeta</a> : <code>object</code></dt>
+<dd><p>Interface of data used by the wallet checkout and payment proccess.</p>
+</dd>
+<dt><a href="#IApplePayShippingOption">IApplePayShippingOption</a> : <code>object</code></dt>
+<dd><p>Interface of Shipping Options for ApplePay</p>
+</dd>
+<dt><a href="#IGooglePayShippingOption">IGooglePayShippingOption</a> : <code>object</code></dt>
+<dd><p>Interface of Shipping Options for GooglePay</p>
+</dd>
+<dt><a href="#IPayPalShippingOption">IPayPalShippingOption</a> : <code>object</code></dt>
+<dd><p>Interface of Shipping Options for PayPal</p>
+</dd>
+</dl>
+
+<a name="IWalletMeta" id="IWalletMeta" href="#IWalletMeta">&nbsp;</a>
+
+## IWalletMeta : <code>object</code>
+Interface of data used by the wallet checkout and payment proccess.
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [amount_label] | <code>string</code> | Label shown next to the total amount to be paid. Required for [Stripe, ApplePay, GooglePay]. N/A for [FlyPay, Flypay V2, PayPal, Afterpay]. |
+| [country] | <code>string</code> | Country of the user. 2 letter ISO code format. Required for [Stripe, ApplePay, GooglePay, Afterpay]. N/A for [FlyPay, Flypay V2, PayPal]. |
+| [pay_later] | <code>boolean</code> | Used to enable Pay Later feature in PayPal Smart Checkout WalletButton integration when available. Optional for [PayPal]. N/A for other wallets. |
+| [standalone] | <code>boolean</code> | Used to enable Standalone Buttons feature in PayPal Smart Checkout WalletButton integration. Used together with `pay_later`. Optional for [PayPal]. N/A for other wallets. |
+| [show_billing_address] | <code>boolean</code> | Used to hide/show the billing address on ApplePay and GooglePay popups. Default value is false. Optional for [ApplePay, GooglePay]. N/A for other wallets. |
+| [request_payer_name] | <code>boolean</code> | Used mainly for fraud purposes - recommended set to true. Optional for [Stripe]. N/A for other wallets. |
+| [request_payer_email] | <code>boolean</code> | Used mainly for fraud purposes - recommended set to true. Optional for [Stripe]. N/A for other wallets. |
+| [request_payer_phone] | <code>boolean</code> | Used mainly for fraud purposes - recommended set to true. Optional for [Stripe]. N/A for other wallets. |
+| [access_token] | <code>string</code> | Used for Flypay V2 express flow. Optional for [Flypay V2]. N/A for other wallets. |
+| [refresh_token] | <code>string</code> | Used for Flypay V2 express flow. Optional for [Flypay V2]. N/A for other wallets. |
+| [request_shipping] | <code>boolean</code> | Used to request or not shipping address in the Wallet checkout, being able to handle amount changes via the `update` event. Optional for [FlyPay, PayPal, ApplePay, GooglePay]. N/A for [Flypay V2, Stripe, Afterpay]. |
+| [shipping_options] | [<code>Array.&lt;IApplePayShippingOption&gt;</code>](#IApplePayShippingOption) \| [<code>Array.&lt;IPayPalShippingOption&gt;</code>](#IPayPalShippingOption) | Used to provide available shipping options.(To use shipping_options the request_shipping flag should be true). Optional for [ApplePay]. N/A for the other wallets. |
+| [merchant_name] | <code>string</code> | Merchant Name used for GooglePay integration via MPGS. Required for [GooglePay]. N/A for other wallets. |
+| [raw_data_initialization] | <code>object</code> | Used to provide values to initialize wallet with raw data. Optional for [ApplePay]. N/A for the other wallets. |
+| [style] | <code>object</code> | For **Paypal**: used to style the buttons, check possible values in the [style guide](https://developer.paypal.com/docs/business/checkout/reference/style-guide). When `standalone` and `pay_later`, extra options can be provided in `style.messages` with the [messages style options](https://developer.paypal.com/docs/checkout/pay-later/us/integrate/reference/#stylelayout). Also used at **ApplePay**, **GooglePay** and **Afterpay** to select button type. Optional for [PayPal, ApplePay, GooglePay, Afterpay]. N/A for [Stripe, FlyPay, Flypay V2]. |
+| [style.button_type] | <code>object</code> | Used to select ApplePay button type (e.g: 'buy','donate', etc), check possible values at https://developer.apple.com/documentation/apple_pay_on_the_web/displaying_apple_pay_buttons_using_css. Also select button type for GooglePay (check GooglePayStyles) and Afterpay (check AfterpayStyles). Optional for [ApplePay, GooglePay, Afterpay]. N/A for other wallets. |
+| [style.height] | <code>object</code> | Used to select Afterpay button height. Optional for [Afterpay]. N/A for other wallets. |
+| [wallets] | <code>array</code> | By default if this is not sent or empty, we will try to show either Apple Pay or Google Pay buttons. This can be limited sending the following array in this field: ['apple','google]. Optional for [Stripe, ApplePay, GooglePay]. N/A for other wallets. |
+
+<a name="IApplePayShippingOption" id="IApplePayShippingOption" href="#IApplePayShippingOption">&nbsp;</a>
+
+## IApplePayShippingOption : <code>object</code>
+Interface of Shipping Options for ApplePay
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [id] | <code>string</code> | Identifier of the Shipping Option. Required. |
+| [label] | <code>string</code> | Identifier of the Shipping Option. Required. |
+| [amount] | <code>string</code> | Amount of the Shipping Option. Required. |
+| [detail] | <code>string</code> | Details of the Shipping Option. Required. |
+| [type] | <code>string</code> | Type of the Shipping Option. Values can be 'ELECTRONIC', 'GROUND', 'NOT_SHIPPED', 'OVERNIGHT', 'PICKUP', 'PRIORITY', 'SAME_DAY'. Optional. |
+
+<a name="IGooglePayShippingOption" id="IGooglePayShippingOption" href="#IGooglePayShippingOption">&nbsp;</a>
+
+## IGooglePayShippingOption : <code>object</code>
+Interface of Shipping Options for GooglePay
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [id] | <code>string</code> | Identifier of the Shipping Option. Required. |
+| [label] | <code>string</code> | Identifier of the Shipping Option. Required. |
+| [detail] | <code>string</code> | Details of the Shipping Option. Optional. |
+| [type] | <code>string</code> | Type of the Shipping Option. Values can be 'ELECTRONIC', 'GROUND', 'NOT_SHIPPED', 'OVERNIGHT', 'PICKUP', 'PRIORITY', 'SAME_DAY'. Optional. |
+
+<a name="IPayPalShippingOption" id="IPayPalShippingOption" href="#IPayPalShippingOption">&nbsp;</a>
+
+## IPayPalShippingOption : <code>object</code>
+Interface of Shipping Options for PayPal
+
+**Kind**: global interface  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [id] | <code>string</code> | Identifier of the Shipping Option. Required. |
+| [label] | <code>string</code> | Identifier of the Shipping Option. Required. |
+| [amount] | <code>string</code> | Amount of the Shipping Option. Required. |
+| [currency] | <code>string</code> | Currency of the Shipping Option. Required. |
+| [type] | <code>string</code> | Type of the Shipping Option. Values can be 'SHIPPING' or 'PICKUP'. Required. |
+
+<a name="WalletButtons" id="WalletButtons" href="#WalletButtons">&nbsp;</a>
+
+## WalletButtons
+Class WalletButtons to work with different E-Wallets within html (currently supports Apple Pay, Google Pay, Google Pay™ and Apple Pay via Stripe, Flypay, Flypay V2, Paypal, Afterpay)
+
+**Kind**: global class  
+
+* [WalletButtons](#WalletButtons)
+    * [new WalletButtons(selector, chargeToken, meta)](#new_WalletButtons_new)
+    * [.load()](#WalletButtons+load)
+    * [.update()](#WalletButtons+update)
+    * [.setEnv(env, [alias])](#WalletButtons+setEnv)
+    * [.close()](#WalletButtons+close)
+    * [.on(eventName, [cb])](#WalletButtons+on) ⇒ <code>Promise.&lt;IEventData&gt;</code> \| <code>void</code>
+    * [.onUnavailable([handler])](#WalletButtons+onUnavailable)
+    * [.onUpdate([handler])](#WalletButtons+onUpdate)
+    * [.onPaymentSuccessful([handler])](#WalletButtons+onPaymentSuccessful)
+    * [.onPaymentInReview([handler])](#WalletButtons+onPaymentInReview)
+    * [.onPaymentError([handler])](#WalletButtons+onPaymentError)
+    * [.onAuthTokensChanged([handler])](#WalletButtons+onAuthTokensChanged)
+
+<a name="new_WalletButtons_new" id="new_WalletButtons_new" href="#new_WalletButtons_new">&nbsp;</a>
+
+### new WalletButtons(selector, chargeToken, meta)
+
+| Param | Type | Description |
+| --- | --- | --- |
+| selector | <code>string</code> | Selector of html element. Container for the WalletButtons. |
+| chargeToken | <code>string</code> | token for the wallet transaction, created with a secure call to `POST charges/wallet`. |
+| meta | [<code>IWalletMeta</code>](#IWalletMeta) | data that configures the E-Wallet, which can be shown on checkout page and configures required customer information. |
+
+**Example**  
+```js
+var button = new WalletButtons('#wallet-buttons', 'charge-token', { amount_label: 'Total', country: 'us' });
+```
+<a name="WalletButtons+load" id="WalletButtons+load" href="#WalletButtons+load">&nbsp;</a>
+
+### walletButtons.load()
+Initializes the availability checks and inserts the button if possible.
+Otherwise function onUnavailable(handler: VoidFunction) will be called.
+
+**Kind**: instance method of [<code>WalletButtons</code>](#WalletButtons)  
+**Example**  
+```js
+var button = new WalletButtons(
+     '#buttons',
+     token,
+     {
+         amount_label: 'Total',
+         country: 'DE',
+     }
+ );
+ button.load();
+```
+<a name="WalletButtons+update" id="WalletButtons+update" href="#WalletButtons+update">&nbsp;</a>
+
+### walletButtons.update()
+Triggers the update process of the wallet, if available.
+Currently supported by Flypay, Paypal and ApplePay/GooglePay via MPGS Wallets.
+
+**Kind**: instance method of [<code>WalletButtons</code>](#WalletButtons)  
+**Example**  
+```js
+var button = new WalletButtons(
+     '#buttons',
+     token,
+     {
+         amount_label: 'Total',
+         country: 'DE',
+     }
+ );
+ button.on('update', (data) => {
+     updateChargeAmountInBackend(data);
+     button.update({ success: true });
+ });
+```
+**Example**  
+```js
+// ApplePay via MPGS example:
+var button = new WalletButtons(
+     '#buttons',
+     token,
+     {
+         amount_label: 'Total',
+         country: 'AU',
+         ...
+     }
+ );
+ button.on('update', (data) => {
+     updateChargeAmountInBackend(data);
+     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"
+                  }
+              ]
+         }
+      });
+ });
+```
+<a name="WalletButtons+setEnv" id="WalletButtons+setEnv" href="#WalletButtons+setEnv">&nbsp;</a>
+
+### walletButtons.setEnv(env, [alias])
+Current method can change environment. By default environment = sandbox.
+Also we can change domain alias for this environment. By default domain_alias = paydock.com
+Bear in mind that you must set an environment before calling `button.load()`.
+
+**Kind**: instance method of [<code>WalletButtons</code>](#WalletButtons)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| env | <code>string</code> | sandbox, production |
+| [alias] | <code>string</code> | Own domain alias |
+
+**Example**  
+```js
+button.setEnv('production', 'paydock.com');
+```
+<a name="WalletButtons+close" id="WalletButtons+close" href="#WalletButtons+close">&nbsp;</a>
+
+### walletButtons.close()
+Closes the checkout forcibly. Currently supported in Flypay wallet.
+
+**Kind**: instance method of [<code>WalletButtons</code>](#WalletButtons)  
+**Example**  
+```js
+button.close();
+```
+<a name="WalletButtons+on" id="WalletButtons+on" href="#WalletButtons+on">&nbsp;</a>
+
+### walletButtons.on(eventName, [cb]) ⇒ <code>Promise.&lt;IEventData&gt;</code> \| <code>void</code>
+Listen to events of button. `unavailable` returns no data, `paymentSuccessful` returns IWalletPaymentSuccessful
+for Stripe or full response for Flypay, and `paymentError` an error.
+
+NOTE: when listening for the 'update' event, make sure to call the `button.update(result)` method on completion.
+
+**Kind**: instance method of [<code>WalletButtons</code>](#WalletButtons)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| eventName | <code>string</code> | Available event names [EVENT](#EVENT) |
+| [cb] | <code>listener</code> |  |
+
+**Example**  
+```js
+button.on('paymentSuccessful', function (data) {
+     console.log(data);
+});
+// or
+button.on('unavailable').then(function () {
+     console.log('No button is available);
+});
+```
+<a name="WalletButtons+onUnavailable" id="WalletButtons+onUnavailable" href="#WalletButtons+onUnavailable">&nbsp;</a>
+
+### walletButtons.onUnavailable([handler])
+User to subscribe to the no button available event. This method is used after loading when the button is not available.
+For MPGS, since can have more than one wallet button configured (ApplePay/GooglePay) you will receive a body (({ wallet: WALLET_TYPE.GOOGLE }) or ({ wallet: WALLET_TYPE.APPLE })) indicating which button is unavailable
+Important: Do not perform thread blocking operations in callback such as window.alert() calls.
+
+**Kind**: instance method of [<code>WalletButtons</code>](#WalletButtons)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [handler] | <code>listener</code> | Function to be called when no button is available. |
+
+**Example**  
+```js
+button.onUnavailable(() => {
+     console.log('No wallet buttons available');
+});
+```
+**Example**  
+```js
+button.onUnavailable().then(() => console.log('No wallet buttons available'));
+```
+**Example**  
+```js
+button.onUnavailable(function (data) {console.log('data.wallet :: ', data.wallet)});
+```
+<a name="WalletButtons+onUpdate" id="WalletButtons+onUpdate" href="#WalletButtons+onUpdate">&nbsp;</a>
+
+### walletButtons.onUpdate([handler])
+If the wallet performs some update in the checkout process, the function passed as parameter will be called.
+
+NOTE: make sure to call the `button.update(result)` method on handler completion.
+
+**Kind**: instance method of [<code>WalletButtons</code>](#WalletButtons)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [handler] | <code>listener</code> | Function to be called when the payment was successful. |
+
+**Example**  
+```js
+button.onUpdate((data) => {
+     button.update({ success: true });
+});
+```
+**Example**  
+```js
+button.onUpdate().then((data) => throw new Error());
+```
+<a name="WalletButtons+onPaymentSuccessful" id="WalletButtons+onPaymentSuccessful" href="#WalletButtons+onPaymentSuccessful">&nbsp;</a>
+
+### walletButtons.onPaymentSuccessful([handler])
+If the payment was successful, the function passed as parameter will be called.
+Important: Do not perform thread blocking operations in callback such as window.alert() calls.
+
+**Kind**: instance method of [<code>WalletButtons</code>](#WalletButtons)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [handler] | <code>listener</code> | Function to be called when the payment was successful. |
+
+**Example**  
+```js
+button.onPaymentSuccessful((data) => {
+     console.log('Payment successful!');
+});
+```
+**Example**  
+```js
+button.onPaymentSuccessful().then((data) => console.log('Payment successful!'));
+```
+<a name="WalletButtons+onPaymentInReview" id="WalletButtons+onPaymentInReview" href="#WalletButtons+onPaymentInReview">&nbsp;</a>
+
+### walletButtons.onPaymentInReview([handler])
+If the payment was left in fraud review, the function passed as parameter will be called.
+Important: Do not perform thread blocking operations in callback such as window.alert() calls.
+
+**Kind**: instance method of [<code>WalletButtons</code>](#WalletButtons)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [handler] | <code>listener</code> | Function to be called when the payment was left in fraud review status. |
+
+**Example**  
+```js
+button.onPaymentInReview((data) => {
+     console.log('Payment in fraud review');
+});
+```
+**Example**  
+```js
+button.onPaymentInReview().then((data) => console.log('Payment in fraud review'));
+```
+<a name="WalletButtons+onPaymentError" id="WalletButtons+onPaymentError" href="#WalletButtons+onPaymentError">&nbsp;</a>
+
+### walletButtons.onPaymentError([handler])
+If the payment was not successful, the function passed as parameter will be called.
+Important: Do not perform thread blocking operations in callback such as window.alert() calls.
+
+**Kind**: instance method of [<code>WalletButtons</code>](#WalletButtons)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [handler] | <code>listener</code> | Function to be called when the payment was not successful. |
+
+**Example**  
+```js
+button.onPaymentError((err) => {
+     console.log('Payment not successful');
+});
+```
+**Example**  
+```js
+button.onPaymentError().then((err) => console.log('Payment not successful'));
+```
+<a name="WalletButtons+onAuthTokensChanged" id="WalletButtons+onAuthTokensChanged" href="#WalletButtons+onAuthTokensChanged">&nbsp;</a>
+
+### walletButtons.onAuthTokensChanged([handler])
+Registers a callback function to be invoked when authentication tokens are changed.
+This function allows you to respond to changes in authentication tokens, such as when a user logs in.
+
+**Kind**: instance method of [<code>WalletButtons</code>](#WalletButtons)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [handler] | <code>listener</code> | Function to be called when authentication tokens are changed. |
+
+**Example**  
+```js
+button.onAuthTokensChanged((eventData) => {
+    console.log('Authentication tokens changed:', eventData);
+});
+```
+**Example**  
+```js
+button.onAuthTokensChanged().then((eventData) => {
+    console.log('Authentication tokens changed:', eventData);
+});
+```
+<a name="EVENT" id="EVENT" href="#EVENT">&nbsp;</a>
+
+## EVENT : <code>object</code>
+List of available event's name in the wallet button lifecycle
+
+**Kind**: global constant  
+
+| Param | Type | Default |
+| --- | --- | --- |
+| UNAVAILABLE | <code>string</code> | <code>&quot;unavailable&quot;</code> | 
+| UPDATE | <code>string</code> | <code>&quot;update&quot;</code> | 
+| PAYMENT_SUCCESSFUL | <code>string</code> | <code>&quot;paymentSuccessful&quot;</code> | 
+| PAYMENT_ERROR | <code>string</code> | <code>&quot;paymentError&quot;</code> | 
+