Charge a Card on File with SCA

Applies to: Web Payments SDK | Customers API

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

Link to section


You can add code to the application you created (with a card payment) from the quickstart project sample, as documented in Web Payments SDK Quickstart. 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.

Did you know?

Custom risk score-based SCA authentication private beta

If the seller has set up custom score rules and logic in Risk Manager, you can also trigger SCA authentication based on the custom risk score by passing the custom risk score value in the verifyBuyer() method call with the customScore field. To try out this feature, contact your Square representative.

Link to section

Implement charging a card on file with SCA

Link to section

1: Update the payment form

The form inputs take the customer ID and card ID associated with a customer.

Link to section

2: Update the event handler to accept IDs


All subsequent steps make revisions to the code inside the <script> tag.

Update the cardButton.addEventListener callback method with the following code.

The event listener validates the text from the input form field and stores the IDs in variables. The handlePaymentWithCardOnFileMethodSubmission method is called with the customer ID and card ID.

Link to section

3: Add the payment method

Add the following code after the appId and locationId global constants:

Link to section

4: Update the submission method

Replace the handlePaymentMethodSubmission function call with handlePaymentWithCardOnFileMethodSubmission using customer ID and card ID arguments.

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

Link to section

5: Test the payment functionality

  1. Navigate to http://localhost:3000/ in your browser. The browser loads the form with the customer ID input field, card ID field, and the Pay $1.00 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, enter the ccof:customer-card-id-ok test card ID, and choose Pay $1.00.

    Did you know?

    The cardId generated from using a Sandbox credit card works in the Square Sandbox environment.

  5. Verify that the application made a successful payment request. In the Developer Dashboard, open the application that you're testing and choose API Logs in the left pane.

Link to section

6. 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 createPaymentWithCardOnFile method to include the verificationToken parameter.

  2. Define the verifyBuyer 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's 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 parameter argument that you pass to verifyBuyer is for card verification. After you pass in the argument, the verifyBuyer function creates a ChargeVerifyBuyerDetails object that verifies the buyer's card on file to be charged and provides 3DS with information about the buyer and the purchase details.

  3. Call the verifyBuyer function in the submission method.

  4. Test the application.

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

    • Enter the card ID ccof:customer-card-id-requires-verification on the form. When the modal window prompt displays, enter 123456.

      Did you know?

      The cardId generated from using a Sandbox SCA credit card works in the Square Sandbox environment.

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