Learn about adding a card on file with Strong Customer Authentication (SCA).
Web Payments SDK

Store a Card on File with SCA

Learn how to store a card on file with SCA (Strong Customer Authentication) to your application.

The steps in this topic add code to the application you created (with a card payment) from the Quickstart project sample, as documented in Take a Card Payment with the Web Payments SDK. If you have not created an application using the Quickstart, you need to do so before completing the following steps.

You can see a complete code example in the Web Payments Quickstart on GitHub.

  1. In the body tag, update the payment form input field for the customer ID.

  2. Add "Store Card" to the button tag, so the form can extract the customer ID into a variable.

The form input takes the customer ID of the customer associated with the card on file.

Inside the <script> tag, update the cardButton.addEventListener callback method with the following code.

The card button event listener validates the text from the input form field and then stores the customer ID in a variable. The handleStoreCardMethodSubmission method is called with the customer ID.

Add the following code after the initializeCard function.

The storeCard function replaces the createPayment function in your code and creates the card on file associated with the customer ID.

  1. Inside the <script> tag, rename the handlePaymentMethodSubmission function to handleStoreCardMethodSubmission after the let card object declaration and add the customer ID parameter.

    The handleStoreCardMethodSubmission method receives information about the card on file payment event with the customer ID.

  2. In the try statement, replace the paymentResults object with the storeCardResults method.

    The storeCardResults method takes the card's token and customer ID. The updated event handler code looks like the following example in the document.addEventListener object:

  1. Navigate to http://localhost:3000/ in your browser. The browser loads the form with the customer ID input field, credit card input field, and the Store Card button.

  2. In another browser tab, log in to your Square developer account and access API Explorer in your Sandbox environment.

  3. Get the customer ID from a customer profile. If you do not have a customer profile for testing, use the CreateCustomer endpoint of the Customers API to create a new test customer profile in API Explorer.

  4. On the form, enter the customer ID, any card number from the following table (any CVV or postal code works), and choose Store Card.

    BrandNumberCVV
    Visa4111 1111 1111 1111111
    Mastercard5105 1051 0510 5100111
    Discover6011 0000 0000 0004111
    Diners Club3000 000000 0004111
    JCB3569 9900 1009 5841111
    American Express3400 000000 000091111
    China UnionPay6222 9888 1234 0000123
  5. Verify that the application successfully stored the customer ID and credit card on file. In the Developer Dashboard, open the application, and choose API Logs in the left pane.

Important

Your application should always attempt to create a payment with a verification token when a token is returned. It should also be prepared to respond to a payment failure in a small number of cases where a payment is rejected despite receiving a buyer verification token.

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

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    • 25
    • 26
    • 27
        // verificationToken can be undefined, as it does not apply to all payment
        // methods.
        async function storeCard(token, verificationToken) {
          const bodyParameters = {
            locationId,
            sourceId: token,
            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. Define the verifyBuyer function with billing contact details after the displayResults function.

    Your production application should collect the billing address of the buyer. Although providing an empty billingContact is acceptable, by providing as much billing contact information as possible, you increase the chances of a successful authentication. This example uses an object that is declared with a hard-coded billing address. Your application might collect a billing address at payment time or, if the buyer is a customer on the seller Square account, from the buyer's customer record.

    Note

    The Web Payments SDK produces a payment token that can be used to make a payment with the presented card or to store the card on file. These operations are represented by two intents: CHARGE to make a payment and STORE to store the card.

    The code in the following steps adds the billing contact values needed by SCA (with the payments.verifyBuyer function) to verify the authenticity of the card holder.

    The verifyBuyer function creates a StoreVerifyBuyerDetails object that verifies a card to be stored on file and provides the buyer and purchase details needed by 3DS.

  3. Add the verifyBuyer function to the handleStoreCardMethodSubmission function and update the storeCard method call to include verificationToken.

    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    • 25
    • 26
    • 27
    • 28
    async function handleStoreCardMethodSubmission(
      event,
      paymentMethod,
      customerId
    ) {
      event.preventDefault();
    
      try {
        // disable the submit button as we await tokenization and make a payment request.
        cardButton.disabled = true;
        const token = await tokenize(paymentMethod);
        // Add verifyBuyer.
        let verificationToken = await verifyBuyer(payments, token);
        // Add verificationToken.
        const storeCardResults = await storeCard(
          token,
          customerId,
          verificationToken
        );
    
        displayResults('SUCCESS');
        console.debug('Store Card Success', storeCardResults);
      } catch (e) {
        cardButton.disabled = false;
        displayResults('FAILURE');
        console.error('Store Card Failure', e);
      }
    }
    
  4. Test the application.

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

    2. Use one of the test cards in the following table with a challenge type of “Modal with Verification Code":

      Brand
      Number
      CVVChallenge typeVerification code
      Visa4800 0000 0000 0004111No ChallengeN/A
      Mastercard5222 2200 0000 0005111No ChallengeN/A
      Discover EU6011 0000 0020 1016111No Challenge123456
      Visa EU4310 0000 0020 1019111Modal with
      Verification Code
      123456
      Mastercard5248 4800 0021 0026111Modal with
      Verification Code
      123456
      Mastercard EU5500 0000 0020 1016111Modal with
      Verification Code
      123456
      American Express EU3700 000002 010141111Modal with
      Verification Code
      123456
      Mastercard5333 3300 0000 0008111Modal with Multiple Verification QuestionsChallenge 1: Thomason
      Challenge 2: Select both St Louis & Dallas
      Challenge 3. Smith
      Visa4811 1100 0000 0008111No Challenge with
      Failed Verification
      N/A

    After you submit, you see the following window where you enter the verification code:

    A graphic showing the SCA cardholder authentication window that appears when the verifyBuyer function is called.

  5. Verify that the application passed in the verification token with a successful response. Check the application's API log again in your developer account.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.