Subscribe Pro PaymentFields Widget API

The following documentation describes the Subscribe ProPaymentFields Widget API, including methods, events, and configuration options.

Access the Subscribe Pro PaymentFields Widget by referencing the global PaymentFields object.

PaymentFields.init(config: PaymentFieldsConfig)

The Subscribe Pro PaymentFields Widget script is configured by passing a configuration object to the PaymentFields.init() function. The configuration object has the following properties:

PaymentFieldsConfig Type

interface PaymentFieldsConfig {
  apiBaseUrl?: string;
  oauthApiToken?: string;
  spVaultEnvironmentId: string;
  paymentMethodType?: PaymentMethodType;
  enableCvv?: boolean;
  enableThreeDs?: boolean;
  enablePrettyFormat?: boolean;  
  numberIframe?: {
    container: string;
    inputStyle?: string;
  };
  cvvIframe?: {
    container: string;
    inputStyle?: string;
  };
  accountIframe?: {
    container: string;
    inputStyle?: string;
  };
  threeDsChallengeIframe?: {
    container: string;
  };
}

PaymentFieldsConfig Properties

Property	Required	Type	Description
`apiBaseUrl`		String	The URL of the Subscribe Pro API to use. Default: `https://api.subscribepro.com`
`oauthApiToken`		String	The OAuth API token to use for authentication. This should be a `customer` scoped OAuth token which was fetched server-side.
`vaultEnvironmentId`	Yes	String	The ID of the Subscribe Pro Vault environment to use. This is a UUID which you should retrieve from the Subscribe Pro Commerce Platform environment you are using. This value is returned in an OAuth token response.
`paymentMethodType`		String	The type of payment method to tokenize. One of: `credit_card`, `bank_account`, `sepa`
`enableCvv`		Boolean	Whether or not to show the CVV field. Default: `true`
`enableThreeDs`		Boolean	Whether or not to enable 3D Secure 2 authentication. Default: `true`
`enablePrettyFormat`		Boolean	Whether or not to enable pretty formatting of the card number. Default: `true`
`numberIframe`		Object	An object containing configuration for the card number iframe.
`numberIframe.container`	Yes	String	The ID of the `<div>` element in which to place the card number iframe.
`numberIframe.inputStyle`		String	A string containing CSS styles to apply to the card number input element.
`cvvIframe`		Object	An object containing configuration for the CVV iframe.
`cvvIframe.container`	Yes	String	The ID of the `<div>` element in which to place the CVV iframe.
`cvvIframe.inputStyle`		String	A string containing CSS styles to apply to the CVV input element.
`accountIframe`		Object	An object containing configuration for the bank account iframe.
`accountIframe.container`	Yes	String	The ID of the `<div>` element in which to place the bank account iframe.
`accountIframe.inputStyle`		String	A string containing CSS styles to apply to the bank account input element.
`threeDsChallengeIframe`		Object	An object containing configuration for the 3D Secure 2 challenge iframe.
`threeDsChallengeIframe.container`	Yes	String	The ID of the `<div>` element in which to place the 3D Secure 2 challenge iframe.

PaymentFields.unmount()

Unmounts the PaymentFields widget iFrames from the DOM. Call PaymentFields.init() to re-mount the widget.

PaymentFields.on(eventName, callback)

This method allows you to register a callback function to be called when the specified event occurs.

Please see here for detail about each event type and the data returned to the event handler callback function: Subscribe Pro PaymentFields Widget Events

PaymentFields.tokenize(args: TokenizeArgs): TokenizeResult

Tokenizes the card data entered into the card number and CVV fields (or other payment data) and optionally initiates a 3D Secure 2 authentication flow.

TokenizeArgs

interface TokenizeArgs {
  authenticateCardholder?: boolean;
  authenticationType?: AuthenticationType;
  paymentDetails?: {
    amount: string;
  };
  cardDetails?: {
    creditcardMonth: string;
    creditcardYear: string;
  };
  customerEmail?: string;
  billingAddress?: {
    firstName: string;
    middleName?: string;
    lastName: string;
    street1?: string;
    street2?: string;
    street3?: string;
    city?: string;
    region?: string;
    postcode?: string;
    country?: string;
  };
  shippingAddress?: {
    firstName: string;
    middleName?: string;
    lastName: string;
    street1?: string;
    street2?: string;
    street3?: string;
    city?: string;
    region?: string;
    postcode?: string;
    country?: string;
  };
}

TokenizeArgs Properties

Property	Required	Type	Description
`authenticateCardholder`		Boolean	Whether or not to initiate a 3D Secure 2 authentication flow. Default: `false`
`authenticationType`		String	The type of 3D Secure 2 authentication to use - corresponds to whether the credit card is being collected in the context of a payment or not. One of: `payment`, `non_payment` Required if `authenticateCardholder` is `true`.
`paymentDetails`		Object	An object containing details about the payment. Required if `authenticationType` is `payment`.
`paymentDetails.amount`	Yes	String	The amount of the payment.
`cardDetails`		Object	An object containing details about the credit card. Required if PaymentFields configured for credit card.
`cardDetails.creditcardMonth`	Yes	String	The month of the credit card expiration date.
`cardDetails.creditcardYear`	Yes	String	The year of the credit card expiration date.
`customerEmail`		String	The email address of the customer.
`billingAddress`		Object	An object containing details about the billing address for a payment and for 3D Secure 2 authentication.
`billingAddress.firstName`	Yes	String	The first name of the customer.
`billingAddress.middleName`		String	The middle name of the customer.
`billingAddress.lastName`	Yes	String	The last name of the customer.
`billingAddress.street1`		String	The first line of the street address.
`billingAddress.street2`		String	The second line of the street address.
`billingAddress.street3`		String	The third line of the street address.
`billingAddress.city`		String	The city of the address.
`billingAddress.region`		String	The region (state, province, etc) of the address.
`billingAddress.postcode`		String	The postal code of the address.
`billingAddress.country`		String	The country of the address.
`shippingAddress`		Object	An object containing details about the shipping address for a payment and for 3D Secure 2 authentication.
`shippingAddress.firstName`	Yes	String	The first name of the customer.
`shippingAddress.middleName`		String	The middle name of the customer.
`shippingAddress.lastName`	Yes	String	The last name of the customer.
`shippingAddress.street1`		String	The first line of the street address.
`shippingAddress.street2`		String	The second line of the street address.
`shippingAddress.street3`		String	The third line of the street address.
`shippingAddress.city`		String	The city of the address.
`shippingAddress.region`		String	The region (state, province, etc) of the address.
`shippingAddress.postcode`		String	The postal code of the address.
`shippingAddress.country`		String	The country of the address.