Skip to main content

 

Affirm Merchant Help

Affirm Exchange 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",
    "exchange_lease_enabled": true,
  },
  "shipping": {
    "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"
  },
  "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": "Affirm Pants",
      "sku": "ABC-123",
      "unit_price": 1999,
      "qty": 3,
      "item_image_url": "https://merchantsite.com/images/affirm-pants.jpg",
      "item_url": "https://merchantsite.com/products/affirm-pants.html",
      "categories": [
        ["Home","Bedroom"],
        ["Home","Furniture","Bed"]
      ],
      "leasable": true
    }
  ],
  "discounts": {
    "DISCOUNT5": {
      "discount_amount": 500,
      "discount_display_name": "$5 discount"
    }
  },
  "metadata": {
    "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 

Affirm Exchange Merchant Object

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": "Affirm Pants",
      "sku": "ABC-123",
      "unit_price": 1999,
      "qty": 3,
      "item_image_url": "https://merchantsite.com/images/affirm-pants.jpg",
      "item_url": "https://merchantsite.com/products/affirm-pants.html",
      "categories": [
        ["Home","Bedroom"],
        ["Home","Furniture","Bed"]
      ],
      "leasable": true
    }
  ],
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.

leasable

required Boolean

Determines whether the merchandise is considered leasable. 
   

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.