# CollectJS

Wallet payments uses Poynt Collect plugin (CollectJS script) to embed an iframe that securely process payment from your website. Learn how to customize your wallet checkout experience using the CollectJS APIs.

Collect script are publicly accessible,

For UI styling reference for iframe, form, and button, refer to this page.

# CollectJS API

# SupportWalletPayments() required

Checks buyer's device or browser compatibility to support ApplePay and GooglePay

Returns SupportWalletPaymentsResponse object

collect.supportWalletPayments()
  .then((result) => {
    const paymentMethods = [];
 
    if (result.googlePay) {
      paymentMethods.push("google_pay");
    }
 
    if (result.applePay) {
      paymentMethods.push("apple_pay");
    }
 
    if (paymentMethods.length) {
      collect.mount("collect-container", document, {
        paymentMethods: paymentMethods,
      });
    }
  })
  .catch((error) => {
    console.error(error);
  });

# Mount(domElement, document, mountOptions) required

Creates iframe under domElement containing wallet button.

Options

• buttonOptions: style the wallet button or/and to add custom onClick event handler (options will apply to both the ApplePay™ button and the GooglePay™ button)
• applePayButtonOptions: style the ApplePay™ button or/and to add custom onClick event handler (has a higher priority, styles from the buttonOptions parameter will be overwritten). See all available options in ApplePay brand guideline
• googlePayButtonOptions: style the GooglePay™ button or/and to add custom onClick event handler (has a higher priority, styles from the buttonOptions parameter will be overwritten). See all available options in GooglePay™ brand guideline (opens new window)

Sample buttonOptions styling:

collect.supportWalletPayments().then((ok) => {
  if (ok.googlePay) {
    collect.mount("collect-container", document, {
      paymentMethods: ["google_pay"],   // "google_pay", "apple_pay"
      buttonOptions: {
        color: "black",
        type: "buy",
        locale: "US",
      },
      applePayButtonOptions: {
        color: "white",
      },
      googlePayButtonOptions: {
        type: "pay",
      },
    });
  }
});

# StartApplePaySession() and StartGooglePaySession() optional

Method parameter: WalletRequestUpdate (optional)

This method is used to open wallet payment sheet. Examples:

collect.supportWalletPayments().then((result) => {
  if (result.applePay) {
    collect.mount("collect-container", document, {
      paymentMethods: ["apple_pay"], // and or google_pay
      buttonOptions: {
        onClick: (event) => {
          ...
          const update = {
            total: ...,
            lineItems: [...],
            shippingMethods: [...],
            couponCode: ...,
          };
           
          if (event.source === "apple_pay") { // or google_pay
            collect.startApplePaySession(update); // or collect.startGooglePaySession(update)
          }
        },
      },
    });
  }
});
collect.supportWalletPayments().then((result) => {
  if (result.applePay) {
    collect.mount("collect-container", document, {
      paymentMethods: ["apple_pay"],
      applePayButtonOptions: {
        onClick: (event) => {
          ...
          const update = {
            total: ...,
            lineItems: [...],
            shippingMethods: [...],
            couponCode: ...,
          };
           
          collect.startApplePaySession(update);
        },
      },
    });
  }
});

# AbortApplePaySession() optional

This method is used to force close an Apple Pay payment sheet. Will have no effect if the Apple Pay payment sheet is not active at the time this method is called.

# Wallet Event Methods

# Complete(walletRequestUpdate) required

Method parameter: WalletRequestUpdate

This method is used to perform billing/shipping address validation before completing payment authorization and closing wallet payment sheet session. You can only pass WalletError object as part of the arguments/options.

