Skip to main content

Merchant Help

 

Affirm Merchant Help

Omni-Channel Checkout API

The Omni-Channel Checkout API is used to send checkout links directly to consumers via SMS or email. This allows consumers to apply for an Affirm loan without using a traditional eCommerce checkout process. Once the charge has been confirmed, a webhook API request will be sent to your servers so you can process authorization and capture requests.

Details

By using this endpoint, Affirm will send a text to the billing phone number provided, which will link the consumer to their online application.

You can optionally choose to provide Affirm with a webhook address, for server-to-server confirmation of the checkout_token (after a consumer has confirmed their loan). We will still POST the token to the user_confirmation_url, but using such a webhook can remove the possibility of client/browser errors, and expedite the update of the payment status on your store terminals. Please reach out to mts@affirm.com if you wish to configure this for your in-store integration.

Note: The Omni-Channel Checkout API is currently only available in production, not sandbox. While testing in the production environment, please be sure to not capture any charges - we report the existence of captured production loans to the credit bureaus.

Definition

Parameters

The following Checkout object parameters contain the bulk of the data that needs to be passed. Data should be sent as the content of a POST to one of the URL's above. 

An example message is located at the bottom of this page.

Checkout Object

This is the data payload that gets POSTed to the Affirm API to initialize checkout. All numerical (Integer) values must be passed as integer USD cents (i.e., $25.00 is passed as 2500).

Field Name R/O/C Type Description
financing_program O String A unique financing program name that is provided to you by Affirm. If you have a custom financing program available, you can enter the name of it in this field. If the program is not available or the name is not valid, your default financing program will be used.
merchant R Object (Merchant) Merchant configuration for the checkout session.
shipping C Object (Consumer Details) Consumer's shipping details. Required if the item is being shipped.
billing R Object (Consumer Details) Consumer's billing details.
items R List (Item) A list of items being purchased.
discounts O List (Discount) A list of discounts being applied. The key of each discount is a unique identifier to the discount. The value of each discount is a Discount object.
metadata O Object (Metadata) A hash of keys to values for any metadata to be passed into checkout and stored. 'entity_name' is a protected key, and will show up in your settlement reporting.
order_id O String Your internal order id. This is stored for your own reference.
shipping_amount C Integer The total shipping amount. Required if the item is being shipped. All numerical (Integer) values must be passed as integer USD cents (i.e., $25.00 is passed as 2500).
tax_amount O Integer The total tax amount computed after all discounts have been applied. Defaults to 0. All numerical (Integer) values must be passed as integer USD cents (i.e., $25.00 is passed as 2500).
total R Integer The total amount of the checkout, less any discounts applied. This determines the total amount charged to the user. All numerical (Integer) values must be passed as integer USD cents (i.e., $25.00 is passed as 2500).

 

Merchant object

The merchant object contains the user_confirmation_url and user_cancel_url, which represent the two possible outcomes of the checkout attempt. The user goes to the confirmation_url if the user is approved and confirms their loan. The user goes to the cancel_url in all other cases (voluntary cancel, credit decline, identity verification issue, etc.). 

Field Name R/O/C Type Description
public_api_key R String API Key of the merchant creating the checkout request
user_confirmation_url R URL

URL that the customer is sent to if they successfully complete the Affirm checkout flow. 

A checkout_token will be sent to this URL in the POST request, and that checkout_token should be used to authorize the charge before the user is redirected to the order confirmation page.

user_cancel_url R URL

URL that the customer is sent to if the customer exits the Affirm checkout flow.

This is the same if the user voluntarily cancels or closes the window before completion, or if the user is denied. You should setup the cancel_url to be the checkout payment page, and you can also append analytics tags to the URL to help you identify who you may want to reach out to about alternative payment methods or reapplying.

user_confirmation_url_action O String Accepted values are: 'GET', 'POST'. Defaults to 'POST'. Preference is to use 'GET'. Read more here.
name O String

For phone sales implementation, you will always want to specify a merchant facing name. Otherwise, customers will see the 'Telesales' suffix on the end of your company name.

If you have multiple sites operating under a single Affirm account, you can override the external company/brand name that the customer sees. This affects all references to your company name in the Affirm UI.

 

Consumer Details

Consumer details are used in both the Billing and Shipping address values. It represents the consumers name, address, email address, and phone number.

