# 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
``` ## 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](/app/apis/pay/tyro-js/style-guide) for detailed information about appearance customizations. #### Config Parameters ```json { "$ref": "#/components/schemas/pay-form-options", "components": { "schemas": { "pay-form-options": { "type": "object", "properties": { "options": { "description": "An optional object containing properties for customizing the Pay Form.", "properties": { "applePay": { "type": "object", "description": "An optional object containing properties for customizing Apple Pay.", "properties": { "enabled": { "type": "boolean", "description": "Apple Pay button will be shown when true. Default is false." }, "totalLabel": { "type": "string", "description": "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": { "type": "array", "description": "Optional array of supported card types for Apple Pay. Defaults to support all.", "items": { "type": "string", "enum": [ "visa", "mastercard", "amex", "maestro", "jcb" ] } } } }, "googlePay": { "type": "object", "description": "An optional object containing properties for customizing Google Pay.", "properties": { "enabled": { "type": "boolean", "description": "Google Pay button will be shown when true. Default is false." }, "merchantInfo": { "type": "object", "description": "An object containing properties for defining merchant information.", "properties": { "merchantName": { "type": "string", "description": "The name of the merchant." }, "merchantId": { "type": "string", "description": "The Google Pay merchant id. It is only required for production." } } }, "supportedNetworks": { "type": "array", "description": "Optional array of supported card types for Google Pay. Defaults to support all.", "items": { "type": "string", "enum": [ "visa", "mastercard", "amex", "jcb" ] } } } }, "walletButtons": { "type": "object", "description": "An optional object containing properties for customizing the wallet pay buttons.", "properties": { "singleButtonOnly": { "type": "boolean", "description": "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." } } }, "creditCardForm": { "type": "object", "description": "An optional object containing properties for customizing the Credit Card Form.", "properties": { "enabled": { "type": "boolean", "description": "Credit Card Form will be shown when true. Default is true." }, "supportedNetworks": { "type": "array", "description": "Optional array of supported card types for the credit card form. Defaults to support all, and may be limited by your merchant account.", "items": { "type": "string", "enum": [ "visa", "mastercard", "amex", "jcb", "maestro", "diners" ] } } } }, "poweredByTyro": { "type": "object", "description": "An optional object containing properties related to the Powered by Tyro logo that can be displayed at the bottom of the Pay Form.", "properties": { "enabled": { "type": "boolean", "description": "Powered by Tyro logo will be shown when true. Default is false." } } } } } } } } } } ``` ```json { "$ref": "#/components/schemas/style-props", "components": { "schemas": { "style-props": { "type": "object", "properties": { "styleProps": { "description": "An optional object containing properties for customizing the appearance of the widget.", "properties": { "applePayButton": { "type": "object", "properties": { "buttonBorderRadius": { "type": "string", "description": "Border radius of the Apple Pay button." }, "buttonStyle": { "type": "string", "enum": [ "black", "white", "white-outline" ], "description": "Style of the Apple Pay button. Defaults to black." }, "buttonType": { "type": "string", "enum": [ "plain", "pay", "buy", "order", "book", "check-out", "continue", "add-money", "contribute", "donate", "reload", "rent", "set-up", "subscribe", "support", "tip", "top-up" ], "description": "Type of the Apple Pay button. Setting this property will add text to the Apple Pay button based on the type chosen. Defaults to plain." } } }, "googlePayButton": { "type": "object", "properties": { "buttonColor": { "type": "string", "enum": [ "black", "white", "default" ], "description": "Style of the Google Pay button. Defaults to default." }, "buttonType": { "type": "string", "enum": [ "book", "buy", "checkout", "donate", "order", "pay", "plain", "subscribe" ], "description": "Type of the Google Pay button. Setting this property will add text to the Google Pay button based on the type chosen. Defaults to buy." } } }, "walletPaymentsDividerText": { "type": "string", "description": "Optional text to show in the wallet payments divider. Default is \"Or pay with card\". Empty is allowed." }, "walletPaymentsDividerEnabled": { "type": "boolean", "description": "Optional flag to enable or disable the wallet payments divider. Defaults to true." }, "walletPaymentsButtonsWidth": { "type": "string", "description": "Optional width property for the wallet payments buttons." }, "walletPaymentsButtonsHeight": { "type": "string", "description": "Optional height property for the wallet payments buttons." }, "walletPaymentsButtonsMargin": { "type": "string", "description": "Optional margin property for spacing around the wallet payment buttons. Defaults to 8px." }, "walletPaymentsButtonsGap": { "type": "string", "description": "Optional gap or space that applies around multiple buttons when present. Defaults to 20px." }, "walletPaymentsButtonsAlign": { "type": "string", "enum": [ "LEFT", "RIGHT", "CENTER" ], "description": "Optional property to set the wallet payment buttons alignment. Defaults to CENTER. You must specify a fixed walletPaymentsButtonsWidth for this properties to take effect." }, "walletPaymentsButtonsStacking": { "type": "string", "enum": [ "HORIZONTAL", "VERTICAL" ], "description": "Optional property to set how multiple wallet payment buttons should be positioned on the form. Defaults to HORIZONTAL. Note: Will be forced to VERTICAL under 380px screen resolution." }, "bodyBackgroundColor": { "type": "string", "description": "The background color of the widget." }, "bodyPadding": { "type": "string", "description": "The padding around the widget." }, "bodyWidth": { "type": "string", "description": "The width of the iframe. Defaults to 100%." }, "bodyMinWidth": { "type": "string", "description": "The minimum width of the iframe. Defaults to 500px." }, "bodyMaxWidth": { "type": "string", "description": "The maximum width of the iframe. Defaults to 780px." }, "fontFamily": { "type": "string", "enum": [ "arial", "roboto", "serif" ], "description": "The font family of all text inside the widget. Defaults to system font." }, "inputBackgroundColor": { "type": "string", "description": "The background color of an input field." }, "inputBorderColor": { "type": "string", "description": "The border color of an input field." }, "inputBorderSize": { "type": "string", "description": "The border thickness of an input field." }, "inputBorderRadius": { "type": "string", "description": "The border radius of all corners of an input field." }, "inputFontColor": { "type": "string", "description": "The font color of text inside an input field." }, "inputFontSize": { "type": "string", "description": "The font size of text inside an input field." }, "inputFontLetterSpacing": { "type": "string", "description": "The font letter spacing size of text inside an input field." }, "inputFontWeight": { "type": "string", "description": "The font weight of text inside an input field." }, "inputErrorFontColor": { "type": "string", "description": "The font color of text inside an input field when it is in an invalid state." }, "inputErrorBorderColor": { "type": "string", "description": "The border color of an input field when it is in an invalid state." }, "inputErrorBorderSize": { "type": "string", "description": "The border thickness of an input field when it is in an invalid state." }, "inputFocusBackgroundColor": { "type": "string", "description": "The background color of an input field when it is focused." }, "inputFocusBorderColor": { "type": "string", "description": "The border color of an input field when it is focused." }, "inputFocusBorderSize": { "type": "string", "description": "The border thickness of an input field when it is focused." }, "inputFocusFontColor": { "type": "string", "description": "The font color of text inside an input field when it is focused." }, "inputPadding": { "type": "string", "description": "The padding inside an input field." }, "inputSpacing": { "type": "string", "description": "The amount of vertical space between inputs, irrespective of error messages." }, "labelPosition": { "type": "string", "enum": [ "block", "floating", "inline" ], "description": "The label position relative to the input field." }, "labelFontColor": { "type": "string", "description": "The font color of a label." }, "labelFontSize": { "type": "string", "description": "The font size of a label." }, "labelFontLetterSpacing": { "type": "string", "description": "The font letter spacing size a label." }, "labelFontWeight": { "type": "string", "description": "The font weight of a label." }, "labelPadding": { "type": "string", "description": "The padding inside a label." }, "errorBackgroundColor": { "type": "string", "description": "The background color of an error message." }, "errorFontColor": { "type": "string", "description": "The font color of an error message." }, "errorFontSize": { "type": "string", "description": "The font size of an error message." }, "errorFontLetterSpacing": { "type": "string", "description": "The font letter spacing size an error message." }, "errorFontWeight": { "type": "string", "description": "The font weight on an error message." }, "errorPadding": { "type": "string", "description": "The padding inside an error message." }, "showCardIcon": { "type": "boolean", "description": "Will display a visual aid card brand icon, and security code helper icon in the respective inputs. Defaults to true." }, "showErrorSpacing": { "type": "boolean", "description": "Reserves space equal to the size of the error message under each field. Defaults to true." }, "showSupportedCards": { "type": "boolean", "description": "Will show a list of supported card types. Defaults to true." } } } } } } } } ``` ```json { "$ref": "#/components/schemas/theme", "components": { "schemas": { "theme": { "type": "object", "properties": { "theme": { "description": "An optional string to load a set of preset styleProps. Defaults to default.", "type": "string", "enum": [ "default", "dark", "sharp", "minimal" ] } } } } } } ``` #### Implementation ```javascript // 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 ```json { "type": "object", "properties": { "selector": { "type": "string", "description": "The selector that identifies the HTML container that the Pay Form should be injected into." } }, "required": [ "selector" ] } ``` #### Implementation ```javascript // 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 // 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 ```json { "type": "object", "properties": { "paymentType": { "type": "string", "enum": [ "GOOGLE_PAY", "APPLE_PAY" ], "description": "The payment type used for the wallet payment" } } } ``` #### Implementation ```javascript // 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 ```json { "type": "object", "properties": { "paymentType": { "type": "string", "enum": [ "GOOGLE_PAY", "APPLE_PAY" ], "description": "The payment type used for the wallet payment" } } } ``` #### Implementation ```javascript // 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 ```json { "type": "object", "properties": { "paymentType": { "type": "string", "enum": [ "GOOGLE_PAY", "APPLE_PAY" ], "description": "The payment type used for the wallet payment" }, "error": { "type": "object", "description": "Will be defined if there is an error" } } } ``` #### Error Object ```json { "$ref": "#/components/schemas/tyro-js-error", "components": { "schemas": { "tyro-js-error": { "title": "Tyro JS Error", "type": "object", "properties": { "type": { "type": "string", "description": "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" }, "errorMessage": { "type": "string", "description": "The error message for a submitted transaction if available e.g. Insufficient Funds", "example": "Insufficient Funds" }, "errorCode": { "type": "string", "description": "The error code for a declined transaction if available e.g. Insufficient Funds", "example": "INSUFFICIENT_FUNDS" }, "gatewayCode": { "type": "string", "description": "The code returned by the payment gateway for a submitted transaction e.g. DECLINED", "example": "DECLINED" } } } } } } ``` * For more `type` information see [Error Types](/app/apis/pay/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](/app/apis/pay/errors) . #### Implementation ```javascript // 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(); } }); ```