Virtual card on the web

Starting a payment with Affirm on the web with a virtual card consists of creating a checkout form, tokenizing customer information securely, and generating a virtual card. You can then process the card through your existing payment gateway.

This guide shows you how to include Affirm.js and Affirm Checkout on your web page to create an Affirm virtual card.

Step 1: Set up Affirm.js

Include the following script in the head section on every page on your site. This script should always be loaded directly from the Affirm domain.

⚠

️

Use only your sandbox API keys and domain for testing and development. This ensures that you don't accidentally modify your live transactions. Note that Affirm does not generate real virtual cards in the sandbox environment. If applicable, please work with your technical account manager on live testing.

<script>
 _affirm_config = {
   public_api_key:  "YOUR_PUBLIC_KEY",
   script:          "https://cdn1-sandbox.affirm.com/js/v2/affirm.js",
   locale:          "fr_CA",
   country_code:    "CAN",
 };
(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>

Once you include the script above, a defined instance of Affirm will be created on your client. You will gain access to methods within the Affirm object to trigger multiple actions.

Step 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:

{ 
   "merchant":{ 
      "user_confirmation_url":"https://merchantsite.com/confirm",
      "user_cancel_url":"https://merchantsite.com/cancel",
      "public_api_key": "{YOUR PUBLIC_API_KEY}",
      "name":"Your Customer-Facing Merchant Name",
      "use_vcn": true
   },
   "shipping":{ 
      "name":{ 
         "first":"Joe",
         "last":"Doe"
      },
    "address": {
      "street1": "4519 Rue Levy",
      "street2": "Apt 1",
      "city": "Saint-Laurent",
      "region1_code": "QC",
      "postal_code": "H4R2P9",
      "country": "CAN"
    },
      "phone_number": "250-555-0199",
    "email": "[email protected]",
     },
   "billing":{ 
      "name":{ 
         "first":"Joe",
         "last":"Doe"
      },
     "billing_address": {
      "street1": "4519 Rue Levy",
      "street2": "Apt 1",
      "city": "Saint-Laurent",
      "region1_code": "QC",
      "postal_code": "H4R2P9",
      "country": "CAN"
    },
     "phone_number": "250-555-0199",
    "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,
 "currency": "CAD"
});

⚠

️ Note:

• Our virtual card product only supports modal mode. The Affirm checkout will open in a modal that floats on top of 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.

Step 3: Launch checkout and handle callbacks

After you create the checkout object, you can 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. In the event of a successful checkout, you will retrieve the card details and the checkout_id from the callback. See below for a template:

⚠

️

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 Merchant Help for further information.

affirm.checkout.open_vcn({
      success: function(card_response) {
         console.log(card_response);
      },
      error: function(error_response) {
        console.log(error_response);
      },
      checkout_data: data
});

Step 4: Card management

Once you receive the card details from the checkout response, you can submit authorizations, captures, and refunds to the virtual card using your existing payment rails.

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