Skip to main content

 

Affirm Merchant Help

Affirm API Reference

Methods

Authorize

Charge authorization occurs after a user completes the Affirm checkout flow and returns to the merchant site. Authorizing the charge generates a charge ID that will be used to reference it moving forward. You must authorize a charge to fully create it. A charge is not visible in the Read charge response, nor in the merchant dashboard until you authorize it.

URL

Sandbox: https://sandbox.affirm.com/api/v2/charges
Live: https://api.affirm.com/api/v2/charges

Options

  • Type: POST
  • Authorization: Basic
  • Content type: application/JSON
  • Data: JSON string

Data

public_api_key

Required string

Your public API key.
private_api_key

Required string

Your private API key.
checkout_token

Required string

A unique token used to authorize a charge. The checkout_token is POSTed to user_confirmation_url after the customer confirms their loan.
order_id

Required string

Your internal order ID that corresponds to the charge.

Response

The response to your request will contain the full charge response object, which includes all of the information submitted when you initialized checkout in addition to the charge and transaction-level identifiers. The only two pieces of information you need to parse from this response object are amount and the id.

200 Success
400

Authorization failed.

Message the customer, ""There was an issue authorizing your Affirm loan. Please check out again or use a different payment method."

Redirect customer back to payment method selection.

401

Unauthorized.

Message the customer, "There was an issue authorizing your Affirm loan. Please check out again or use a different payment method."

Redirect customer back to payment method selection.

402

Checkout token expired.

Message the customer, "There was an issue authorizing your Affirm loan. Please check out again or use a different payment method."

Redirect customer back to payment method selection.

Request

curl https://affirm.com/api/v2/charges/
     -X POST
     -u "<public_api_key>:<private_api_key>"
     -H "Content-Type: application/json"
     -d '{"checkout_token": "<checkout_token>","order_id": "JKLM4321"}'

Response

{
   "id:ALO4-UVGR",
   "created":"2016-03-18T19:19:04Z",
   "currency":"USD",
   "amount":6100,
   "auth_hold":6100,
   "payable":0,
   "void":false,
   "expires": "2016-04-18T19:19:04Z",
   "order_id":"JKLM4321",
   "events":[
      {
         "created":"2014-03-20T14:00:33Z",
         "currency":"USD",
         "id":"UI1ZOXSXQ44QUXQL",
         "transaction_id":"TpR3Xrx8TkvuGio0",
         "type":"auth"
      }
   ],
   "details":{
      "items":{
         "sweater-a92123":{
            "sku":"sweater-a92123",
            "display_name":"Sweater",
            "qty":1,
            "item_type":"physical",
            "item_image_url":"http://placehold.it/350x150",
            "item_url":"http://placehold.it/350x150",
            "unit_price":5000
         }
      },
      "order_id":"JKLM4321",
      "shipping_amount":400,
      "tax_amount":700,
      "shipping":{
         "name":{
            "full":"John Doe"
         },
         "address":{
            "line1":"325 Pacific Ave",
            "city":"San Francisco",
            "state":"CA",
            "zipcode":"94112",
            "country":"USA"
         }
      }
      "discounts": {
        "RETURN5": {
          "discount_amount":    500,
          "discount_display_name": "Returning customer 5% discount"
        },
        "PRESDAY10": {
          "discount_amount":    1000,
          "discount_display_name": "President's Day 10% off"
        }
      }
   }
}

Read

Read the checkout data and current checkout status for a specific checkout attempt. This is also useful for updating your phone or in-store agent's UI.

URL

Sandbox: https://sandbox.affirm.com/api/v2/checkout/<checkout_id>
Live: https://api.affirm.com/api/v2/checkout/<checkout_id>

Options

  • Type: GET
  • Authorization: Basic
  • Content type: application/JSON
  • Data: JSON string

Data

public_api_key

Required string

Your public API key.
private_api_key

Required string

Your private API key.
checkout_id

Required string

The ID returned from the direct checkout API response. Also referred to as the checkout_token.

 Response

200 Success

Request

curl https://sandbox.affirm.com/api/v2/checkout/checkout_id/
     -u "public_key:private_key"

Response

