Skip to main content

 

Affirm Merchant Help

VirtualCard Server-Side Integration

 

Overview

Integration Points
  • Checkout flow
    • Add new Affirm payment method selector
       
  • Generate checkout session and initiate checkout
    • Write code to populate checkout_data and generate checkout session token on the back-end
    • If checkout data is valid:
      • Pass checkout_session_token to the front-end and initiate checkout.
    • If checkout data is invalid:
      • Pass error 'message' along to the front-end, and optionally highlight the field that's causing the error.
         
  • Order confirmation
    • Write success callback function to pass the returned checkout_session_token to the back-end
    • Write server-side script to request card details using the checkout_session_token
    • Populate card fields with the card details returned server-side
       
  • Order management system
    • Flag orders paid using Affirm as such, so it can be distinguished from other orders paid with a card 
User Flow

  1. User selects Affirm payment method during checkout
  2. User submits checkout
  3. Merchant submits checkout object JSON to /checkout/session endpoint and generates checkout_session_token
  4. Merchant stores returned checkout_session_token and passes to front-end
  5. Merchant populates 'affirm.checkout.open_vcn({ checkout_session_token })' object
  6. Merchant calls 'affirm.checkout.open_vcn()' function
  7. Affirm checkout pop-up window displays
  8. User logs in or creates an account with Affirm
  9. User selects loan terms
  10. User confirms loan terms
  11. Success callback is triggered
  12. Merchant stores card_token string
  13. Merchant calls Affirm /card/ API endpoint with card_token to retrieve card details
  14. Merchant parses returned card details
  15. Merchant populates card form fields or submits card auth request on back-end
  16. Merchant submits checkout page
  17. Merchant sends card authorization hold request via their payment gateway
  18. Merchant waits for success response
  19. Merchant redirects user to order confirmation page
  20. Order is complete

 

Merchant account setup

How to access your Affirm merchant account credentials.
Google Account

You can sign into the Affirm Dashboard using Google, or using your email and password.

  • If you'd like to use the Google sign-in option, and your work email address isn't associated with a Google account, you can do so here: Sign up without Gmail
  • If your company uses Gmail, or if you already have a Google account, you can select your work account after clicking the Google sign-in button.

Go to the Merchant Dashboard

You can access the sandbox environment Merchant Dashboard here:

https://sandbox.affirm.com/dashboard

Sign in with your Google account. If you aren't able to login, or receive a Internal Server Error, you may not have access to this dashboard or the dashboard may not be enabled. Please contact merchanthelp@affirm.com to restore your access.

Affirm Merchant Sandbox Dashboard

  1. Go to: https://sandbox.affirm.com/dashboard.
  2. Sign in with Google, or use your email and password.

Note: The work email address that you use to sign-in to the Affirm Dashboard must be granted access by your Dashboard's administrator, or your Affirm contact.

Need help accessing the Affirm Dashboard?

Retrieve Sandbox Keys

Once you are in the Merchant Dashboard, use the navigation bar on the left to access your API Keys. You will need the public key, private key, and financial product key that is displayed here.

  1. Hover over the profile icon area at the lower-left of the page.
    Screen Shot 2016-03-22 at 7.56.58 AM-2.png
  2. Click the API Keys link that appears.
    Screen Shot 2016-03-22 at 7.56.20 AM.png
  3. Copy the public, private, and financial product keys.


 

Generate Checkout Session Token


 

Initiate Checkout

Embed Affirm's JS runtime code


<script>
  _affirm_config = {
    public_api_key:  "XXXXXXXXXXXXXXX",
    script:          "https://cdn1-sandbox.affirm.com/js/v2/affirm.js"
  };
  (function(l,g,m,e,a,f,b){var d,c=l[m]||{},h=document.createElement(f),n=document.getElementsByTagName(f)[0],k=function(a,b,c){return function(){a[b]._.push([c,arguments])}};c[e]=k(c,e,"set");d=c[e];c[a]={};c[a]._=[];d._=[];c[a][b]=k(c,a,b);a=0;for(b="set add save post open empty reset on off trigger ready setProduct".split(" ");a<b.length;a++)d[b[a]]=k(c,e,b[a]);a=0;for(b=["get","token","url","items"];a<b.length;a++)d[b[a]]=function(){};h.async=!0;h.src=g[f];n.parentNode.insertBefore(h,n);delete g[f];d(g);l[m]=c})(window,_affirm_config,"affirm","checkout","ui","script","ready");
 // Use your live public API Key and https://cdn1.affirm.com/js/v2/affirm.js script to point to Affirm production environment.
</script>

