Skip to main content

 

Affirm Merchant Help

Define Checkout Object

Checkout object

The checkout object is the data payload that gets POSTed to the Affirm API to initialize checkout. 

affirm.checkout({

      "merchant": {
        "user_confirmation_url":    "https://merchantsite.com/confirm",
        "user_cancel_url":          "https://merchantsite.com/cancel",
        "user_confirmation_url_action": "POST",
        "name": "Your Customer-Facing Merchant Name"
      },
      "shipping":{
        "name":{
          "first":"Joe",
          "last":"Doe"
          // You can include the full name instead
          // "full" : "John Doe"
        },
        "address":{
          "line1":"633 Folsom St",
          "line2":"Floor 7",
          "city":"San Francisco",
          "state":"CA",
          "zipcode":"94107",
          "country":"USA"
        },
        "phone_number": "4153334567",
        "email": "joedoe@123fakestreet.com"
      },
      "billing":{
        "name":{
          "first":"Joe",
          "last":"Doe"
        },
        "address":{
          "line1":"633 Folsom St",
          "line2":"Floor 7",
          "city":"San Francisco",
          "state":"CA",
          "zipcode":"94107",
          "country":"USA"
        },
        "phone_number": "4153334567",
        "email": "joedoe@123fakestreet.com"
      },
      "items": [{
        "display_name":         "Awesome Pants",
        "sku":                  "ABC-123",
        "unit_price":           1999,
        "qty":                  3,
        "item_image_url":       "http://merchantsite.com/images/awesome-pants.jpg",
        "item_url":             "http://merchantsite.com/products/awesome-pants.html"
        "categories": [
            ["Home", "Bedroom"],
            ["Home", "Furniture", "Bed"]
        ],
      }],
      "discounts": {
        "RETURN5": {
          "discount_amount":    500,
          "discount_display_name": "Returning customer 5% discount"
        },
        "PRESDAY10": {
          "discount_amount":    1000,
          "discount_display_name": "President's Day 10% off"
        }
      },

      "metadata": {
          //user defined key/value pairs
          "platform_type": "your-platform-name",
          "shipping_type": "UPS Ground"
          //webhook_session_id: "ABC123"
      },

      "order_id":               "JKLMO4321",

      "shipping_amount":        1000,
      "tax_amount":             500,
      "total":                  5997
  });
merchant

required object.

Define the URLs for the two results of a checkout attempt and an optional external name.

shipping

required object.

Customer contact information.

billing

optional object.

Customer contact information.

items

required list.

A list of item objects.

discounts

optional hash.

A hash of coupon codes to discount objects. If discounts are passed, they must have a name and positive integer dollar amount.

metadata

optional object.

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

optional string.

Your internal order id. This is stored for your own future reference.

shipping_amount

required integer.

The total shipping amount; Defaults to 0.

tax_amount

required integer.

The total tax amount computed after all discounts have been applied; Defaults to 0.

total

required integer.

The total amount of the checkout. This determines the total amount charged to the user.

Note: We only use this value for the loan total; we do not calculate the total from the checkout object line items.

Merchant object 

The merchant object contains the user_confirmation_url and user_cancel_url. The customer goes to the user_confirmation_url if the user is approved and confirms their loan. The user goes to the user_cancel_url in all other cases, such as voluntary cancel, credit decline, identity verification issue, etc. 

"merchant": {
    "user_confirmation_url":    "https://merchantsite.com/confirm",
    "user_cancel_url":          "https://merchantsite.com/cancel",
    "user_confirmation_url_action": "POST", // or "GET"
    "name":          "External Company Name"
     },
user_confirmation_url

required 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.

Analytics tags are other query string parameters can be persisted here as well. Read more here.

user_cancel_url

required 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.

Analytics tags are other query string parameters can be persisted here as well. Read more here.

user_confirmation_url_action

optional string.

Accepted values are: 'GET', 'POST'. Defaults to 'POST'. Read more here.

name

optional string.

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.

Contact object

The Contact object includes the shipping object, which is is required, and the billing object, which is optionalBoth objects have the same format. It also includes the Address and Name objects.


"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":{
          "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"
      }
(object key name)

required string.

Either 'shipping' or 'billing'. Only the 'shipping' object is required, 'billing' object is optional.

name

required object.

First and last, or full name. Used to pre-populate the account sign-up form.

address

required object.

Address information. Validated against public address service APIs.

phone_number

optional string.

The user's phone number. Validated against the Affirm checkout API. Must be a valid, U.S.-based, mobile phone number.

email

optional string.

The user's email address.


"address":{
   "line1":"633 Folsom St",
   "city":"San Francisco",
   "state":"CA",
   "zipcode":"94107",
   "country":"USA"
}
line 1

required string.

Valid U.S. street address, verified by public address service APIs.

line 2

optional string.

Apartment, suite, floor, etc.

city

required string.

City name, verified by public address service APIs.

state

required string.

2-letter ISO code or full name, verified by public address service APIs.

zipcode

required string.

Must match other provided address information, verified by public address service APIs.

country

optional string.

If provided, must be 'US' or 'USA' (3-letter ISO code). Affirm is only available to U.S. residents.


"name":{
   "first": "John",
   "last": "Doe",
   "full": "John Doe"
}
first

required string.

Can contain multiple words (for middle names).

last

required string.

 

full

optional string.

Required if 'first' and 'last' keys are missing. String must contain at two words.

Item object

Build the Item object array dynamically based on the current cart contents. Item object array will be used to provide additional insights for customer service operations.


"items": [{
        "display_name":         "Awesome Pants",
        "sku":                  "ABC-123",
        "unit_price":           1999,
        "qty":                  3,
        "item_image_url":       "http://merchantsite.com/images/awesome-pants.jpg",
        "item_url":             "http://merchantsite.com/products/awesome-pants.html",
        "categories": [
            ["Apparel", "Pants"],
            ["Mens", "Apparel", "Pants"]
        ]
      },
      {
        "display_name":         "Best Drone",
        "sku":                  "DEF-456",
        "unit_price":           5999,
        "qty":                  1,
        "item_image_url":       "http://merchantsite.com/images/best-drone.jpg",
        "item_url":             "http://merchantsite.com/products/best-drone.html",
        "categories": [
            ["Electronics", "Drones"],
            ["Drones", "Best Drones"]
        ]
      }]
display_name

required object.

The display name of the product.

sku

required string.

The product SKU.

unit_price

required integer.

The item price expressed as integer USD cents ("$100" = 10000).

qty

required integer.

The item quantity expressed as an integer.

item_image_url

required string.

The item's product image URL.

item_url

required string.

The item's product description page URL.

categories

optional array.

An array of lists that indicate the various categories that apply to this product, and the hierarchy of those category definitions. Each list in the array contains one or more comma-separated strings, with the first string being the highest-level (widest) category.

Metadata object


 "metadata": {
        "shipping_type":        "UPS Ground",
        "entity_name":          "internal-sub_brand-name",
        "platform_type":        "your-platform-name",
        "webhook_session_id":    "A1b2C3"
      },
shipping_type

required string.

Customer contact information.

entity_name

optional string.

Internal sub-brand name.

platform_type

optional string.

Name of your platform Ex: Magento.

webhook_session_id

optional string.

Customer or session specific ID that's used to reconcile incoming webhooks. Optional unless Affirm webhooks are used.

mode

optional string.

Value can be 'modal'. Enables modal checkout. See implementation details and restrictions here.

  • Was this article helpful?