Field Name R/O/C Type Description
name R Object (Name) Consumers name to be used with the address.
address R Object (Address) Consumers physical address.
phone_number C String Consumers phone number.
email O String Consumers email address.
Name
Field Name R/O/C Type Description
first C String Consumers first name. Either ("first" and "last") or ("full") must be passed.
last C String Consumers last name. Either ("first" and "last") or ("full") must be passed.
full C String Consumers full name. Either ("first" and "last") or ("full") must be passed.
Address
Field Name R/O/C Type Description
line1 R String First line of the consumers address.
line2 O String Second line of the consumers address.
city R String Consumers city.
state R String (2-character ISO State Code) Consumers State.
zipcode R String Consumers zip code.
country R String (2 or 3-character ISO Country Code) Consumers country. NOTE: The only values currently supported are "US" or "USA".

 

Item Object

The item object array should be built dynamically, based on the current cart contents. All numerical (Integer) values must be passed as integer USD cents (i.e., $25.00 is passed as 2500).

Field Name R/O/C Type Description
display_name R String The display name of the product.
sku R String The unique identifier (SKU) of the product.
unit_price R Integer The item individual price. All numerical (Integer) values must be passed as integer USD cents (i.e., $25.00 is passed as 2500).
qty R Integer The item quantity expressed as an integer.
item_image_url O URL The item's product image URL.
item_url O URL The item's product description page URL.

 

Discount Object

Field Name R/O/C Type Description
discount_amount R Integer Amount of the discount being applied. All numerical (Integer) values must be passed as integer USD cents (i.e., $25.00 is passed as 2500).
discount_display_name R String Friendly name of the discount being applied.

 

Syntax notes

  • All numerical values must be sent as integer USD cents ($25.00 -> 2500).
  • The items from a consumer's cart are stored in an object array. You should build this array dynamically by adding item objects to it based on cart contents.
  • The discount object uses the discount code as the name of the nested objects. As a result, you may have to construct each discount without the use of a strongly-typed class.

Response

The POST returns a JSON String. It will also send a text to the phone_number from the billing contact object. This String contains the URL the consumer should be directed to.

Field Name R/O/C Type Description
checkout_id R String Checkout ID for the consumer's application.

Exceptions

If there are any errors processing the request, an error object is returned. The contents of the error object contains details about the specific error.

Error Response Fields

Field R/O/C Type Description
field R String Field containing an incorrect or invalid value.
message R String Friendly message that describes the issue.
code R String Short code referencing the specific error.
type R String Type of error being returned.
status_code R String HTTP Status Code that was returned.

Possible code values

The list below contains all of the possible code values that can be returned by Affirm.

auth-declined
Charge authorization hold declined.
capture-greater-instrument
Charges on this instrument cannot be captured for more than the authorization hold amount.
capture-unequal-instrument
Charges on this instrument cannot be captured for an amount unequal to authorization hold amount.
capture-voided
Cannot capture voided charge.
partial-capture-instrument
Charges on this instrument cannot be partially captured.
refund-exceeded
Max refund amount exceeded.
refund-uncaptured
Cannot refund a charge that has not been captured.
refund-voided
Cannot refund voided charge.
capture-declined
Charge capture declined.
capture-limit-exceeded
Max capture amount on charge exceeded.
expired-authorization
Cannot capture expired charge authorization hold.
refund-expired
Charges on this instrument must be refunded within N days of capture.
financial-product-invalid
Please provide a valid financial product key.
invalid_field
An input field resulted in invalid request.
public-api-key-not-specified
Please provide a public API key.
public-api-key-invalid
Please provide a valid public API key.
public-api-key-wrong-environment
Please provide a live public API key when not using the sandbox environment.
public-api-key-inactive
Please provide an active public API key.
api-key-pair-not-specified
Please provide a API key pair.
private-api-key-invalid
Please provide a valid private API key.
api-key-pair-wrong-environment
Please provide a live API key pair when not using the sandbox environment.
api-key-pair-inactive
Please provide an active API key pair.
not_found
The resource(s) specified in the request could not be found.

Possible type values

The list below contains all of the possible type values that can be returned by Affirm.

invalid-request
A generic error that indicates request inputs were invalid.
unauthorized
API keys were invalid.

Possible status_code values

The list below contains all of the possible status_code values that can be returned by Affirm.

400
Request fields resulted in an error.
401
Authorization was unsuccessful.
404
The requested resource(s) could not be found.
50x
An internal server issue resulted in an error.

Examples

Checkout Configuration Example:

Below is an example of a Checkout Configuration to submit to Affirm:

