Skip to main content

Merchant Help

 

Affirm Merchant Help

Cybersource Integration

Overview

 This guide describes how to integrate Affirm into the CyberSource platform 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’ll use for the sandbox and live environments.

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

2. Build your integration using CyberSource APIs

Follow this CyberSource Simple Order API 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 in the response body. Redirect the client browser to that checkout URL 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 URL you chose You’ll receive the checkout_token at this URL.

Parse checkout_token
The checkout_token is included in the request (via GET method) when the client is redirected back to your site after confirming their Affirm loan. POST the checkout_token to CyberSource for charge authorization.

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
Void an authorized charge, which remains not captured, to cancel the transaction.

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 Simple Order API Guide.

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({
    "orderId": "T12345",
    "total": 3739
}, [{
    "productId": "SKU-1234",
    "quantity": 1
}, {
    "productId": "SKU-5678",
    "quantity": 1
}]);

Required function parameters

Order object

Parameter Type Description
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

Parameter Type Description
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 Client Success Manager 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-sandbox.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.