Charge a Card on File

Applies to: Web Payments SDK | Customers API

Learn how to charge a card on file with the Web Payments SDK.

Link to section

Overview

With Web Payments SDK integration, your application can charge a card on file in the following two payment flows for a card on file:

  • (Beta) A new default payment flow that involves:
    • Generating a payment token. During payment tokenization, Square checks the tokenize request to determine whether buyer verification is needed based on the buyer's information.
    • Including the payment token in a Payments API request call to process a payment.
  • The existing payment flow that involves:
    • Generating a verification token after verifying the buyer.
    • Including both the verification token and the card id of the stored card in a Payments API request call to process a payment.

Important

The new payment flow will replace the existing Web Payments SDK card payment acceptance implementation and become the new default card payment flow when Square releases it for General Availability.

When Square releases the new payment flow for General Availability, Square will deprecate the Payments.verifyBuyer() method that performs buyer verification and generates a verification token. Square will provide a migration guide so that you can update your application to take card payments with the new payment flow.

Square recommends updating your application to use the new default payment flow with the Web Payments SDK. However, during Beta, Square will continue to support both payment flows.

Link to section

Card-on-file payment flows

Choose one of the following card-on-file payment flows to set up your application to charge a card on file with Web Payments SDK integration.

Link to section

Set up the new charge card-on-file payment flow

Before updating your application with the CHARGE intent, make sure to update your application to support the new payment flow by following the instructions in Take a Card Payment.

In your application:

  1. Initialize a Card object.

  2. Call Card.tokenize() with the verificationDetails and cardId of the stored card.

  3. Call CreatePayment with the token as the sourceId.

    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.

    Important

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

    The following code example demonstrates the charge card on file setup.