Set Up Virtual Card on the Web

Prerequisites

• Review About Affirm Virtual Card.

Steps

1. Add Affirm.js

Add the Affirm.js script to the on your site. The script loads directly from the Affirm domain.

🚧

Sandbox API Keys

Use only your sandbox API keys and domain during testing and development. This ensures that you don't accidentally modify live transactions.

<script>
var _affirm_config = {
		public_api_key: "YOUR_PUBLIC_API_KEY", /* replace with public api key */
		script: "https://cdn1-sandbox.affirm.com/js/v2/affirm.js",
		locale: "en_US",
		country_code: "USA",
	};

(function(m,g,n,d,a,e,h,c){var b=m[n]||{},k=document.createElement(e),p=document.getElementsByTagName(e)[0],l=function(a,b,c){return function(){a[b]._.push([c,arguments])}};b[d]=l(b,d,"set");var f=b[d];b[a]={};b[a]._=[];f._=[];b._=[];b[a][h]=l(b,a,h);b[c]=function(){b._.push([h,arguments])};a=0;for(c="set add save post open empty reset on off trigger ready setProduct".split(" ");a<c.length;a++)f[c[a]]=l(b,d,c[a]);a=0;for(c=["get","token","url","items"];a<c.length;a++)f[c[a]]=function(){};k.async=
  !0;k.src=g[e];p.parentNode.insertBefore(k,p);delete g[e];f(g);m[n]=b})(window,_affirm_config,"affirm","checkout","ui","script","ready","jsReady");
</script>

Adding the script to your site creates a defined instance of Affirm on your client, enabling you to access methods in the Affirm object to trigger multiple actions.

Note: Affirm does not generate real virtual cards in the sandbox environment. Please work with your technical account manager on live testing.

2. Create the Checkout Object

When a customer chooses Affirm to pay for a purchase, a checkout object containing the order details should be created with affirm.checkout() so that Affirm can render the checkout flow. See below for a sample checkout object:

affirm.checkout({ 
   "merchant":{ 
      "name":"Your Customer-Facing Merchant Name",
      "use_vcn": true
   },
   "shipping":{ 
      "name":{ 
         "first":"Joe",
         "last":"Doe"
      },
      "address":{ 
         "line1":"633 Folsom St",
         "line2":"Floor 7",
         "city":"San Francisco",
         "state":"CA",
         "zipcode":"94107",
         "country":"USA"
      },
      "phone_number":"4153334567",
      "email":"[email protected]"
   },
   "billing":{ 
      "name":{ 
         "first":"Joe",
         "last":"Doe"
      },
      "address":{ 
         "line1":"633 Folsom St",
         "line2":"Floor 7",
         "city":"San Francisco",
         "state":"CA",
         "zipcode":"94107",
         "country":"USA"
      },
      "phone_number":"4153334567",
      "email":"[email protected]"
   },
   "items":[ 
      { 
         "display_name":"Awesome Pants",
         "sku":"ABC-123",
         "unit_price":1999,
         "qty":3,
         "item_image_url":"http://merchantsite.com/images/awesome-pants.jpg",
         "item_url":"http://merchantsite.com/products/awesome-pants.html"
      }
   ],
   "order_id":"JKLMO4321",   
   "metadata": {
       "mode": "modal"
     },
   "shipping_amount":1000,
   "tax_amount":500,
   "total":5997
});

📘

Note:

• Virtual Card only supports modal mode. The Affirm checkout opens in a modal pop-up window over your checkout page. This is indicated in the checkout object when setting the mode parameter to modal.
• Set the use_vcn parameter to true to enable card details to be generated on loan origination.
• affirm.checkout() validates the required data in the checkout object.

3. Launch Checkout and Handle Callbacks

Launch the Affirm checkout modal using the affirm.checkout.open_vcn() function. When the customer confirms their Affirm loan, we send a JavaScript callback on success or on error, depending on the outcome. After a successful checkout, you retrieve the card details and checkout_id from the callback. See the affirm.checkout.open_vcn() template:

affirm.checkout.open_vcn({
      success: function(card_response) {
         console.log(card_response);
         //add logic on handling the returned client-side card details and/or checkout token here
      },
      error: function(error_response) {
        console.log(error_response);
        //add logic on handling a declination or abandoned checkout here. We recommend redirecting users to the payment selection screen to choose an alternative payment method.
      },
      checkout_data: data
});

4. Card Management

You can submit authorizations, captures, and refunds to the Virtual Card using your existing payment rails.

You can also retrieve card details from your server using our Read Card API endpoint and the associated checkout_id.

🚧

Retrieve Card Details

If you don't want to retrieve the card details from the client-side, we can always pass them back via the server-side only (for PCI reasons). Please contact Affirm through [email protected] for further information.

FAQ

🚩

Resolving "affirm.checkout.open_vcn is not a function" Error in VCN Integration

Q: How do I fix the error "affirm.checkout.open_vcn is not a function" when using Affirm's checkout methods?

A: This error typically occurs when the Affirm script hasn't fully loaded before the checkout and open_vcn methods are called. To resolve this, wrap the Affirm checkout and open_vcn method calls within the affirm.ui.ready method. Below is a solution that has assisted multiple merchants:

JavaScript

affirm.ui.ready(function() {
  affirm.checkout(checkoutObj);
  affirm.checkout.open_vcn({
      success: function(card_checkout) {
          //On successful loan confirmation Affirm will trigger this function
          //This function will be used to pass CC number to your CC processor
          //You will need to handle redirecting to a success page here as well
          console.log(card_checkout);
      },
      error: function(error_response) {
          //On Cancel or decline Affirm will trigger the following function
          //You will need to handle redirecting to an error page here
          console.log(error_response);
      }
  });
});

In this solution, the success function is used for processing successful loan confirmations, including passing credit card details to your processor and redirecting to a success page. The error function handles cancellations or declines by redirecting to an error page. This workaround ensures that Affirm's methods are only called after the script is fully loaded, effectively preventing the error.

What's Next?

• Promotional Messaging and Prequalification
• Set Up Virtual Card for Android
• Set Up Virtual Card for iOS