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

<!-- 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

optionsobject

An optional object containing properties for customizing the Pay Form.

options.applePayobject

An optional object containing properties for customizing Apple Pay.

options.applePay.enabledboolean

Apple Pay button will be shown when true. Default is false.

options.applePay.totalLabelstring

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.

options.applePay.supportedNetworksArray of strings

Optional array of supported card types for Apple Pay. Defaults to support all.

Items Enum"visa""mastercard""amex""maestro""jcb"

options.googlePayobject

An optional object containing properties for customizing Google Pay.

options.googlePay.enabledboolean

Google Pay button will be shown when true. Default is false.

options.googlePay.merchantInfoobject

An object containing properties for defining merchant information.

options.googlePay.merchantInfo.merchantNamestring

The name of the merchant.

options.googlePay.merchantInfo.merchantIdstring

The Google Pay merchant id. It is only required for production.

options.googlePay.supportedNetworksArray of strings

Optional array of supported card types for Google Pay. Defaults to support all.

Items Enum"visa""mastercard""amex""jcb"

options.walletButtonsobject

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

options.walletButtons.singleButtonOnlyboolean

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.

options.creditCardFormobject

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

options.creditCardForm.enabledboolean

Credit Card Form will be shown when true. Default is true.

options.creditCardForm.supportedNetworksArray 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"

options.poweredByTyroobject

An optional object containing properties related to the Powered by Tyro logo that can be displayed at the bottom of the Pay Form.

options.poweredByTyro.enabledboolean

stylePropsobject

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

themestring

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

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

Implementation

// 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'],
    },
    poweredByTyro: {
        enabled: true,
    }
  }
});

payForm.inject(selector)

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

Method Parameters

selectorstringrequired

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

Implementation

// 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

// 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

paymentTypestring

The payment type used for the wallet payment

Enum"GOOGLE_PAY""APPLE_PAY"

Implementation

// 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

paymentTypestring

The payment type used for the wallet payment

Enum"GOOGLE_PAY""APPLE_PAY"

Implementation

// 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

paymentTypestring

The payment type used for the wallet payment

Enum"GOOGLE_PAY""APPLE_PAY"

errorobject

Will be defined if there is an error

Error Object

typestring

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"

Example: "SERVER_VALIDATION_ERROR"

errorMessagestring

The error message for a submitted transaction if available e.g. Insufficient Funds

Example: "Insufficient Funds"

errorCodestring

The error code for a declined transaction if available e.g. Insufficient Funds

Example: "INSUFFICIENT_FUNDS"

gatewayCodestring

The code returned by the payment gateway for a submitted transaction e.g. DECLINED

Example: "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

// 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();
    }
});