@motopays/pay-form NPM

@motopays/pay-form

Installation

npm i @motopays/pay-form
#or
yarn add @motopays/pay-form

Usage

<body>
  <moto-web-pay id="payment"></moto-web-pay>
</body>

import "@motopays/pay-form/lib/index.js";
import "@motopays/pay-form/lib/styles/styles.css";

const payment$ = document.querySelector("#payment");

//This listener has to be assigned before payment and settings fields set
payment$.addEventListener("analyticsTracked", (event) => {
  console.log("analytics data was detected: ", e); // Custom event
  if(event.detail.type == 'user-preference-checkbox-1-check') {
    console.log(event.detail.payload);
  }
});

payment$.payment = {
  userAuthToken?: string;
  userId: string;
  
  paymentId: string;
  amount: number;
  amountType?: AmountType; //one of strings: GrossWithoutGst, Net, Gross
  tax?: number;
  orderType?: OrderType; //one of numbers: Regular, FreeTrial
  currency: string;
  merchantId: string;
  initiator?: PaymentInitiatorType; //one of strings: Customer, Merchant

  webhookUrl?: string;
  returnUrl?: string;

  description: string;
  email?: string;
  details?: ISimple<any>; //any object
  phoneNumber?: string;
  ipAddress?: string;
  signature?: string;

  billingAddress?: {
    addressLine: string;
    city: string;
    state: string;
    country: string;
    zip: string;
  }
}

payment$.settings = {
  isPhoneNumberFieldVisible: boolean;
  isCloseButtonVisible: boolean;
  isSignatureRequired: boolean;
  isProblemTipsListVisible: boolean;

  urls: {
    //For example, "https://billingprofiles.dating.com
    billingProfiles: string;
    processing: string;
  };

  //Now it supports these strings: "american-express" | "discover" | "jcb" | "maestro" | "mastercard" | "unionpay" | "visa"
  availableCardBrands: string[] or CreditCardTypeCardBrandId[];

  chargeTerms: {
    visible: boolean;
    text?: string;
    checkboxes?: { 
      text: string; 
      link: { 
        text: string; 
        href: string; 
      }
    } [];
  };

  merchantInfo: {
    visible: boolean;
    text?: string;
    links?: { 
      text: string; 
      href: string; 
    } [];
  };
}

payment$.addEventListener("close", (event) => {
  console.log("clicked to close icon: ", e); // Custom event
});

payment$.addEventListener("paid", (event) => {
  console.log("event after pay: ", event.detail); // Payment result event
});

Usage with TypeScript

declare module "@motopays/pay-form/pay";

Payment interface

Field	Type	Description
userAuthToken	string	End-user authorization token to access Motopays services. This field is necessary for ApplePay availability
userId *required	string	External end-user Id generated on the merchant side (not Motopays)
paymentId *required	string	Id of a payment
amount *required	number	Payment amount
amountType	AmountType or string	Type of amount can be only one of the following values: {GrossWithoutGst, Net, Gross}
tax	number	Payment tax
orderType	OrderType or string	Type of order can be only one of the following values: {Regular, FreeTrial}
currency *required	string	Payment currency in ISO_4217 format. For example: gbp, eur, usd
merchantId *required	string	Merchant's identificator, issued by Motopays.
initiator	PaymentInitiatorType or string	Identifies who of 2 types initiated the payment. Currently accepted: {Merchant, Customer}
webhookUrl	string	URL where the Motopays will send hooks about the payment status changes
returnUrl	string	The URL to which the user will be redirected after completing some types of payment, such as PayPal
description	string	Short order description for the customer
email	string	End-customer e-mail. That parameter can be used to find a best button appearance for the particular customer.
details	ISimple	Additional information about payment
phoneNumber	string	End-customer phone number (can be changed if a customer fill the number by themself)
ipAddress	string	End-customer ip address
billingAddress	BillingAddress	The address linked to a customer bank account
billingAddress.addressLine	string	Street, building appartment and etc in one line
billingAddress.city	string	City of a customer bank account
billingAddress.state	string	State of a customer bank account
billingAddress.country	string	Country of a customer bank account (ISO 3166-1 alpha-2 country code). Example: US
billingAddress.zip	string	Zip of a customer bank account
signature	string	The signature of the payment. For details contact technical support

Settings interface

