The Pay Form

The Pay Form is provided by Tyro and used to securely collect customer payment details.

Create the HTML

Create the container where the Pay Form will be injected into.
Create the submit button

Copy

Copied

<!-- HTML sample code -->
<form id="pay-form">
  <div id="tyro-pay-form">
    <!--Tyro.js injects the Pay Input Fields -->
  </div>
  <button id="pay-form-submit">Pay</button>
</form>

tyro.createPayForm(config)

This method creates an instance of the Pay Form, and optionally supports a parameter object to customize the appearance.

Please refer to the Style Guide for detailed information about appearance customizations.

Config Parameters

object

An optional object containing properties for customizing the Pay Form.

object

An optional object containing properties for customizing Apple Pay.

enabled	boolean Apple Pay button will be shown when true. Default is false.
totalLabel	string Optional total label shown for Apple Pay payments. Use the same business name people see when they look for the charge on their bank or credit card statement, for example, Merchant Name.
supportedNetworks	Array of strings Optional array of supported card types for Apple Pay. Defaults to support all. Items Enum: "visa" "mastercard" "amex" "maestro" "jcb"

object

An optional object containing properties for customizing Google Pay.

enabled	boolean Google Pay button will be shown when true. Default is false.
	object An object containing properties for defining merchant information.
supportedNetworks	Array of strings Optional array of supported card types for Google Pay. Defaults to support all. Items Enum: "visa" "mastercard" "amex" "jcb"

object

An optional object containing properties for customizing the wallet pay buttons.

singleButtonOnly

boolean

Only a single wallet pay button will be shown that is most appropriate for the environment the pay form is displayed on. On Mac OS X and iOS running in Safari only the Apple Pay button will be displayed. On all other environments only the Google Pay button will be shown. Default is false.

object

An optional object containing properties for customizing the Credit Card Form.

enabled	boolean Credit Card Form will be shown when true. Default is true.
supportedNetworks	Array of strings Optional array of supported card types for the credit card form. Defaults to support all, and may be limited by your merchant account. Items Enum: "visa" "mastercard" "amex" "jcb" "maestro" "diners"

object

An optional object containing properties for customizing the appearance of the widget.

theme

string

An optional string to load a set of preset styleProps. Defaults to default.

Enum: "default" "dark" "sharp" "minimal"

Implementation

Copy

Copied

// Javascript code sample
const payForm = tyro.createPayForm({
  // Example properties
  theme: 'default',
  styleProps: {
    bodyMinWidth: 250,
    bodyMaxWidth: 980,
    labelPosition: 'block',
    walletPaymentsButtonsPadding: '30px',
    applePayButton: {
      buttonStyle: 'black'
    }
  },
  options: {
    applePay: {
      enabled: true,
      totalLabel: 'Example Merchant Name',
      supportedNetworks: ['visa', 'mastercard'],
    },
    googlePay: {
      enabled: true,
      merchantInfo: {
        merchantName: 'Example Merchant Name',
        merchantId: 'example-merchant-id-000',
      },
      supportedNetworks: ['visa', 'mastercard'],
    },
    creditCardForm: {
      enabled: true,
      supportedNetworks: ['visa', 'mastercard', 'amex'],
    }
  }
});

payForm.inject(selector)

Injects the Pay Form into the HTML page. Returns a Promise.

Method Parameters

selector

required

string

The selector that identifies the HTML container that the Pay Form should be injected into.

Implementation

Copy

Copied

// Javascript code sample
await payForm.inject("#tyro-pay-form");

Event Functions

payForm.setReadyListener(listener)

Sets the readyListener on the Pay Form. This listener is called when the payRequest has loaded and the payForm is ready for processing.

Implementation

Copy

Copied

// Javascript code sample
payForm.setReadyListener(() => {
  // your code to handle presentation, animations or show the pay button
});

Wallet Payment Functions

payForm.isApplePaySupported()

Returns true if Apple Pay is supported, otherwise false.

payForm.isGooglePaySupported()

Returns true if Google Pay is supported, otherwise false.

payForm.setWalletPaymentBeginListener(listener)

Sets the walletPaymentBeginListener on the Pay Form. This listener is called at the beginning of a wallet payment before the dialog is shown.

Listener Function Parameters

paymentType

string

The payment type used for the wallet payment

Enum: "GOOGLE_PAY" "APPLE_PAY"

Implementation

Copy

Copied

// Javascript code sample
payForm.setWalletPaymentBeginListener((paymentType) => {
  // your code to show loading state
});

payForm.setWalletPaymentCancelledListener(listener)

Sets the walletPaymentCancelledListener on the Pay Form. This listener is called when a wallet payment is cancelled by the user.

Listener Function Parameters

paymentType

string

The payment type used for the wallet payment

Enum: "GOOGLE_PAY" "APPLE_PAY"

Implementation

Copy

Copied

// Javascript code sample
payForm.setWalletPaymentCancelledListener((paymentType) => {
  // your code to handle a cancelled wallet payment
});

payForm.setWalletPaymentCompleteListener(listener)

Sets the walletPaymentCompleteListener on the Pay Form. This listener is called when a wallet payment transaction is complete or errors. The error object will be defined if there is an error.

Listener Function Parameters

paymentType	string The payment type used for the wallet payment Enum: "GOOGLE_PAY" "APPLE_PAY"
error	object Will be defined if there is an error

Error Object

type	string The error type can be used to determine what is shown to the customer e.g. SERVER_VALIDATION_ERROR Enum: "CLIENT_VALIDATION_ERROR" "SERVER_VALIDATION_ERROR" "CARD_ERROR" "SERVER_ERROR" "UNKNOWN_ERROR"
errorMessage	string The error message for a submitted transaction if available e.g. Insufficient Funds
errorCode	string The error code for a declined transaction if available e.g. Insufficient Funds
gatewayCode	string The code returned by the payment gateway for a submitted transaction e.g. DECLINED

For more type information see Error Types.
Depending on the stage of the particular error, different error codes can be returned. Please refer to full list of supported Error Codes.

Implementation

Copy

Copied

// Javascript sample code
async function showPaymentResult() {
  const payRequest = await tyro.fetchPayRequest();

  switch (payRequest.status) {
    case "SUCCESS":
      return showSuccess();
    case "FAILED":
      return showFail();
    ......
  }
}

payForm.setWalletPaymentCompleteListener((paymentType, error) => {
    if(error) {
        const { type, errorMessage, errorCode, gatewayCode } = error;
        // handle errors here
            switch (type) {
            case "SERVER_VALIDATION_ERROR":
                return showServerValidationError(errorMessage, errorCode, gatewayCode);
            case "CARD_ERROR":
                return showCardError(errorMessage, errorCode, gatewayCode);
            case "SERVER_ERROR":
                return showGenericError(errorMessage, errorCode, gatewayCode);
            ......
            }
    } else {
        showPaymentResult();
    }
});