New
Web Payments SDK

Verify Buyer

Learn how to add strong customer authentication (SCA) to the card payment integration that you built using the quickstart project sample in Take a Card Payment with Web Payments SDK to integrate the Web Payments SDK into your application.

The instructions add code to the application you created from the quickstart project sample. If you have not created an application using the quickstart, you need to do so before completing the following steps.

An example of the front-end SCA code can be found in the GitHub Web Payments SDK Quickstart repository.

Step 1: Add strong customer authentication Permalink Get a link to this section

Your production application needs to collect the billing address of the buyer. For this example, you work from an object that is declared with a hard-coded billing address.

The code in the following steps adds the billing contact values needed by SCA to verify the authenticity of the card holder:

  1. Add the following function below the tokenize function in your script tag:

    async function verifyBuyer(payments, token) {
      const verificationDetails = {
        amount: '1.00',
        /* collected from the buyer */
        billingContact: {
          addressLines: ['123 Main Street', 'Apartment 1'],
          familyName: 'Doe',
          givenName: 'John',
          email: 'jondoe@gmail.com',
          country: 'GB',
          phone: '3214563987',
          region: 'LND',
          city: 'London',
        },
        currencyCode: 'GBP',
        intent: 'CHARGE',
      };
    
      const verificationResults = await payments.verifyBuyer(
        token,
        verificationDetails
      );
      return verificationResults.token;
    }
    
  2. Update the call to handlePaymentMethodSubmission in the cardButton click handler to include a third argument of true.

     cardButton.addEventListener('click', async function (event) {
       // add 3rd argument of `true`  
       handlePaymentMethodSubmission(event, card, true);
     });
    
  3. Update the handlePaymentSubmission function in the DOMContentLoaded eventListener function to have a third parameter shouldVerify and a call to the verifyBuyer function.

     async function handlePaymentMethodSubmission(
       event,
       paymentMethod,
       shouldVerify = false // SCA only needs to be run for Card Payments. All
       // other payment methods can be set to false.
     ) {
       // Add the following lines after the `tokenize` call
       let verificationToken;
       if (shouldVerify) {
         verificationToken = await verifyBuyer(
           payments,
           token
         );
       }
    
       console.debug('Verification Token:', verificationToken);
    
       //TODO: Add the verification token in Step 2.2
       const paymentResults = await createPayment(token);
       // handling the paymentResults.
     }
    

The full version of the handlePaymentMethodSubmission function should look like the following:

async function handlePaymentMethodSubmission(
  event,
  paymentMethod,
  shouldVerify = false
) {
  event.preventDefault();

  try {
    // disable the submit button as we await tokenization and make a payment
    // request.
    cardButton.disabled = true;
    const token = await tokenize(paymentMethod);
    let verificationToken;

    if (shouldVerify) {
      verificationToken = await verifyBuyer(
        payments,
        token
      );
    }

    console.debug('Verification Token:', verificationToken);

    //TODO: Add the verification token in Step 2.2
    const paymentResults = await createPayment(token);
    displayPaymentResults('SUCCESS');

    console.debug('Payment Success', paymentResults);
  } catch (e) {
    cardButton.disabled = false;
    displayPaymentResults('FAILURE');
    console.error(e.message);
  }
}

Test the application

  1. Navigate to http://localhost:3000/ in your browser.

  2. Get one of the test cards with a challenge type of “Modal with Verification Code” from the Sandbox Test Values.

After you submit, you see the following modal where you enter the verification code.

web-payments : sca : verify

When SCA has verified the buyer, the verification token is logged to the Developer Dashboard.

Step 2: Add the verification token to the payment details Permalink Get a link to this section

  1. Update the createPayment function to take the verificationToken parameter.

     // verificationToken can be undefined, as it does not apply to all payment
     // methods.
     async function createPayment(token, verificationToken) {
       const bodyParameters = {
         locationId,
         sourceId: token,
       };
    
       if (verificationToken !== undefined) {
         bodyParameters.verificationToken = verificationToken;
       }
    
       const body = JSON.stringify(bodyParameters);
    
       // Same as in the cards example.
       const paymentResponse = await fetch('/payment', {
         method: 'POST',
         headers: {
           'Content-Type': 'application/json',
         },
         body,
       });
    
       if (paymentResponse.ok) {
         return paymentResponse.json();
       }
    
       const errorBody = await paymentResponse.text();
       throw new Error(errorBody);
     }
    
  2. Add the verification token parameter to the createPayment function call in the DOMContentLoaded eventListener.

    //TODO: Add the verification token in Step 2.2
    const paymentResults = await createPayment(
       token,
       verificationToken  //new parameter
    );
    
  3. On your backend, modify your payment object to include a verificationToken. If you are using Square's example server, this is done for you as shown in the following code from index.js:

     const payment = {
       idempotencyKey,
       locationId: payload.locationId,
       sourceId: payload.sourceId,
       amountMoney: {
         amount: '100', // the expected amount is in cents ($1.00.)
         currency: 'USD',
       },
     };
    
     // VerificationDetails is part of Secure Card Authentication.
     // This part of the payload is highly recommended (and required for some
     // countries) for 'unauthenticated' payment methods like Cards.
    
     if (payload.verificationToken) {
       payment.verificationToken = payload.verificationToken;
     }
    
     const { result, statusCode } = await square.paymentsApi.createPayment(
       payment
     )
    

Test the application

  1. Navigate to http://localhost:3000/ in your browser.

  2. Choose the Pay $1.00 button.

You see the SCA modal window. The payment succeeds on successfully completing the challenge.

Related topics Permalink Get a link to this section