{
   "status": "opened",
   "created":"2016-03-18T19:19:04Z",
   "currency":"USD",
   "total":6100,
   "details":{
      "items":{
         "sweater-a92123":{
            "sku":"sweater-a92123",
            "display_name":"Sweater",
            "qty":1,
            "item_type":"physical",
            "item_image_url":"http://placehold.it/350x150",
            "item_url":"http://placehold.it/350x150",
            "unit_price":5000
         }
      },
      "order_id":"JKLM4321",
      "shipping_amount":400,
      "tax_amount":700,
      "shipping":{
         "name":{
            "full":"John Doe"
         },
         "address":{
            "line1":"633 Folsom St",
            "line2":"Floor 7",
            "city":"San Francisco",
            "state":"CA",
            "zipcode":"94112",
            "country":"USA"
         }
      }
      "discounts": {
        "RETURN5": {
          "discount_amount":    500,
          "discount_display_name": "Returning customer 5% discount"
        },
        "PRESDAY10": {
          "discount_amount":    1000,
          "discount_display_name": "President's Day 10% off"
        }
      }
   }
}

Read charge

Read the charge information, current charge status, and checkout data for one or more charges. This is useful for updating your records or order management system with current charge states before performing actions on them. It also allows you to keep your system in sync with Affirm if your staff manually manages loans in the merchant dashboard.

URL

Sandbox: https://sandbox.affirm.com/api/v2/charges/<charge_id>
Live: https://api.affirm.com/api/v2/charges/<charge_id>

Options

  • Type: GET
  • Authorization: Basic
  • Content type: application/JSON
  • Data: JSON string

Data

public_api_key

Required string

Your public API key.
private_api_key

Required string

Your private API key.
charge_id

Optional string

The charge ID. If you don't specify the charge ID,  a list of charges will be returned. You can define how the results are paginated using the parameters below.
limit

Optional integer

Number of charges to include in the response.
before

Optional string

Returns a list of charges that were created before the given charge ID.
after

Optional string

Returns a list of charges that were created after the given charge ID.

Response

200 Success

Request (single charge)

curl https://sandbox.affirm.com/api/v2/charges/charge_id/
     -X GET
     -u "public_key:private_key"

Request (multiple charges)

curl https://sandbox.affirm.com/api/v2/charges/?limit=5&before=1234-ABCD
     -X GET
     -u "public_key:private_key"

Response

{
   "id:ALO4-UVGR",
   "status": "auth",
   "created":"2016-03-18T19:19:04Z",
   "currency":"USD",
   "amount":6100,
   "auth_hold":6100,
   "payable":0,
   "void":false,
   "expires": "2016-04-18T19:19:04Z",
   "order_id":"JKLM4321",
   "events":[
      {
         "created":"2014-03-20T14:00:33Z",
         "currency":"USD",
         "id":"UI1ZOXSXQ44QUXQL",
         "transaction_id":"TpR3Xrx8TkvuGio0",
         "type":"auth"
      }
   ],
   "details":{
      "items":{
         "sweater-a92123":{
            "sku":"sweater-a92123",
            "display_name":"Sweater",
            "qty":1,
            "item_type":"physical",
            "item_image_url":"http://placehold.it/350x150",
            "item_url":"http://placehold.it/350x150",
            "unit_price":5000
         }
      },
      "order_id":"JKLM4321",
      "shipping_amount":400,
      "tax_amount":700,
      "shipping":{
         "name":{
            "full":"John Doe"
         },
         "address":{
            "line1":"633 Folsom St",
            "line2":"Floor 7",
            "city":"San Francisco",
            "state":"CA",
            "zipcode":"94112",
            "country":"USA"
         }
      }
      "discounts": {
        "RETURN5": {
          "discount_amount":    500,
          "discount_display_name": "Returning customer 5% discount"
        },
        "PRESDAY10": {
          "discount_amount":    1000,
          "discount_display_name": "President's Day 10% off"
        }
      }
   }
}

Capture

Capture the funds of an authorized charge, similar to capturing a credit card transaction. After capturing a loan:

  • The customer receives a notice that the charge is captured
  • The customer's first payment is due in 30 days
  • Affirm pays the merchants within 2-3 business days
  • Full or partial refunds can be processed within 120 days

URL

Sandbox: https://sandbox.affirm.com/api/v2/charges/<charge_id>/capture
Live: https://api.affirm.com/api/v2/charges/<charge_id>/capture

Options

  • Type: POST
  • Authorization: Basic
  • Content type: application/JSON
  • Data: JSON string

Data

public_api_key

Required string

Your public API key.
private_api_key

Required string

Your private API key.
charge_id

Required string

The charge ID.
order_id

Optional string

Your internal Order ID stored for your future reference.
shipping_carrier

Optional string

The shipping carrier used to ship the items in the charge.
shipping_confirmation

Optional string

The tracking number for the shipment.

Response

200 Success
400 Capture failed.
401 Unauthorized.
402 Authorization expired.

Request

