Card on file

The "Card on file" functionality allows users to save credit card information for future use instead of repeatedly entering their credit card information.

Cards can be stored during each of the following flows:

Charge flow
From a client card
During checkout

Saving card during a charge flow

Client consent

For the payment gateway application to determine whether the user chose to save the card, the iFrame should listen to the following postMessage that indicates whether the “Client has consented to save this card on file” checkbox is checked or unchecked.

Code snippet for listening to save card checkbox events

window.addEventListener(
        'message',
        (event) => {
          // Save card checked/unchecked event
          if (event.data.type === 'generic' && event.data.func === 'setSaveCard') {
            const saveCard = event.data.params.checked.checked; // boolean
            return;
          }
        })

Charge event

Once the user clicks the Charge button, we will start the process of saving the card, and once done, the Charge will continue as described under the Charge section.

At that point, you want to save the payment details along with the credit card information, and make sure you can reference the credit card information based on the "charge token" - the token you provided via the JavaScript postMessage.

Note that this time, the postMessage emitted when the Charge CTA is clicked will indicate that "save_card: true":

{
  type: 'generic', 
  func: 'getToken', 
  params: {
    amount: number,
    save_card: true,
    pivot_id: string,
    client_id: string,
    currency: string
  } 
}

Also, when save_card is true, you'll need to pass a cardholder_name in the postMessage in addition to the token you'd pass in a charge flow.

window.addEventListener(
        'message',
        (event) => {
           if (event.data.type === 'generic' && event.data.func === 'getToken') {
            // Do some credit card number validations
            const cardValidationErrors = validateCard(); // Can be a function that returns an array of errors
            // if card validations checks error
            if (cardValidationErrors.length > 0) {
              const messageObj = {
                type: 'generic',
                func: 'validationFailure'
              }
              window.parent.postMessage(messageObj, '*')
              // present the errors in the iFrame
              return;
              // If the card checks correctly with no issues
            } else {
              const token = {TOKEN}
              const messageObj = {
                type: 'generic',
                token: {TOKEN}
              }
              // Add cardholder_name is save_card === true
              if (event.data.params.save_card) {
                messageObj['cardholder_name'] = this.cardHolderName;
              }
              window.parent.postMessage(messageObj, '*');
              // Store token and payment details in your database for later reference
              return;
            }
          }
        }
      )

POST /customer

inTandem will send a POST request to {redirect_uri}/customer the first time you're attempting to save a card for a given client. The response should be the client's customer_id.

Following card-on-file attempts for that same client will not trigger another request to /customer.

Request

POST {redirect_uri}/customer

Request body payload

client_id: "jwlubzof7xahdazo"
email: "[email protected]"
name: "first name last name"

Expected response

{customer_id: {CUSTOMER_ID_VALUE}}

📘
customer_id
The customer ID is a unique identifier assigned to a customer by the payment gateway. This identifier is used to represent the customer in the payment gateway's system and is typically used for managing and processing payments, subscriptions, and storing payment information securely.

POST /customer/:token/attach

Next, inTandem will send another POST request to {redirect_uri}/customer/:token/attach.
The "token" param will correspond to the token you initially provided in the Charge event.

POST {redirect_uri}/customer/:token/attach

Request payload:

{
	"customer_id": string
}

Expected response:

{
    "card": {
        "card_id": "addtkthQ16trAsldSar50v6sLfdmuQ", // card identifier provided by the payment gateway
        "card_info": {
            "card_brand": "visa",
            "last_4": 1217,
            "exp_month": 10,
            "exp_year": 2030,
            "cardholder_name": "John Doe"
        }
    },
    "customer_id": "49v0ud9YhquOoYTczn0PkwdRn9QRb7"
}

That's it. At that point, the card is saved and will appear as an optional payment option for future payments.

Saving card on file from the client card

Saving a card on file from the client card is identical to how you save a card on the Charge flow. On both, inTandem will embed the Payment Processing Page from {redirect_uri}/charge, emit the getToken postMessage when the ADD CTA is clicked (and expecting a following postMessage with a token), followed by a POST request to {redirect_uri}/charge/:token/attach.

For the payment processing page to differentiate between the two flows, when inTandem loads the payment processing page on the client card page, we'll append a query param to the iFrame URL indicating that this is a save-card-only operation and not a charge flow.

{redirect_uri}/charge?save_card=true&pivot_id=BUSINESS_UID

Delete saved cards

Removing saved cards is done by inTandem sending a request to:

POST {api_uri}/customer/:token/detach

Request payload

{
    "customer_id": "49v0ud9YhquOoYTczn0PkwdRn9QRb7"
}

Expected response:

{
    "customer_id": "49v0ud9YhquOoYTczn0PkwdRn9QRb7"
}

Saving card-on-file on checkout

Get payment information from inTandem (make sure that “allow_save_card” is true). If allow_save_card is false, either the client already has 3 cards saved, or the “checkout_vaulting” feature flag is missing for that account.

Saving cards on checkout is done in two steps:

Make sure that the save card feature is available at the account level.
When sending the GET request to /checkout/:url_key as part of the usual checkout flow, make sure that the value of the “allow_save_card” property is true.

GET /checkout/:url_key body request:

{
    "status": "OK",
    "data": {
        "amount": "33.0",
        "currency": "USD",
        "name": "John Doe",
        "return_url": "https://clients.meet2know.com/portal/5e3c760d?fromCheckout=true#/loader",
        "email": "[email protected]",
        "client_id": "zlbsfegs493u9zmo",
        "invoice_id": null,
        "allow_save_card": true
    }
}

If “allow_save_card” is true, you can proceed with the checkout flow by appending the customer id and the card information when sending the payment checkout update request.

PUT https://api.vcita.biz/platform/v1/payment/checkout/ body request:

{
   "url_key": "ijGghOYFKTFClDWJQZSNzkaZDZNQOiksktubFXpXfWmdovxuSz",
   "card":{
       "card_id": "15dsanida54",
       "card_info": {
           "exp_month": "01",
           "exp_year": "2025",
           "last_4": "6666",
           "card_brand": "visa",
           "cardholder_name": "John Doe"
           }
   },
   "customer_id": "49v0ud9YhquOoYTczn0PkwdRn9QRb7",
   "created": "2020-11-26",
   "transaction_id": "12qw34rt56yu",
   "type": "checkout.session.completed"
}

Expected response:

{
    "status": "OK",
    "data": {}
}

Saving card during a charge flow

Client consent

Code snippet for listening to save card checkbox events

Charge event

POST /customer

Request

Expected response

📘customer_id

POST /customer/:token/attach

POST {redirect_uri}/customer/:token/attach

Request payload:

Expected response:

Saving card on file from the client card

Delete saved cards

Saving card-on-file on checkout

📘
customer_id