Skip to main content

 

Affirm Merchant Help

Cybersource Integration

Overview

 This guide describes how to directly integrate Affirm into the CyberSource platform (CyberSource's Alternative Payments API) so you can provide Affirm as a payment option to your customers. After integrating Affirm, your CyberSource site will:

  • Offer Affirm as payment option on the checkout page
  • Process Affirm charges in your order management system
  • Display Affirm promotional messaging

The integration steps are:

  1. Get your merchant ID
  2. Build your integration
  3. Add Affirm promotional messaging
  4. Review your order management functions
  5. Add the Confirmation Page function
  6. Test your integration
  7. Deploy to production

Before you begin

Before beginning integration, you should review:

Sandbox development

You should have received an email inviting you to create an Affirm account. Click here for information about accessing your account.

Develop and test the Affirm integration in your development environment connected to our sandbox. To use our sandbox, retrieve your sandbox API keys at https://sandbox.affirm.com/dashboard/#/apikeys for use during integration.

After development and testing, you'll need to update your integration to use your live API keys, which you can find at https://affirm.com/dashboard/#/apikeys.

1. Get your merchant ID

Integrating Affirm into CyberSource requires a merchant ID, which is the same ID value you will use for the sandbox and live environments.

  1. Inform Affirm that you would like to integrate with CyberSource
  2. Get your Affirm merchant ID from your Client Success Manager
  3. Provide your merchant ID to your CyberSource contact

2. Build your integration using CyberSource APIs

Follow the CyberSource Affirm Services integration guide to build your checkout and order management integration:

Initiate Checkout
When you initiate checkout using the Sessions service, you’ll receive a checkout URL (merchantURL) in the Sessions Reply. Redirect the client browser to that checkout URL (merchantURL) using a client-side scripting language, such as JavaScript. After being redirected to Affirm, the customer will complete their loan application. After confirming the loan, the customer will then be redirected back to a success_url value sent in the Sessions service. You will also receive the checkout_token at this URL. (See FAQ section for initiating Affirm checkout in a modal)

Parse checkout_token
The checkout_token is included in the request (via GET method) when the client is redirected back to your site (to the success_url) after confirming their Affirm loan. Use this checkout_token as preapprovalToken in the CyberSource authorization service.

Authorize
Like a card transaction, the authorization will hold the funds and allow you to save the customer's order. The authorization response returns another Transaction ID to use in subsequent actions (capture, refund, etc.).

Capture
Once you've fulfilled an order, capture the associated Affirm payment. Capturing a payment completes the transaction and initiates settlement into your bank account. Captures should occur within 30 days of the authorization. Affirm does not support multiple or partial capture requests. We recommend capturing the whole amount when shipping the first item, and refunding if the customer cancels the remaining items.

Refund
If you need to refund all or part of a transaction, you can use the Refund service. You can process any number of refunds, which can only be processed within 120 days of capturing the charge. A full refund cancels the transaction, which will refund the entire loan principal to the customer.

Void/Authorization Reversal
You can void an authorized transaction to cancel the transaction. Only applies to transactions that haven't been captured.

3. Add Affirm promotional messaging

Affirm promotional messaging components—monthly payment messaging and educational modals—show customers how they can use Affirm to finance their purchases. Properly placed promotional messaging helps drive increased AOV and conversion.

Adding Affirm promotional messaging is a required integration step, and you should complete it before testing your integration. Click here for information about adding Affirm promotional messaging.

4. Review your order management functions

Processing transactions (authorize, void, refund, and partial refund) in CyberSource updates the loan status in the Affirm dashboard. While you can process orders in the dashboard, we strongly recommend using CyberSource to keep order status synced with Affirm. For more information on processing orders in CyberSource, refer to their CyberSource Affirm Services integration guide (Simple Order API/SCMP API).

5. Add the Confirmation Page function

When a customer completes their purchase, you can send their order and product information to Affirm for A/B testing, which will help you optimize your site. Send this information by adding the Confirmation Page function to your payment confirmation page. We only require orderId, total, productId, and quantity for A/B testing.

Click here for all the Confirmation Page function parameters.


affirm.analytics.trackOrderConfirmed({
    "paymentMethod": "Visa",
    "orderId": "T12345",
    "total": 3739
}, [{
    "productId": "SKU-1234",
    "quantity": 1
}, {
    "productId": "SKU-5678",
    "quantity": 1
}]);

Required function parameters

Order object

paymentMethod string The payment method chosen by the customer (e.g., Visa). Maximum 150 characters.
orderId string Your internal unique identifier representing the order. Maximum 500 characters.
total integer The total amount of the transaction, including tax and shipping, stated in USD cents (e.g., $100 = 10000).

Product object

productId string Your internal unique identifier representing the product, such as the SKU or an internal database identifier. Maximum 500 characters.
quantity integer The quantity of the purchased product.

6. Test your integration

After completing your integration, do a thorough testing of both your front-end and order management functions in our sandbox to ensure that everything works as expected. Click here for our recommended test plan. However, you’ll need to tailor your testing plan to your specific systems, processes, and integration.

For test transactions, send requests to the CyberSource test server.

7. Deploy to production

Coordinate testing with Affirm

Before deploying the Affirm integration to your production site, Affirm will need to test it in your development or staging environment connected to our live environment. Contact your Integration Consultant or merchanthelp@affirm.com to coordinate this test.

Connect to the live Affirm environment

  1. Contact CyberSource to have them enable Affirm in production
  2. Retrieve your live API keys at https://affirm.com/dashboard/#/apikeys
  3. Update the script parameter in the Affirm.js embed code to point to our live environment at https://cdn1.affirm.com/js/v2/affirm.js
  4. Replace the public_api_key parameter in the Affirm.js embed code with the public API key you just retrieved
  5. For live transactions, send requests to the CyberSource production server

Launch to production

After you’ve connected to our live environment and we’ve tested your integration, you’re ready to deploy to your production environment and offer Affirm as a payment option to your customers.

FAQ

1. How do I initiate Affirm checkout in a modal instead of redirect checkout flow?

When you send a Sessions service request, you receive "merchantURL" as one of the fields in a successful Sessions reply. If you'd like to render Affirm checkout in a modal instead of redirecting the user to the Affirm checkout, you would need to retrieve the checkout_token/preapprovalToken prior to initiating a redirect to the "merchantURL". You can then use the checkout_token to initiate the checkout in a Affirm modal using Affirm.js. Additional callback functions should also be added to redirect to the same success_url and cancel_url value that was sent in the Sessions service. The onSuccess() callback should also initiate the authorization request using the checkout_token before confirming the order on your site.

Sample PHP code can be found below, where public_api_key can be retrieved from the Affirm dashboard and the version of Affirm.js used should correspond to whether you're publishing your changes to a sandbox or production environment:

<?php
  $url = "https://sandbox.affirm.com/checkout/your_public_apikey/new/new_token/"; //Replace this with merchantURL from Sessions Reply
  $path = parse_url($url, PHP_URL_PATH); //retrieve checkout token
  $checkoutToken = basename($path);
?>
<html>
  <head>
  </head>
  <body>
    <script>
      //Include Affirm.js
      var _affirm_config = {
      public_api_key: "your_public_apikey", // Public API Key retrieved from the Affirm dashboard
      script:         "https://cdn1-sandbox.affirm.com/js/v2/affirm.js" //Affirm.js runtime script
      };
      (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 the checkout token to create checkout request for modal checkout
      affirm.checkout({
        "checkoutAri"  : "<?php echo $checkoutToken ?>",
        "metadata": {
          "mode": "modal" 
         }
        });
    </script>
    <script>
      // Open modal checkout and add callbacks
      affirm.checkout.open({
        onFail: function(a){/* Add code to redirect to ap_sessions_cancel_url=http://cancel.example.com */},
        onSuccess: function(a){ /* Add code to redirect to ap_sessions_success_url=http://success.example.com and use the checkoutToken as preapprovalToken for authorizing a payment */ }
        });
    </script>
  </body>
</html>

Additional Affirm checkout modal considerations can be found here