Take a Card Payment

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, initialize a Card object. Modify the token and payment objects prior to calling Card.tokenize() and CreatePayment, respectively.

The Card.tokenize() method passes the following properties in a verificationDetails object:

• amount - The amount of the card payment to be charged.
• billingContact - The buyer's contact information for billing.
• intent - The transactional intent of the payment.
• sellerKeyedIn - Indicates that the seller keyed in payment details on behalf of the customer. This is used to flag a payment as Mail Order / Telephone Order (MOTO).
• customerInitiated - Indicates whether the customer initiated the payment.
• currencyCode - The three-letter ISO 4217 currency code.

1. Declare a verificationDetails object and add the parameters to the object body in JSON format.
2. Declare a token object and include the await parameter with the Card.tokenize() method, which takes the verificationDetails object as an argument.
3. Declare a payment object, which calls createPayment and takes the token object as an argument.

The following code example demonstrates the payment flow setup.

const verificationDetails = { 
  amount: '10.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',
  customerInitiated: true,
  sellerKeyedIn: false,
};

const token = await card.tokenize(verificationDetails)

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.

Card tokenization now takes in a verificationDetails object. If your application currently creates the verificationDetails object for use with verifyBuyer(), you must move the verificationDetails properties to the tokenize() method. Square will be deprecating verifyBuyer() and the verification token, which won't automatically be included in the card tokenization request.

The following procedure describes how to modify the existing payment test flow:

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

   async function tokenize(paymentMethod) {
     const tokenResult = await paymentMethod.tokenize();
     // ...
   }
   
   async function verifyBuyer(payments, token) {
     const verificationDetails = {
       amount: '10.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 verificationResults = await payments.verifyBuyer(
       token,
       verificationDetails
     );
     return verificationResults.token;
   }

   After moving and modifying the test values

    async function tokenize(paymentMethod) {
     const verificationDetails = {
       amount: '10.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',
       customerInitiated: true,
       sellerKeyedIn: false,
     };
     const tokenResult = await    paymentMethod.tokenize(verificationDetails);
     if (tokenResult.status === 'OK') {
       return tokenResult.token;
     } else {
       let errorMessage = `Tokenization failed with status: ${tokenResult.status}`;
       if (tokenResult.errors) {
         errorMessage += ` and errors: ${JSON.stringify(
           tokenResult.errors,
         )}`;
       }
       throw new Error(errorMessage);
     }
   }

   Make sure to add and set the customerInitiated and sellerKeyedIn fields.

2. Update createPayment to take only the token as an argument.

   async function createPayment(token) {
     const body = JSON.stringify({
       locationId,
       sourceId: token,
       idempotencyKey: window.crypto.randomUUID(),
     });
     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);
   }

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

   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);
       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. Enter the verification code in the pop-up window and 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.

 amount: '1.00'

 currencyCode: 'GBP'

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