curl https://sandbox.affirm.com/api/v2/charges/charge_id/capture
     -X POST
     -u "(public_api_key):(private_api_key)"
     -H "Content-Type: application/json"
     -d '{"order_id": "JKLM4321", "shipping_carrier": "USPS", "shipping_confirmation": "1Z23223"}

Response

{
"fee": 600,
"created": "2016-03-18T00:03:44Z",
"order_id": "JKLM4321",
"currency": "USD",
"amount": 6100,
"type": "capture",
"id": "O5DZHKL942503649",
"transaction_id": "6dH0LrrgUaMD7Llc"
}

Void

Cancel an authorized charge. After voiding a loan:

  • It is permanently canceled and cannot be re-authorized
  • The customer receives a notice that the transaction is canceled

URL

Sandbox: https://sandbox.affirm.com/api/v2/charges/<charge_id>/void
Live: https://api.affirm.com/api/v2/charges/<charge_id>/void

Options

  • Type: POST
  • Authorization: Basic
  • Content type: application/JSON
  • Data: JSON string

Data

public_api_key

Required string

Your public API key.
private_api_key

Required string

Your private API key.
charge_id

Required string

The charge ID.

Response

200 Success
400 Authorization failed.
401 Unauthorized.
402 Checkout token expired.

Request

curl https://sandbox.affirm.com/api/v2/charges/charge_id/void
     -X POST
     -u "(public_api_key):(private_api_key)"

Response

{
"type": "void",
"id": "N5E9OXSIDJ8TKZZ9",
"transaction_id": "G9TqohxBlRPWTGB2",
"created": "2014-03-17T22:52:16Z",
"order_id": "JLKM4321"
}

Refund

Refund a charge. (add link to refund info)

Request

URL

Sandbox: https://sandbox.affirm.com/api/v2/charges/<charge_id>/refund
Live: https://api.affirm.com/api/v2/charges/<charge_id>/refund

Options

  • Type: POST
  • Authorization: Basic
  • Content type: application/JSON
  • Data: JSON string

Data

public_api_key

Required string

Your public API key.
private_api_key

Required string

Your private API key.
charge_id

Required string

The charge ID.
amount

Optional integer

The amount to be refunded, stated in USD cents ($500 = 50000). If this parameter is missing or null, then the entire remaining loan balance will be refunded (full refund).

Response

200 Success
400 Refund request failed.
401 Unauthorized.
402 Authorization expired.

Response

{
  "created": "2014-03-18T19:20:30Z",
  "fee_refunded": 1500,
  "amount": 50000,
  "type": "refund",
  "id": "OWA49MWUCA29SBVQ",
  "transaction_id": "r86zdkHONPcaiVJJ"
}

Update

Update a charge with new fulfillment or order information, such as shipment tracking number, shipping carrier, or order ID.

Request

URL

Sandbox: https://sandbox.affirm.com/api/v2/charges/<charge_id>/update
Live: https://api.affirm.com/api/v2/charges/<charge_id>/update

Options

  • Type: POST
  • Authorization: Basic
  • Content type: application/JSON
  • Data: JSON string

Data

public_api_key

Required string

Your public API key.
private_api_key

Required string

Your private API key.
charge_id

Required string

The charge ID.
order_id

Optional string

Your internal Order ID stored for your future reference.
shipping_carrier

Optional string

The shipping carrier used to ship the items in the charge.
shipping_confirmation

Optional string

The tracking number for the shipment.
shipping

Optional object

The customer contact information for shipping.

Response

200 Success

Response

{  
   "created":"2016-11-30T21:07:47Z",
   "order_id":"JLKM4321",
   "shipping_confirmation":"1Z23223",
   "shipping":{  
      "name":{  
         "full":"John Doe"
      },
      "address":{  
         "city":"San Francisco",
         "state":"CA",
         "zipcode":"94111",
         "line1":"325 Pacific Ave",
         "country":"USA"
      }
   },
   "shipping_carrier":"USPS",
   "type":"update",
   "id":"EILMLQLZPGC742HO"
}

Data types

Checkout object

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

merchant

Required object

The URLs for when a customer either confirms a loan or exits the loan process and an optional external name.
shipping

Optional object

The customer contact information for shipping.
billing

Required object

The customer contact information for billing.
items

Required object

A list items the customer is purchasing. Each item is an object.
discounts

Optional object

A hash of coupon codes to discount objects. Passed discounts must have a name and positive integer dollar amount.
metadata

Optional object

A hash of key value pairs for any metadata passed into checkout and stored. The key 'entity_name' is protected and will show up in your settlement reporting.
order_id

Optional string

Your internal Order ID stored for your future reference.
shipping_amount

Required integer