Field	Type	Description
urls *required	IServicesUrls	The necessary services urls
urls.processing *required	string	The processing service URL
urls.billingprofiles *required	string	The billing profiles service URL
isPhoneNumberFieldVisible	boolean	Whether to show the phone input field when creating a map
isSignatureRequired	boolean	Whether to show an error and deny access to the payment form if the signature field in the payment model is not set
isCloseButtonVisible	boolean	Whether to show a window close button in the top right corner of the screen
isProblemTipsListVisible	boolean	Whether to show tips on the payment result page when the payment is rejected, if tips exist for the error status code that occurred
merchantInfo	IMerchantInfoSettings	The information displays in merchant info section
merchantInfo.visible	boolean	Whether to show the merchant information
merchantInfo.text	string	The information about a merchant
merchantInfo.links	ILink[]	The array of merchant links. For example, Policy and Terms
chargeTerms	IChargeTermsSettings	The charge terms section
chargeTerms.visible	boolean	Whether to show the charge terms
chargeTerms.checkboxes	ITermCheckbox[]	The checkboxes that, without being selected, the user will not be able to make a payment. All these checkboxes have to be selected by user to be able to make a payment
chargeTerms.text	string	The text of charge terms. For example, description of terms and policy
chargeTerms.location	string or ChargeTermsLocation	The location of ChargeTerms element. Currently accepted: { BeforePay, AfterPay }
availableCardBrands	string[] or CreditCardTypeCardBrandId[]	The сard brands for which icons will be displayed on the form as card payment methods. Currently accepted: {american-express, discover, jcb, maestro, mastercard, unionpay, visa}
requiredFieldsBehavior	IRequiredFieldsBehavior	Configuration of the display of required fields for the user to manage the user's focus on them
requiredFieldsBehavior.showStars	boolean	Show the stars on labels of required fields
requiredFieldsBehavior.buttonStateUntilCorrect	string	If 'disabled', the payment buttons remain disabled until the user fills in all the required fields. If 'enabled', then when one of the buttons is pressed (the buttons are enabled), the required fields will be marked as invalid (red color) for the user. If 'hidden-enabled', then when one of the buttons is pressed (the buttons are enabled but have styles as disabled), the required fields will be marked as invalid (red color) for the user. Current accepted: { enabled, disabled, hidden-enabled }
requiredFieldsBehavior.markAsInvalidUntilCorrect	boolean	If true, then all unfilled or incorrectly filled required fields will initially appear as invalid (red color) to the user until they are filled and correct. If the value is false, the required fields will only be shown as invalid in the event that the user presses the payment button when the buttons are enabled
userPreferences	IUserPreferencesSettings	The user preferences section
userPreferences.visible	boolean	Whether to show the user preferences
userPreferences.text	string	The text of user preferences. For example, description of autorefill plan
userPreferences.checkboxes	IUserPreferenceCheckbox[]	The text of user preferences. For example, description of autorefill plan

ILink interface:

interface ILink {
    text: string;
    href: string;
}

ITermCheckbox interface:

interface ITermCheckbox {
    text: string;
    link?: ILink;
}

IUserPreferenceCheckbox interface:

interface IUserPreferenceCheckbox {
    name: string;
    text: string;
    link?: ILink;
    defaultValue?: boolean;
}

Example of merchantInfo:

merchantInfo: {
  "visible": true,
  "text": "The vendor prides itself on designing and implementing state-of-the-art payment infrastructures that cater to a wide range of commercial activities. Specializing in the creation of robust payment processing platforms, the merchant provides tailored solutions that support the dynamic needs of the global market",
  "links": [
    {
      "text": "Terms",
      "href": "https://www.google.com/"
    },
    {
      "text": "Policy",
      "href": "https://www.google.com/"
    }
  ]
}

Example of chargeTerms:

chargeTerms: {
  "visible": true,
  "text": "By checking this box, I am affirming my full and complete understanding of, as well as my agreement to, all the terms and conditions that were previously presented to me, acknowledging that they form a binding contractual agreement.",
  "checkboxes": [
    {
      "text": "I hereby agree to the conditions previously outlined.",
      "link": {
        "text": "Link to the application",
        "href": "https://www.google.com/"
      }
    },
    {
      "text": "I validate the foregoing stipulations.",
      "link": {
        "text": "Google",
        "href": "https://www.google.com/"
      }
    }
  ]
},

Example of userPreferences:

"userPreferences": {
  "visible": true,
  "text": "By checking this box, I am affirming my full and complete understanding of, as well as my agreement to, all the terms and conditions that were previously presented to me, acknowledging that they form a binding contractual agreement.",
  "checkboxes": [
    {
      "name": "autoFill",
      "text": "Do you want to auto refill? Check this.",
      "link": {
        "text": "Refill policy",
        "href": "https://www.google.com/"
      }
    },
    {
      "name": "isGood",
      "defaultValue": true,
      "text": "Do you want to mark this as good? Check this.",
      "link": {
        "text": "Link to the application",
        "href": "https://www.google.com/"
      }
    }
  ]
}

