Skip to main content

Merchant Help

 

Affirm Merchant Help

Checkout Instrument Server-Side Integration

*Note: 'Checkout Instrument' is Affirm's abstraction for a First Data card.

Overview

Integration Points
  • Checkout flow
    • Add new Affirm payment method
  • Checkout initiation
    • Parse customer and cart data and populate the checkout data JSON
    • Pass checkout data JSON to internal Walmart API endpoint
    • Walmart server-side script to POST the checkout data JSON to the Affirm checkout/direct endpoint.
    • Parse returned checkout URL in the checkout/direct API response and relay to front-end
    • Create iFrame modal window with checkout URL as its source
    • Error handling if the direct checkout API request returns an error message. This message should be relayed to the front-end so users can respond to the error message.
  • Checkout confirmation
    • After the customer confirms their Affirm loan, Affirm will send a POST request to the confirmation URL provided by Walmart during checkout creation. The request will include the checkout ID. Walmart can use this as a trigger to close the iFrame modal window and send the user to their order confirmation page.
  • First Data card details retrieval
    • To retrieve the First Data card details, Walmart will send a GET request to the provided endpoint, using the given checkout ID.
  • Charge authorization and order processing
    • The returned First Data card details will be used to process a redemption via the First Data gateway.
    • Affirm will learn of the redemption from a daily file received from First Data. Upon receipt of this file, the charge will become authorized and captured, thereby finalizing the user's loan.
  • Order management system
    • Flag orders paid using Affirm as such, so it can be distinguished from other order paid with card.
    • Charge management (i.e., refunds) will be facilitated via First Data gateway.

 


 

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.


 

Retrieve First Data 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).


 

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.