The total shipping amount, stated in USD cents (e.g., $100 = 10000). Default is 0.
tax_amount

Required integer

The total tax amount computed after all discounts have been applied, stated in USD cents (e.g., $100 = 10000). Default is 0.
total

Required integer

The total amount of the checkout, which determines the total amount charged to the user, stated in USD cents (e.g., $100 = 10000). Note: we only use this value to calculate the loan total and do not calculate the total from the checkout object line items.
 

Merchant object

user_confirmation_url

Required url

The customer goes to this URL after they confirm their loan.

A checkout_token is sent to this URL in the POST request. Use the checkout_token to authorize the charge before the customer is redirected to the order confirmation page.

Analytics tags and other query string parameters can be persisted here.

user_cancel_url

Required url

The customer goes to this URL if they exit the loan application process for any reason. Set this URL to your checkout payment page.

Analytics tags and other query string parameters can be persisted here.

user_confirmation_url_action

Optional string

Accepted values are GET and POST. Default is POST. Learn more.
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.
 

Shipping object

name

Required object

The customer’s first and last, or full name, which is used to pre-populate the account sign-up form.
address

Required object

The customer's address information, which is validated against public address service APIs.
phone_number

Optional string

The customer's phone number, which is validated against the Affirm checkout API. It must be a valid, U.S.-based, mobile phone number. Used to pre-populate the account sign-up form.
email

Optional list (? - string?)

The customer’s email address.
 

Billing object

name

Required object

The customer’s first and last, or full name, which is used to pre-populate the account sign-up form.
address

Required object

The customer's address information, which is validated against public address service APIs.
phone_number

Optional string

The customer's phone number, which is validated against the Affirm checkout API. It must be a valid, U.S.-based, mobile phone number. Used to pre-populate the account sign-up form.
email

Optional list (? - string?)

The customer’s email address.
 

Name object

first

Required string

The customer’s first name, which can contain multiple names (e.g., middle names).
last

Required string

The customer's last name.
full

Optional string

The customer’s full name. Required if first and last parameters are missing. String must contain at least two names.
 

Address object

line1

Required string

Valid U.S. street address, which will be verified by public address service APIs.
line2

Optional string

Apartment, suite, floor, etc.
city

Required string

City name, which will be verified by public address service APIs.
state

Required string

2-letter state ISO code or full state name, which will be verified by public address service APIs.
zipcode

Required string

Zipcode must match other provided address information and will be 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.
 

Item object

display_name

Required string

The display name of the item.
sku

Required string

The item SKU.
unit_price

Required integer

The item price, stated in USD cents (e.g., $100 = 10000).
qty

Required integer

The item quantity.
item_image_url

Required url

The item's product image URL.
item_url

Required url

The item's product description page URL.
 

Discount object

discount_amount

Required integer

The amount of the discount being applied, stated in USD cents (e.g., $100 = 10000).
discount_display_name

Required string

Your internal name for the discount.
 

Metadata object

shipping_type

Required string

The shipping method (e.g., UPS Ground).
entity_name

Optional string

Your internal sub-brand name. (?)
platform_type

Optional string

Your e-commerce platform (e.g., Magento).
webhook_session_id

Optional string

Customer or session specific ID used to reconcile incoming webhooks.
mode

Optional enum

Set to modal to enable the modal checkout flow (default uses redirect checkout flow).
 

Errors

The API returns an error object if the request produces any errors.

field

string

An incorrect or invalid value.
message

string

A friendly message describing the error.
code

string

A short code reference for the specific error.
type

string

The type of error being returned.
status_code

string

The returned HTTP status code.

 The code error field can have the following values.

auth-declined Charge authorization hold declined.
capture-greater-instrument Cannot capture charges on this instrument for more than the authorization hold amount.
capture-unequal-instrument Cannot capture charges on this instrument for an amount unequal to the authorization hold amount.
capture-voided Cannot capture voided charge.
partial-capture-instrument Cannot partially capture charges on this instrument.
refund-exceeded Exceeded maximum refund.
refund-uncaptured Cannot refund a charge that hasn't been captured.
refund-voided Cannot refund a voided charge.
capture-declined Charge capture declined.
capture-limit-exceeded Exceed maximum capture amount on charge.
expired-authorization Cannot capture a charge with an expired authorization hold.
refund-expired Charges on this instrument must be refunded within N days of capture.
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 an 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 Could not find the resource(s) specified in the request.

The type error field can have the following values.

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

The status_code error field can have the following values. 

400 Request fields resulted in an error.
401 Authorization was unsuccessful.
404 Could not find the requested resource(s).
50x An internal server issue resulted in an error.
  • Was this article helpful?