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 haven't 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.

Link to section

Implement the functionality to store a card on file

Link to section

Step 1: Update the form

  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.

<body> <form id="payment-form"> <input id="customer-input" type="text" aria-required="true" aria-label="Customer ID" required="required" placeholder="Customer ID" name="customerId" /> <div id="card-container" style="margin-top: 0"></div> <button id="card-button" type="button">Store Card</button> </form> <div id="payment-status-container" class="store-card-message"></div> </body>
Link to section

Step 2: Update the event handler to accept the customer ID

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.

const cardButton = document.getElementById(`card-button`); cardButton.addEventListener('click', async function (event) { const textInput = document.getElementById('customer-input'); if (!textInput.reportValidity()) { return; } const customerId = textInput.value; // Add the `handleStoreCardMethodSubmission` method. handleStoreCardMethodSubmission(event, card, customerId); }
Link to section

Step 3: Add the card on file method

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.

Link to section

Step 4: Update the card on file submission method

  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:

Link to section

Step 5: Test the add card to file functionality

  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 don't 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.

    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.

Link to section

Add Strong Customer Authentication


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.

  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.


    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.

  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":

      BrandNumberCVVChallenge 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
      Mastercard5248 4800 0021 0026111Modal with
      Verification Code
      Mastercard EU5500 0000 0020 1016111Modal with
      Verification Code
      American Express EU3700 000002 010141111Modal with
      Verification Code
      Visa4811 1100 0000 0008111No Challenge with
      Failed Verification

    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.