> Note: Replace [GR4VY_ID] and [SESSION_ID] with the ID of your instance
> and the Session ID obtained from calling the Checkout Sessions API.

| Prop Name | Description |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| gr4vyId | Your Gr4vy ID. |
| environment | Your Gr4vy environment. Can be either sandbox or production. |
| sessionId | The Session ID. |
| paymentMethod | An optional object { id: string, scheme: string } for stored payment methods. |
| paymentMethodId | An optional uuid for stored payment methods. Deprecated: This prop is no longer recommended for use and will be removed in a future release. Please use paymentMethod instead. |
| debug | Enables / disables the debug mode. |
| font | Loads a custom font from Google Fonts to be used inside inputs. You can define the font family as well as styles or weights as a string (e.g. "Lato:400,600"). To use the loaded font, add the correct fontFamily property to the styles object when rendering fields. |
| onReady | An event handler that listens for Secure Fields to be securely loaded. It listens for the READY event and accepts a callback function. |
| onFormChange | An event handler that listens for Secure Fields change. It listens for the FORM_CHANGE event and accepts a callback function. |
| onCardVaultSuccess | An event handler that listens for card data to be securely vaulted. It listens for the CARD_VAULT_SUCCESS event and accepts a callback function. |
| onCardVaultFailure | An event handler that listens for any failures when storing any card data. It listens for the CARD_VAULT_FAILURE event and accepts a callback function. |

$3

Within the SecureFields provider you can now create your own card form using each of the Secure Field components.

Additionally, a useSecureFields hook is available to get the configured Secure Fields instance which can be
used to submit() the card form, and check if debug is enabled or not.

`js
const {
CardNumber,
ExpiryDate,
SecurityCode,
} = require('@gr4vy/secure-fields-react')

// Alternatively:
// import {
// CardNumber,
// ExpiryDate,
// SecurityCode
// } from "@gr4vy/secure-fields-react"

const Form = () => {
const { secureFields } = useSecureFields()

const handleSubmit = () => {
secureFields.submit()
}

return (
<>
Card number


Expiry date


Security code


Submit

)
}
`

You can also collect other kind of information along with the card data. We currently support an additional postal code field, which can be added to your form using Field component, passing the specific type and the rest of the options.

`js
const { Field } = require('@gr4vy/secure-fields-react')

Postal code
type="postalCode"
pattern="[A-Z][0-9]\s[0-9][A-Z]{2}" // optional, defaults to 5 characters minimum
/>
`

Field Components

The available secure fields components are CardNumber, ExpiryDate, SecurityCode and Field. You can pass the following props to customize each of them.

| Prop Name | Description |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| placeholder | Input placeholder text. |
| pattern | A pattern the field value should match, defined as a string (regular expression). Only for postal code fields. |
| styles | An object of CSS rules to style the input inside the iframe. See Styles for more information. |
| onBlur | Attaches an event handler to the input, listening for the blur event. The data available in the passed callback includes an id representing the field type (e.g. expiryDate). |
| onFocus | Attaches an event handler to the input, listening for the focus event. The data available in the passed callback includes an id representing the field type (e.g. expiryDate). |
| onInput | Attaches an event handler to the input, listening for the input event. The data available in the passed callback includes an id representing the field type (e.g. expiryDate) and some useful card validation information, such as the current scheme (e.g. visa) and security code label (e.g. CVV). |

Click to Pay

Click to Pay is the better way to pay online – featuring advanced payment technology built on secure remote commerce industry standards.

$3

Follow the instructions for Click to Pay Merchant Setup.

$3

Once Secure Fields is configured, you can start adding Click to Pay to your checkout.

Firstly, add the ClickToPay component to your form so Secure Fields can render Click to Pay. Make sure to pass the required options to it as props.

Then, add a sign-in form to let users access their Click to Pay stored cards and wrap it with the ClickToPaySignIn component.

Additionally, add a checkbox to allow a customer not already enrolled to determine if they want to share their card data with Click to Pay.

Finally, ensure card inputs are wrapped with the CardForm component.

`js
import { ClickToPay, ClickToPaySignIn, CardForm } from '@gr4vy/secure-fields-react'

...

const { secureFields } = useSecureFields()

dpaLocale="en_AU"
cardBrands={['mastercard', 'visa', 'american-express']}
email="john@example.com"
mobileNumber={{
countryCode: '61',
phoneNumber: '491570159',
}}
consentCheckbox="#click-to-pay-consent-checkbox"
/>

onVisibilityChange={(visible: boolean) => {
console.log('Sign in UI visibility changed. Visible', visible)
}}
>
Access your Click to Pay stored cards

className="px-4 py-2 text-white bg-blue-500 rounded-md hover:bg-blue-600"
onClick={() => secureFields?.clickToPay?.signIn({ email: phoneOrEmailRef?.current?.value })}
>Continue



Card number


Expiry date


Security code



The ClickToPay component accepts the following props:

| Prop Name | Description |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| srcDpaId | DPA Identifier. This is a unique identifier for you Digital Payment Application (DPA), which was generated during onboarding. |
| dpaName | Legal name of registered DPA. |
| cardBrands | List of card schemes the merchant accepts. We currently support mastercard, maestro, visa, amex, discover |
| consentCheckbox | A reference to the opt-in consent checkbox element. |
| learnMoreLink | A reference to the learn more link element. |
| email | The user email used to access Click to Pay. |
| mobileNumber | The user phone number used to access Click to Pay. Required format is { countryCode: string, phoneNumber: string } |
| dynamicDataType | The type of cryptogram or token used for the card data. See the Mastercard docs for more information. Possible values are NONE and CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM. |

$3

The following props can be used on the SecureFields component to listen to specific Click to Pay events.

| Prop Name | Description |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| onClickToPayInitialized | An event handler that listens for Click to Pay to be securely initialized. It listens for the CLICK_TO_PAY_INITIALIZED event and accepts a callback function with a clickToPay instance as argument. |
| onClickToPayReady | An event handler that listens for Click to Pay to be ready. It listens for the CLICK_TO_PAY_READY event and accepts a callback function with an object { buyerExists: boolean }. |
| onClickToPaySignOut | An event handler that listens for users signing out of Click to Pay. It listens for the CLICK_TO_PAY_SIGN_OUT event and accepts a callback function. |
| onClickToPayError | An event handler that listens for any errors thrown by Click to Pay. It listens for the CLICK_TO_PAY_ERROR event and accepts a callback function with the error type (one of \| 'RETRIES_EXCEEDED' \| 'CODE_INVALID' \| 'INVALID_CARD' \| 'SIGN_OUT_FAILED' \| 'ACCT_INACCESSIBLE' \| 'UNKNOWN' \| 'USER_NOT_RECOGNIZED'). |
| onClickToPayCancel | An event handler that listens for users closing / cancelling Click to Pay. It listens for the CLICK_TO_PAY_CANCEL event and accepts a callback function. |
| onClickToPayCheckoutWithNewCard | An event handler that listens for users checking out with a new card. It listens for the CLICK_TO_PAY_CHECKOUT_WITH_NEW_CARD event and accepts a callback function. |
| onClickToPayUnableToLoadDpa | An event handler that listens for Click to Pay not being able to load the provided DPA. It listens for the CLICK_TO_PAY_UNABLE_TO_LOAD_DPA event and accepts a callback function. |
| onMethodChange | An event handler that listens for users selecting a different method (either card or click-to-pay). It listens for the METHOD_CHANGE` event and accepts a callback function with the selected method. |