Charge a Card on File

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.

   
   async function createPaymentWithCardOnFile(
        token,
        customerId,
      ) {
        const body = JSON.stringify({
          locationId,
          sourceId: token,
          customerId,
          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);
      }
   
      // status is either SUCCESS or FAILURE;
      function displayPaymentResults(status) {
        const statusContainer = document.getElementById(
          'payment-status-container',
        );
        if (status === 'SUCCESS') {
          statusContainer.classList.remove('is-failure');
          statusContainer.classList.add('is-success');
        } else {
          statusContainer.classList.remove('is-success');
          statusContainer.classList.add('is-failure');
        }
   
        statusContainer.style.visibility = 'visible';
      }
   
      async function tokenize(paymentMethod, sourceId) {
        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, sourceId);
        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);
        }
      }
   
      document.addEventListener('DOMContentLoaded', async function () {
        if (!window.Square) {
          throw new Error('Square.js failed to load properly');
        }
   
        let payments;
        try {
          payments = window.Square.payments(appId, locationId);
        } catch {
          const statusContainer = document.getElementById(
            'payment-status-container',
          );
          statusContainer.className = 'missing-credentials';
          statusContainer.style.visibility = 'visible';
          return;
        }
   
        let card;
        try {
          card = await payments.card();
        } catch (e) {
          console.error('Initializing Card failed', e);
          return;
        }
   
        async function handleChargeCardOnFileSubmission(
          event,
          card,
          cardId,
          customerId,
        ) {
          event.preventDefault();
   
          try {
            // disable the submit button as we await tokenization and make a payment request.
            cardButton.disabled = true;
   
            const token = await tokenize(card, cardId);
            const paymentResults = await createPaymentWithCardOnFile(
              token,
              customerId
            );
   
            displayPaymentResults('SUCCESS');
            console.debug('Payment Success', paymentResults);
          } catch (e) {
            cardButton.disabled = false;
            displayPaymentResults('FAILURE');
            console.error(e.message);
          }
        }
   
        const cardButton = document.getElementById('card-button');
        cardButton.addEventListener('click', async function (event) {
          const customerTextInput = document.getElementById('customer-input');
          const cardTextInput = document.getElementById('card-input');
   
          if (
            !customerTextInput.reportValidity() ||
            !cardTextInput.reportValidity()
          ) {
            return;
          }
   
          const cardId = cardTextInput.value;
          const customerId = customerTextInput.value;
          handleChargeCardOnFileSubmission(event, card, cardId, customerId);
        });
      });