collect.on("payment_authorized", (e) => {
    let update = {
        "error": {
            "code": "invalid_payment_data",
            "message": "Payment data is not valid"
        }
    };
    e.complete(update); // e.complete() for no error
}

# UpdateWith(walletRequestUpdate) optional

Method parameter: WalletRequestUpdate

Updates wallet request total, displayed items, shipping methods, coupon code and possibly error when wallet payment sheet is modified. This method should be used inside the following event handlers:

• Shipping Address Change
• Shipping Method Change
• Coupon Code Change

IMPORTANT WalletRequest.total is NOT calculated on-the-fly and it will be overwritten. You will need to handle the cost adjustment due to event triggers.

collect.on("shipping_address_change", (e) => {
  const options = {
    lineItems: [
      {
        label: "Express Shipping",
        amount: "7.00",          // wallet does NOT calculate total cost on-the-fly
      },
    ],
    total: {
      label: "Total",
      amount: OlsServer.calcShipping(e.shippingAddress, walletRequest.total.amount),
    },
  };
 
  e.updateWith(options);
});

In case you just wanted to display error without modifying existing line items, shipping methods, or total, simply just pass in WalletError as an option to updateWith method. Refer to Payment Sheet Errors and Input Validation for more detailed usage.

collect.on("shipping_address_change", (e) => {
  ...
  const options = {
    error: {
      code: "invalid_shipping_address",
      contactField: "locality",
      message: "We don't support shipping to SINALOA, choose different address",
    }
  };
 
  e.updateWith(options);
});

# Schemas

# WalletRequest

WalletRequest is an object which contains fields of supported payment options

interface WalletRequest {
  total: LineItem;
  country: string;          //merchant's two-letter ISO 3166 country code
  currency: string;         //three-letter ISO 4217 currency code for the payment
  merchantName: string;
  shippingType?: string;    //default "shipping"
  shippingMethods?: ShippingMethod[]; //IMPORTANT! requireShippingAddress must be "true" to initialize shipping methods
  lineItems?: LineItem[];
  requireEmail?: boolean;
  requirePhone?: boolean;
  requireShippingAddress?: boolean;
  supportCouponCode?: boolean;
  couponCode?: CouponCode; //IMPORTANT! requireCouponCode must be "true" to initialize coupon code
  error?: WalletError;
  disableWallets?: {
    applePay?: boolean;
    googlePay?: boolean;
  }
}

# MountOptions

interface MountOptions {
  ...
  paymentMethods?: PaymentMethod[]; // "apple_pay" | "google_pay" | "card"
  buttonsContainerOptions?: ButtonsContainerOptions;
  buttonOptions?: ButtonOptions;
  applePayButtonOptions?: ButtonOptions;
  googlePayButtonOptions?: ButtonOptions;
}

# ButtonsContainerOptions

interface ButtonsContainerOptions {
  justifyContent?: string;
  alignItems?: string;
  flexDirection?: string;
  style?: Record<string, string>; // object with valid CSS styles
  className?: string;
}

# ButtonOptions

interface ButtonOptions {
  color?: ButtonColor;  // "black" | "white"
  type?: ButtonType;    // "book" | "buy" | "checkout" | "donate" | "order" | "plain" | "subscribe";
  locale?: string;
  width?: string;
  height?: string;
  margin?: string;
  onClick?: (event: ButtonClickEvent) => void;
}

# ButtonClickEvent

interface ButtonClickEvent {
  source: string; // "apple_pay" | "google_pay"
}

# WalletRequestUpdate

Wallet request update fields, if present, will overwrite (patch) whatever value stored in WalletRequest as is.

interface WalletRequestUpdate {
  total?: LineItem;             //overwrite total as is
  shippingMethods?: ShippingMethod[]; //IMPORTANT! shipping methods will not be updated if an empty array is passed
  lineItems?: LineItem[];
  couponCode?: CouponCode;
  error?: WalletError;
}

# LineItem

• isPending in total indicates whether the total price displayed on the payment sheet will be changed after the payment is authorized (for example, depending on the billing address). If omitted, defaults as "false".
• isPending in lineItems indicates whether the line item price is pending or final. If set to "true" line item will not be displayed on the payment sheet. If omitted, defaults as "false".

interface LineItem {
  label: string;
  amount: string;
  isPending?: boolean;
}

# ShippingMethod

interface ShippingMethod {
  id: string;
  label: string;
  detail: string;
  amount: string;
}

# CouponCode

interface CouponCode {
  code: string;
  label: string;
}

# WalletError

interface WalletError {
  code?: WalletErrorCode;
  message?: string;
  contactField?: WalletErrorContactField;
}

# WalletErrorCode

type WalletErrorCode = "invalid_shipping_address" | "invalid_billing_address" | "invalid_coupon_code" | "expired_coupon_code" | "unserviceable_address" | "unknown";

# WalletErrorContactField

type WalletErrorContactField = "administrativeArea" | "countryCode" | "postalCode" | "locality";

# SupportWalletPaymentsResponse

interface SupportWalletPaymentsResponse {    
  googlePay: boolean;
  applePay: boolean;
}

# Address

interface Address {
  emailAddress?: string;
  administrativeArea?: string;
  countryCode?: string;
  postalCode?: string;
  locality?: string;
  phoneNumber?: string;
  addressLines?: string[];
  name?: string;
}

# WalletButtonClickResponse

interface WalletButtonClickResponse {
  source: string;
}

# PaymentAuthorizedResponse

nonce is a one-time use payment token. Charge this token from your backend to process payment.

interface PaymentAuthorizedResponse {
  nonce: string;         // payment token
  source: PaymentMethod; // "apple_pay" or "google_pay"
  shippingAddress?: Address;
  billingAddress?: Address;
  complete: Function;   // only for handling invalid billing address
}

# ShippingAddressChangeResponse

interface ShippingAddressChangeResponse {
  shippingAddress: {
    administrativeArea: string;
    countryCode: string;
    postalCode: string;
    locality: string;
  };
  updateWith: Function;
}

# ShippingMethodChangeResponse

interface ShippingMethodChangeResponse {
  shippingMethod: {
    id: string;
  };
  updateWith: Function;
}

# CouponCodeChangeResponse

interface CouponCodeChangeResponse {
  couponCode: string;
  updateWith: Function;
}