Applies to: Web Payments SDK | Cards API | Customers API
Learn how to store a card on file with the Web Payments SDK.
With Web Payments SDK integration, your application can store 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 Cards API call to store a card on file with CreateCard.
- The existing payment flow that involves:
- Generating a payment token.
- Generating a verification token after verifying the buyer.
- Including both the payment token and verification token in a Cards API call to store a card on file with CreateCard.
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.
Choose one of the following card-on-file payment flows to set up your application to store a card on file with Web Payments SDK integration.
Before updating your application with the STORE
intent, make sure to update your application to support the new payment flow by following the instructions in Take a Card Payment with the Web Payments SDK.
In your application, replace the
createPayment
method with a new method calledstoreCard
, pass thetoken
andcustomerId
objects as arguments, and add the following values from the code example:async function storeCard(token, customerId) { const body = JSON.stringify({ locationId, sourceId: token, customerId, idempotencyKey: window.crypto.randomUUID(), }); const paymentResponse = await fetch('/card', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body, }); if (paymentResponse.ok) { return paymentResponse.json(); } const errorBody = await paymentResponse.text(); throw new Error(errorBody); }Modify the tokenize method with the following updates to
verificationDetails
. Make sure to setintent
toSTORE
. ThecustomerInitiated: true
andsellerKeyedIn: false
properties are not required.async function tokenize(paymentMethod) { const verificationDetails = { billingContact: { givenName: 'John', familyName: 'Doe', email: '[email protected]', phone: '3214563987', addressLines: ['123 Main Street', 'Apartment 1'], city: 'London', state: 'LND', countryCode: 'GB', }, intent: 'STORE', customerInitiated: true, sellerKeyedIn: false, }; const tokenResult = await paymentMethod.tokenize(verificationDetails); if (tokenResult.status === 'OK') { return tokenResult.token; } else { throw new Error( `Tokenization errors: ${JSON.stringify(tokenResult.errors)}`, ); } }Replace the
handlePaymentMethodSubmission
method with a new method calledhandleStoreCardSubmission
, pass theevent
,card
andcustomerId
arguments to the method, and modify the followingtry
statement declaration from the code example:async function handleStoreCardSubmission(event, card, 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); const storeCardResults = await storeCard( token, customerId, ); displayResults('SUCCESS'); console.debug('Store Card Success', storeCardResults); } catch (e) { cardButton.disabled = false; displayResults('FAILURE'); console.error('Store Card Failure', e); } }In the
cardButton.addEventListener
event listener, declare a newcustomerId
object and call thehandleStoreCardSubmission
method as indicated in the following code example: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; handleStoreCardSubmission(event, card, customerId); });