Take a Card Payment with the Web Payments SDK

The Web Payments SDK provides secure payment methods and Strong Customer Authentication (SCA) regulatory compliance so that your application authorizes and processes card payments.

To simplify the operation of authorizing payments, verifying buyer identity, and processing card payments, you can implement the new payment flow. Using this flow, an application calls the Web Payments SDK Card.tokenize() method and exchanges all necessary information about the buyer in the tokenization request so Square can handle all the authentication before returning a payment token. This payment flow allows Square to process the payment and comply with any applicable local regulations or to comply with the seller's preference to trigger 3D Secure (3DS) authentication based on rules that the seller sets in Square Risk Manager.

The payment flow uses additional fields in tokenize() to allow Square to perform payment authentication, which involves:

1. Running a buyer risk evaluation.

2. Determining whether a payment will be authenticated with 3DS.

   Square authenticates a payment for two reasons:

   • Regulatory mandate - Square determines whether the payment is in scope of a mandate and routes the payment through 3DS as needed.
   • Seller choice - A seller sets a rule in Risk Manager for when 3DS is triggered for a payment. For more information, see Square Risk Manager seller documentation for 3DS.

3. Applying 3DS if needed per authentication regulations.

4. Tokenizing the card payment so that the Web Payments SDK returns a payment token to the application with the buyer's identity verified and authentication completed (if authentication is required by a regulatory mandate or the seller's Risk Manager risk rule).

With this authentication flow, you no longer need the application to call Payments.verifyBuyer() and handle a verification token. The benefit of this authentication flow is that it provides all the buyer verification functionality from calling Card.tokenize() and CreatePayment or CreateCard with a payment token.

After getting a payment token, the application calls CreatePayment to process and complete the payment.

Modify your application so it can incorporate the new payment flow for authentication with the Card.tokenize() method. Your application should then perform fewer operations to authenticate buyers for card payments without calling Payments.verifyBuyer().

• Web Payments SDK integration
• Card payment method support

In your application, modify the token and payment objects prior to calling Card.tokenize() and CreatePayment, respectively.

Along with the card payment method object, the tokenize() method passes the following additional properties:

• billingContact - The buyer's contact information for billing.

• intent - The transactional intent of the payment.

• sellerKeyedIn - Whether the seller keyed in payment details.

• customerInitiated - Whether the customer initiated the payment.

• total - The total amount of the card payment.

  Important

  Provide as much buyer information as possible for billingContact so that you get more accurate decline rate performance from 3DS authentication.

  The Payment object passes the token object that contains the aforementioned values.

   const token = await tokenize(
     card,
     billingContact,
     intent: CHARGE,
     sellerKeyedIn: FALSE,
     customerInitiated: TRUE,
     total
   );
  
   const payment = createPayment(token);

  If your application makes calls with verifyBuyer() and uses a verification token (as part of the Web Payments SDK card payment method setup to add SCA), complete the next two steps.

1. Move the buyer verification test values to the token object.

   If your application makes calls with verifyBuyer(), you can move the test values declared in the verificationDetails object to the tokenize() method of the token object and modify the parameter values. The following code examples show a set of test values:

   Before moving the test values

    const token = await tokenize(card);
   
    async function verifyBuyer(payments, token) {
      const verificationDetails = {
        amount: '1.00',
        billingContact: {
          givenName: 'John',
          familyName: 'Doe',
          email: '[email protected]',
          phone: '3214563987',
          addressLines: ['123 Main Street', 'Apartment 1'],
          city: 'London',
          state: 'LND',
          countryCode: 'GB',
        },
        currencyCode: 'GBP',
        intent: 'CHARGE',
      };
   
    const payment(token, verificationDetails);

   After moving and modifying the test values

    const token = await tokenize(
      card,
      billingContact: {
        givenName: 'John',
        familyName: 'Doe',
        email: '[email protected]',
        phone: '3214563987',
        addressLines: ['123 Main Street', 'Apartment 1'],
        city: 'London',
        state: 'LND',
        countryCode: 'GB',
      },
      intent: 'CHARGE',
      sellerKeyedIn: 'FALSE',
      customerInitiated: 'TRUE',
      total: {
        amount: '1000',
        currencyCode: 'GBP'
      }
    );
   
    const payment = createPayment(token);

2. Remove instances of the verificationToken object and verifyBuyer() method calls.

   If you have set up the card payment method with the Web Payments SDK, the following code example shows the handlePaymentMethodSubmission method that calls tokenize() with the token object:

   async function handlePaymentMethodSubmission(event, card) {
     event.preventDefault();
   
     try {
       // disable the submit button as we await tokenization and make a payment request.
       cardButton.disabled = true;
       const token = await tokenize(
         card,
         billingContact,
         intent: CHARGE,
         sellerKeyedIn: FALSE,
         customerInitiated: TRUE,
         total
       );
       const paymentResults = await createPayment(token);
       displayPaymentResults('SUCCESS');
       console.debug('Payment Success', paymentResults);
     } catch (e) {
       cardButton.disabled = false;
       displayPaymentResults('FAILURE');
       console.error(e.message);
     }
   }

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

2. Complete the card payment form and submit a test payment with a CNP test credit card from Sandbox Payments.

   For this step, test with two cards: a test card that invokes an SCA challenge and a test card that doesn't.

   1. Use an SCA test card with a challenge type of “Modal with Verification Code".

      The following modal launches:

      

   2. Choose Authenticate. After authentication, the application sends the payment request to complete the card payment.

   3. Check the console log in your browser or the returned TokenResult object to confirm that the payment token is generated.

   4. Refresh your browser and use a test card from the Card-not-present success state values table or an SCA test card with no challenge.

   5. Check the console log again in your browser or the returned TokenResult object to confirm that the payment token is generated.

After testing the application to take a card payment, you can update the application to authorize buyers for card-on-file payments. The tokenize() method includes the intent key where you can update the value to CHARGE_AND_STORE. When your application charges and stores a card on file, the application should call CreateCard to create a new Card object when the application sends the buyer authentication and payment requests to Square. For more information, see Charge and Store a Card on File with SCA.

The payment flow includes the following tokenize() method fields that allow Square to handle buyer verification and authentication.

 total: {
    amount: 1000,
    currentCode: 'GBP'
 }

 billingContact: {
    addressLines: ['123 Main Street', 'Apartment 1'],
    familyName: 'Doe',
    givenName: 'John',
    email: '[email protected]',
    countryCode: 'GB',
    phone: '3214563987',
    state: 'LND',
    city: 'London',
    postalCode: 'WC2N 5DU'
 }