@primer-io/web v1.1.0

primer-sdk-web

Using the Primer SDK for the web, you can quickly and easily create a checkout page for your site to securely collect card information and offer a multitude of alternative payment methods to your customers.

Get Started!

check out our guides on how to get started here.

Reference

Global

class Primer(options: PrimerClientOptions)

Creates a primer client

type PrimerClientOptions

Options to configure the primer client

type PrimerClientOptions {
  credentials: {
    // Your server-generated client token
    clientToken: string;
  };

  // maximum time in milliseconds to wait for third party scripts to load [default=10000]
  thirdPartyScriptTimeout?: number;
}

Primer (checkout)

Primer#checkout(options: PrimerCheckoutOptions): Promise<PrimerCheckout>

create a Primer checkout component

type PrimerCheckoutOptions

type PrimerCheckoutOptions {
  // Optimise the UX for managing saved payment methods by specifying 'MANAGE_PAYMENT_METHODS' for uxFlow
  uxFlow?: 'CHECKOUT' | 'MANAGE_PAYMENT_METHODS',
  
  // A selector for the container in which to place the checkout component
  container: string;

  // Override the locale
  // By default translations will be provided for the browser's locale
  locale?: string;

  // Your alpha2 country code 
  // [required for Google Pay, Apple Pay and PayPal]
  countryCode?: string;

  // Additional information about the purchase 
  // [required for Google Pay, Apple Pay and PayPal]
  purchaseInfo?: {
    totalAmount: { 
      value: number | string; 
      currency: string; 
    };
  };

  // Control the transition duration when switching between views in the checkout component
  // For more information see the guide on styling
  transitions?: {
    // a number of milliseconds or specify different durations for 'enter' and 'exit'
    duration?: number | { enter: number, exit: number };
    // Callbacks for when a view is transitioning in or out
    onEntering?: (node: Node) => void;
    onEntered?: (node: Node) => void;
    onExiting?: (node: Node) => void;
    onExited?: (node: Node) => void;
  };

  card?: {
    // A stylesheet to inject into each input element
    // For more information see the guide on styling
    css?: string;

    // Choose if the cardholder name should be required or not
    // default value is true
    cardholderNameRequired?: boolean;

    // Checkout will ask the customer id they want to save their card.
    // To disable this feature provide a value for the vault option.
    // When true: the card will be vaulted
    // When false: the card will not be vaulted
    vault?: boolean | () => boolean;
  };

  // 3DS options. These must be provided if you want to perform SCA
  // See the section on 3DS below for more info.
  threeDSecure?: ThreeDSecureVerifyOptions;
  
  // A callback for when tokenization begins
  onTokenizeStart?: () => void;

  // A callback for tokenization success. This will receive the payment method token.
  onTokenizeSuccess: (data: PaymentMethodToken) => void;

  // A callback for when tokenization fails. See the error message here for more information
  onTokenizeError: (message: string) => void;
}

Primer (Advanced usage)

Primer#render(options: PrimerClientRenderOptions): Promise<void>

Securely render a credit card form or alternative payment method buttons.

type PrimerClientRenderOptions

type PrimerClientRenderOptions {
  // Override the locale
  // By default translations will be provided for the browser's locale
  locale?: string;

  // Your alpha2 country code 
  // [required for Google Pay, Apple Pay and PayPal]
  countryCode?: string;

  // Additional information about the purchase 
  // [required for Google Pay, Apple Pay and PayPal]
  purchaseInfo: {
    totalAmount: { 
      value: number | string; 
      currency: string; 
    };
  };

  // A success callback, receives the payment method token.
  onTokenizeSuccess: (data: PaymentMethodToken) => void;

  // A callback for when tokenization begins
  onTokenizeStart?: () => void;

  // A callback for when there is a tokenization error
  onTokenizeError?: (message: string) => void;

  // A callback for when tokenization ends
  onTokenizeEnd?: () => void;

  // Configuration for a credit card form
  card?: {
    // The name of the cardholder
    cardholderName?: string;
    
    // A callback for form metadata
    onChange?: (state: FormState) => void;
    
    // A callback for extra card information (brand etc)
    onCardMetadata?: (meta: CardMetadata) => void;
    
    // Whether or not the form is disabled - this will prevent tokenization if it returns true
    disabled?: () => boolean;

    // A stylesheet to inject into each input element
    // For more information see the guide on styling
    css?: string;
    
    // A DOM selector for a button which will begin the tokenization
    submitButton: string;
    
    // Credit card field configuration
    fields: {
      // Card number field configuration
      cardNumber: CreditCardFieldConfig;
      // Expiry Date field configuration
      expiryDate: CreditCardFieldConfig;
      // CVV field configuration
      cvv: CreditCardFieldConfig;
    };
  };

  // Configuration for alternative payment methods
  // The container property should be a DOM selector for a visible element n the page.
  applePay?: { container: string; };
  googlePay?: { container: string; };
  paypal?: { container: string; };
}

