Click to Pay with Secure Fields

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

​

Merchant setup

In order to process Click to Pay payments you will need to register as a Digital Payments Application (DPA). You can set up Click to Pay in the dashboard which will automatically register and configure your DPA with Mastercard.

​

Prepare the server

Before you can load Click to Pay with Secure Fields into your checkout, you will need to generate a checkout session via the API. This is made easy with our server-side SDKs.

​

Install a server-side SDK

Use the package manager in your preferred programming language to install our server-side SDK. Generating a checkout session can only be done server side and we do not recommend doing this client side as it will expose your API key to your customers.

npm install @gr4vy/node --save
# or: yarn add @gr4vy/node

​

Initialize the SDK client

Next, initialize the SDK with the ID of your instance and the private key.

const fs = require("fs");
const { Client } = require("@gr4vy/node");
// or: import { Client } from "@gr4vy/node";

const key = String(fs.readFileSync("./private_key.pem"));

const client = new Client({
  gr4vyId: "[GR4VY_ID]",
  privateKey: key,
});

This assumes the key you created in the previous step is kept in a file called private_key.pem that is kept in the same folder next to the code. You could store this key in an environment variable or a secure vault.

​

Create a checkout session

With the SDK installed, you can use it to create a checkout session for use with Click to Pay.

const response = await this.newCheckoutSession();

​

Create your checkout

With your checkout session ready, it’s time to start creating a card form that can support Click to Pay.

Our frontend integration is called Secure Fields and it essentially wraps each of your credit card input fields in a secure element, keeping you PCI-compliant and allowing for seamless integration with Click to Pay.

​

Install Secure Fields

There are three ways to install Secure Fields for use with Click to Pay: either as a React library, a Node library or straight off our CDN.

npm install @gr4vy/secure-fields-react --save
# or: yarn add @gr4vy/secure-fields-react

import { SecureFields } from "@gr4vy/secure-fields-react";

<SecureFields
  gr4vyId="[GR4VY_ID]"
  environment="sandbox" // or "production"
  sessionId="[CHECKOUT_SESSION.ID]"
  // enable debugging
  debug
>
  <Form />
</SecureFields>

{sessionId && (
  <SecureFields ...>
    ...
  </SecureFields>
)}

import { 
  CardForm, 
  CardNumber, 
  ExpiryDate, 
  SecurityCode,
  useSecureFields
} from '@gr4vy/secure-fields-react'

const secureFields = useSecureFields()

{/* This card form will automatically hide  */}
<CardForm
  onVisibilityChange={(visible: boolean) => {
    console.log('Card form visibility changed. Visible', visible)
  }}
>
  <div id="cc-form" className="max-w-xs">
    {/* You can add your own fields as well as secure fields */}
    <label for="cc-holder-name">Name</label>
    <input id="cc-holder-name" placeholder="Name on the card" />
    
    {/* These are fields that will become secure fields */}
    <label htmlFor="cc-number">Card number</label>
    <CardNumber styles={styles} />

    <label htmlFor="cc-expiry-date">Expiry date</label>
    <ExpiryDate styles={styles} />

    <label htmlFor="cc-security-code">Security code</label>
    <SecurityCode styles={styles} />

    <button onClick={() => secureFields.submit()}>Pay</button>
  </div>
</CardForm>

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

 {/* The main Click to Pay component */}
<ClickToPay
  srcDpaId='{SRC_DPA_ID}'
  dpaName='{DPA_NAME}'
  dpaLocale='en_AU'
  cardBrands={['mastercard', 'visa', 'amex']}
  consentCheckbox='#click-to-pay-consent-checkbox'
  learnMoreLink="#click-to-pay-learn-more-link"
  // email='john@example.com' // optional: define a Click to Pay user e-mail instead of capturing it with the sign-in form
  /* mobileNumber={{
    countryCode: "61",
    phoneNumber: "491570159"
  }} */ // optional: define a Click to Pay user phone instead of capturing it with the sign-in form
/>

 {/* An optional sign-in with email or phone for Click to Pay would go here */}
<ClickToPaySignIn data-testid="sign-in">
  <label>Access your Click to Pay stored cards</label>
  <input type="text" className="email" ref={ref} />
  {/* This shows how to sign in with email. For the mobile number use the `mobileNumber` with a `countryCode` and `number` */}
  <button onClick={() => secureFields.clickToPay.signIn({ email: ref.current.value })}>
    Sign in
  </button>
</ClickToPaySignIn>

<CardForm>
  {/* ... */}

  <input type="checkbox" id="click-to-pay-consent-checkbox" />
  <label htmlFor="click-to-pay-consent-checkbox">
    Store my card with Click to Pay <a href="javascript:void(0)" id="click-to-pay-learn-more-link">Learn more</a>
  </label>

  {/* ... */}
</CardForm>

<SecureFields onCardVaultSuccess={async () => {
    // call your API
  }}
>...</SecureFields>

​

Create a payment

With the card data stored in the vault, you are now ready to create a transaction on the server-side. To create a transaction you can pass the amount, currency, as well as the payment method, in this case a checkout session.

const request = new TransactionRequest();
request.amount = 1299;
request.currency = "AUD";

request.paymentMethod = new TransactionPaymentMethodRequest();
request.paymentMethod.method = "checkout-session";
request.paymentMethod.id = "[CHECKOUT_SESSION.ID]";

const transaction = await client.authorizeNewTransaction(request);

​

Error handling

The available error codes for Click to Pay are as follows. It is recommended to catch and handle Click to Pay errors as required.

• CODE_INVALID - The user entered an incorrect OTP. An error message is also displayed on the OTP component.
• INVALID_CARD - The user entered incorrect card details, or the details of a card that is not one of the supported schemes.
• ACCT_INACCESSIBLE - The user’s account is temporarily not accessible.
• USER_NOT_RECOGNIZED - The user is not recognized by Click to Pay (typically when a user hasn’t signed in yet).
• UNKNOWN - An unknown error occurred. These are usually unrecoverable. For example, the Click to Pay library was not initialized due to an invalid parameter.
• RETRIES_EXCEEDED - The user has exceeded the maximum number of retries filling in their one-time password (OTP) and their profile is locked. An error message is also displayed in the OTP component. It is recommended to hide the Click to Pay component for the user at this point.
• SIGN_OUT_FAILED - When attempting to sign out via the “Not you?” link, it is possible that Click to Pay is not able to sign out the user. It is recommended to hide the Click to Pay component for the user at this point.

<SecureFields
  ...
  onClickToPayError={({ error }) => {
    if (error.code === 'RETRIES_EXCEEDED' ||
        error.code === 'SIGN_OUT_FAILED') {
      // Hide the Click to Pay component
      setClickToPayVisible(false);
    }
    console.error(error);
  }}
/>

​

Events

<CardForm onVisibilityChange={(visible) => console.log('Card form visible', visible)} />

​

Links