Output events

Event	Type	Description
close	void	triggered by clicking on the closing icon
paid	Payment Result	triggered after receiving a payment response
analyticsTracked	IAnalyticsData	triggered by analytics events

Payment Result Structure

IPaymentResponse {
    action?: {
        name: string;
        data: IThreeDsData | IRedirectData | any;
    }
    ip: string;
    merchant: string;
    order: {
        invoiceId: string;
        details: string;
    }
    payment: {
        paymentId: string;
        state: PaymentState; //on of strings: completed, rejected, needAction
        rebillAnchor: string;
        info: {
            completeProcessingTime?: Date;
            currency: string;
            paymentType: string;
            paymentSystem: string;
            paymentRequisites?: string;
            price: number
        }
        rejectionDetails?: {
            hardDecline: boolean;
            message?: string;
            problemSolvingTips: string[];
            rejectionCode: number;
        }
    }
    taxInfo: {
        abbreviation: string;
        price: number;
        priceNet: number;
        tax: number;
    }
    user: {
        id: string;
    }
    signature: string;
}

IThreeDsData {
  paReq: string;
  acsurl: string;
  termUrl: string;
  md: string;
}

IRedirectData {
    location: string;
}

Analytics

For receiving analytics listen analyticsTracked events.

'init-start' - the form has started initializtion. Payload: void. 'loading-finish' - the form has finished initialization and loading. Payload: void. 'card-number-field-click' - the card number field has been clicked. Payload: void. 'expiration-date-field-click' - the expiration date field has been clicked. Payload: void. 'cvv-field-click' - the cvv field has been clicked. Payload: void. 'card-holder-field-click' - the card holder field has been clicked. Payload: void. 'charge-term-checkbox--check' - the charge term checkbox has been checked. Payload: IChargeTermsAnalytics. 'charge-term-checkbox--uncheck' - the charge term checkbox has been unchecked. Payload: IChargeTermsAnalytics. 'user-preference-checkbox--check' - the user preference checbox has been checked. Payload: IUserPreferencesAnalytics. 'user-preference-checkbox--uncheck' - the user preference checbox has been unchecked. Payload: IUserPreferencesAnalytics. 'pay-button-click' - the 'Pay' button has been clicked (payment by card). Payload: void. '-button-click' - the apm payment button has been clicked. Payload: void. 'add-card-button-click' - the "Add New Card" button has been clicked. Payload: void. 'card-options-button-click' - the card options button has been clicked (existing card menu visualised as 3 vertical dots). Payload: ICardAnalytics. 'remove-card-button-click' - the card removing button has been clicked. Payload: ICardAnalytics. 'select-card-button-click' - the card selecting button has been clicked. Payload: ICardAnalytics.

Examples of dynamic event types (number inserting): 1. Example of the first checkbox: 'charge-term-checkbox-0-check' 2. Example of the second checkbox: 'charge-term-checkbox-1-check'

Examples of dynamic event types (apm inserting): 1. 'coinbase-button-click' 2. 'moto-button-click'

//structure
interface IAnalyticsData {
    type: TAnalyticsData,
    payload?: any
}

//event types
type TAnalyticsData = 
  | 'init-start'
  | 'loading-finish'
  | 'card-number-field-click'
  | 'expiration-date-field-click'
  | 'cvv-field-click'
  | 'card-holder-field-click'
  | `charge-term-checkbox${`-${number}`}-check`
  | `charge-term-checkbox${`-${number}`}-uncheck`
  | `user-preference-checkbox${`-${number}`}-check`
  | `user-preference-checkbox${`-${number}`}-uncheck`
  | 'pay-button-click'
  | `${string}-button-click`
  | 'add-card-button-click'
  | 'card-options-button-click'
  | 'remove-card-button-click'
  | 'select-card-button-click'


//payload types
interface ICardAnalytics {
    last4Digits: string;
}

interface IChargeTermsAnalytics {
    text: string;
}

interface IUserPreferencesAnalytics {
    name: string;
    text: string;
}

Webpack 5 Issues

During the integration process, you might face multiple issues with webpack 5. This issue is caused due to the fact that some packages have certain dependencies, which are not present within the browser environment by webpack 5. Hence, you require certain node polyfills to be added to your project, while overriding the configurations to enable their usage. When that is done, your project should run without any issues.

moto cards payments js web

@everything-registry/sub-chunk-620

9 months ago

9 months ago

9 months ago

10 months ago

9 months ago