{
      "merchant": {
        "public_api_key":               "ABCDEF123456",
        "user_confirmation_url":        "https://secure.merchantsite.com/affirm/confirm",
        "user_cancel_url":              "https://secure.merchantsite.com/affirm/cancel"
        "user_confirmation_url_action": "POST",
        "name":                         "Your Customer-Facing Merchant Name"
      },
      "shipping":{
        "name":{
          "first":                      "John",
          "last":                       "Doe"
          // You can include the full name instead
          // "full" :                   "John Doe"
        },
        "address":{
          "line1":                       "325 Pacific Ave",
          "city":                        "San Francisco",
          "state":                       "CA",
          "zipcode":                     "94112",
          "country":                     "USA"
        },
        "phone_number":                  "4151234567",
        "email":                         "johndoe@gmail.com"
      },
      "billing":{
        "name":{
          "full":                        "John Doe"
        },
        "address":{
          "line1":                       "325 Pacific Ave",
          "city":                        "San Francisco",
          "state":                       "CA",
          "zipcode":                     "94112",
          "country":                     "USA"
        },
        // This is the phone number to which Affirm will send a text, linking to the consumer's online application
        "phone_number":                  "4151234567", 
        "email":                         "johndoe@gmail.com"
      },
      "items": [
        {
            "display_name":              "Awesome Pants",
            "sku":                       "ABC-123",
            "unit_price":                1999,        //in cents, this represents $19.99
            "qty":                       3,
            "item_image_url":            "http://merchantsite.com/images/awesome-pants.jpg",
            "item_url":                  "http://merchantsite.com/products/awesome-pants.html"
        }
      ],

      "discounts": {
        "RETURN5": {
          "discount_amount":             500,         //in cents
          "discount_display_name":       "Returning customer 5% discount"
        },
        "PRESDAY10": {
          "discount_amount":             1000,
          "discount_display_name":       "President's Day 10% off"
        }
      },

      "metadata": {
        "shipping_type":                 "UPS Ground",
        "entity_name":                   "internal-sub_brand-name"
      },

      "order_id":                        "JKLMO4321", //Your unique transaction reference
      "shipping_amount":                 1000,        //in cents
      "tax_amount":                      500,         //in cents
      "total":                           6997         //in cents
  });

In addition to sending the consumer a text at the phone_number associated with the billing object, the result is a JSON object including the checkout_id

{"checkout_id": "ABCDEFGH12345678"}

A full PHP example of how this might be used is below:

<?php
    $endpoint = "https://api.affirm.com/api/v2/checkout/store";
    $rawCheckout = array( 
        "merchant" => array (
            "public_api_key" => "ABCDEF123456",
            "user_cancel_url" => "https://secure.merchantsite.com/affirm/cancel",
            "user_confirmation_url" => "https://secure.merchantsite.com/affirm/confirm",
        ),
        "items" => array (
            array (
                "display_name" => "Awesome Pants",
                "item_image_url" => "http://merchantsite.com/images/awesome-pants.jpg",
                "item_url" => "http://merchantsite.com/images/awesome-pants.html",
                "qty" => "1",
                "sku" => "ABC-123",
                "unit_price" => "10000"
            )
        ),
        "shipping" => array (
            "address" => array (
                "city" => "San Francisco",
                "line1" => "225 Bush St",
                "state" => "CA",
                "zipcode" => "94104"
            ),
            "name" => array (
                "full" => "John Doe"
            )
        ),
        "billing" => array (
            "address" => array (
                "city" => "San Francisco",
                "line1" => "225 Bush St",
                "state" => "CA",
                "zipcode" => "94104"
            ),
            "name" => array (
                "full" => "John Doe"
            ),
            "phone_number" => "415-555-5555",
            "email" => "johndoe@gmail.com"
        ),
        "total" => "10000"
    );
            
    $data = json_encode($rawCheckout);
    $contentType = "application/json";
    
    $process = curl_init($endpoint);
    curl_setopt($process, CURLOPT_HTTPHEADER, array('Content-Type: ' . $contentType));
    curl_setopt($process, CURLOPT_HEADER, false);
    curl_setopt($process, CURLOPT_VERBOSE, false);
    curl_setopt($process, CURLOPT_POST, TRUE);
    curl_setopt($process, CURLOPT_POSTFIELDS, $data);
    curl_setopt($process, CURLOPT_RETURNTRANSFER, TRUE);
    $return = curl_exec($process);
        
    $rCode = curl_getinfo( $process, CURLINFO_RESPONSE_CODE );
    
    if ($rCode == 200) {
        print( "<p><h2>Success!</h2><br>");
        print( $return );
    }
    else {
        http_response_code($rCode);
        print_r( "<p><h2>There was an error!</h2><br>" );
        print_r( $return );
    }
    curl_close( $process );
?>