Note: Be sure to use your public API key from the sandbox merchant dashboard for 'public_api_key' and a session ID variable for the optional 'session_id' to take advantage of additional analytics. The API key must match the Affirm-environment you're referencing ('sandbox' or 'live').

Once the Affirm JS is initialized, the affirm.checkout method is made available:

  • affirm.checkout.open_vcn() - Initiates the VCN checkout window and accepts the checkout data object as its parameter.

The Affirm environment that's used is determined by the Affirm script URL that's defined in the _affirm_config.script:

var _affirm_config = {
    public_api_key:  "XXXXXXXXXXXXXXX",
    script:          "https://cdn1-sandbox.affirm.com/js/v2/affirm.js"
  };

Checkout Object

You can define a separate checkout object to contain the top-level parameters for the open_vcn() method. This is where you define the name of the checkout_data object, success callback, and error callback.

affirm.checkout.open_vcn({

      success: function(card_token) {
         success_callback_function();
      }
      error: error_callback_function
      checkout_session_token: checkoutSessionToken
  });
success
required event. This event is triggered when the user successfully completes the Affirm checkout flow. The event data contains the virtual card token. This token will then be subsequently exchanged for the virtual card details via server-side API.
error
optional event. This event is triggered if the user is denied, or if they voluntarily cancel the Affirm checkout flow. The event data is generic, and only indicates that the checkout was canceled (even if they were actually denied).
checkout_session_token
required string. The checkout session token corresponds to checkout data submitted to the Affirm servers previously, which contains all the cart details, customer information, and metadata for the order.


 

Checkout Result


 

Retrieve Card Details

Card details request format

GET /api/v2/checkout/<checkout_id>/checkout_instrument

This returns the card details associated with the checkout_id that was passed in the request URL. Once the card details are returned, the card can be authorized through your usual card gateway.


curl https://sandbox.affirm.com/api/v2/checkout/<checkout_id>/checkout_instrument
     -u "(public_api_key):(private_api_key)"
URL

 

Card details response object

200 Response:


{
   number:"41111111111111111",
   pin:"1234"
}
 
number
string. The First Data card number.
pin
string. The First Data card pin.

400 Response if no First Data card exists for the given checkout.


500 Response if Affirm is unable to issue a card with First Data.


 

Charge Actions

All charge actions are done using your existing payment gateway and First Data. 

To redeem or reload the First Data card, simply use your payment gateway API and the First Data card number that was returned at checkout. 

Do not attempt to interact directly with the Affirm API for charges that were created. All charge interactions must be done through First Data.

Furthermore, the state of the Affirm charge as it appears in the Merchant Dashboard will not always reflect the charge state on the card network. For example, a refunded charge may not show as refunded on Affirm's side for up to 24 hours. Please refer to our merchant resources for customer-facing teams to help explain the relationship between charge actions on the gift card network (processed by the merchant) and the charge state in Affirm's system (visible to the customer).


 

Example Code

Create checkout session
curl https://sandbox.affirm.com/api/v2/checkout/session \
     --verbose \
     -X POST \
     -u "ARQBLCL7NAMBTZ7F:RkHBmVSP5ayC2rCUujwhArpGWPxpuTtv" \
     -H "Content-Type: application/json"\
     -d '{"merchant": {"public_api_key":"ARQBLCL7NAMBTZ7F","user_cancel_url": "http://requestb.in/14h8g7c1","user_confirmation_url": "http://requestb.in/xdxxyyxd"},"items": [{"display_name": "Great product","item_url": "http://www.google.com","item_image_url": "","qty": 2,"sku": "ABC123","unit_price": 10000}],"shipping": {"address": {"city": "San Francisco","line1": "633 Folsom Street","state": "CA","zipcode": "94107"},"name":{"full":"Z"},"phone_number":"9253236612"},"billing": {"address": {"city": "San Francisco","line1": "633 Folsom Street","state": "CA","zipcode": "94107"},"email":"benmoo@gmail.com","name":{"full":"Z"},"phone_number":"9253236612"},"total": 10000}'
Retrieve card
curl https://sandbox.affirm.com/api/v2/card/
     -X POST
     -u "(public_api_key):(private_api_key)"
     -H "Content-Type: application/json"
     -d '{"card_token": "ARZBLCL7NAMBTZ2D"}' 


 

Settlement

Since all charges are captured through your existing card gateway, you will rely on the existing settlement reports that are generated by your card gateway to reconcile transactions.

Affirm will provide a monthly invoice so that any applicable merchant fees can be remitted, and a more detailed transaction-level spreadsheet will be provided to reconcile Affirm transactions.