type PaymentMethodToken

A tokenized payment method. Use the token property to authorize transactions. The token object also contains some other metadata describing the payment method which it represents.

type PaymentMethodToken {
  // The token used to authorize transactions
  token: string;
  // The type of payment method which this token represents
  paymentMethodType: 'PAYMENT_CARD' | 'GOOGLE_PAY' | 'APPLE_PAY' | 'PAYPAL';
  // Additional data about the payment method
  paymentMethodData: object;
}

type FormState

Form metadata

type FormState {
  // Whether any field is dirty
  dirty: boolean;
  // Whether any field was been touched
  touched: boolean;
  // Whether any field is active
  active: boolean;
  // Whether all fields are valid
  valid: boolean;
}

type CardMetadata

Additional Card information

type CardMetadata {
  // The card type - 'visa' | 'mastercard' etc
  type?: string;
  // The possible types of the card given the current value
  possibleTypes: string[];
}

type CreditCardFieldConfig

Configuration for credit card fields

type CreditCardFieldConfig {
  // A DOM selector specifying where to render the input
  container: string;
  // Whether to append or prepend the input to the container element
  placement?: 'append' | 'prepend';
  // A placeholder to display when the input is empty
  placeholder?: string;
  // A callback which receives input metadata
  onChange: (data: { meta: FieldMetadata; }) => void;
}

type FieldMetadata

Input metadata for a Credit card field

type FieldMetadata {
  // A validation error
  error?: string;
  // Whether or not the input contains valid information
  valid: boolean;
  // Whether or not the input is focussed
  active: boolean;
  // Whether or not the input's value has been changed
  dirty: boolean;
  // Whether or not the customer has focussed the field
  touched: boolean;
  // Whether or not the form has been submitted
  submitted: boolean;
}

Primer#threeDSecure: ThreeDSecure

Primer 3DS verification API

ThreeDSecure#verify(options: ThreeDSecureVerifyOptions): Promise<ThreeDSecureVerification>

Perform a 3DS verification on a payment method token

type ThreeDSecureVerifyOptions

Options provided to 3DS verification

type ThreeDSecureVerifyOptions {
  // A Payment method token to perform 3DS verification for
  token: string;
  
  // An element selector for the parent of the 3DS challenge UI
  container: string;

  // A callback for when the 3DS challenge starts 
  onChallengeStart?: () => void;

  // A callback for when the 3DS challenge ends
  onChallengeEnd?: () => void;

  // 3DS order details
  order: {
    // Your order ID
    orderId: string;

    amount: {
      // The sale amount
      value: number | string;
      // The alpha3 currency code of the sale
      currency: string;
    };

    // The customer's email address
    email: string;

    billingAddress: {
      // Billing first name
      firstName: string;
      // Billing last name
      lastName: string;
      // Street address
      addressLine1: string;
      // Extended street address
      addressLine2?: string
      // Extended street address
      addressLine3?: string
      // City or town
      city: string;
      // State, region or province
      state?: string;
      // The alpha2 country code of the address
      countryCode: string;
      // The postal or zip code
      postalCode: string;
    }
  };
}

type ThreeDSecureVerification

The result of a 3DS verification. If successful, a new token will be returned.

{
  // The result status of the verification
  status: 'AUTH_SUCCESS' | 'AUTH_FAILED' | 'SKIPPED';
  // Optional error if something unexpected happened
  error?: Error;
  // Data object containing the new token
  data?: PaymentMethodToken;
}