Skip to main content

Merchant Help

 

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.

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"}'

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

Parameter Type Description
public_api_key string Your public API key. Required
private_api_key string Your private API key. Required
checkout_token string A unique token used to authorize a charge. The checkout_token is POSTed to user_confirmation_url after the customer confirms their loan. Required
order_id string Your internal order ID that corresponds to the charge. Required

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.

Status Response
200
{
   "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"
        }
      }
   }
}
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.

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.

Request

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

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

Parameter Type Description
public_api_key string Your public API key. Required
private_api_key string Your private API key. Required
checkout_id string The ID returned from the direct checkout API response. Also referred to as the checkout_token. Required

 Response

Status Response
200
{
   "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.

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"

URL

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

Options

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

Data

Parameter Type Description
public_api_key string Your public API key. Required
private_api_key string Your private API key. Required
charge_id 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. Optional
limit integer Number of charges to include in the response. Optional
before string Returns a list of charges that were created before the given charge ID. Optional
after string Returns a list of charges that were created after the given charge ID. Optional

Response

Status Response
200
{
   "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

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"}

URL

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

Options

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

Data

Parameter Type Description
public_api_key string Your public API key. Required
private_api_key string Your private API key. Required
charge_id string The charge ID. Required
order_id string Your internal Order ID stored for your future reference. Optional
shipping_carrier string The shipping carrier used to ship the items in the charge. Optional
shipping_confirmation string The tracking number for the shipment. Optional

Response

Status Response
200
{
"fee": 600,
"created": "2016-03-18T00:03:44Z",
"order_id": "JKLM4321",
"currency": "USD",
"amount": 6100,
"type": "capture",
"id": "O5DZHKL942503649",
"transaction_id": "6dH0LrrgUaMD7Llc"
}
400 Capture failed.
401 Unauthorized.
402 Authorization expired.

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

Request

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

URL

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

Options

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

Data

Parameter Type Description
public_api_key string Your public API key. Required
private_api_key string Your private API key. Required
charge_id string The charge ID. Required

Response

Status Response
200
{
"type": "void",
"id": "N5E9OXSIDJ8TKZZ9",
"transaction_id": "G9TqohxBlRPWTGB2",
"created": "2014-03-17T22:52:16Z",
"order_id": "JLKM4321"
}
400 Authorization failed.
401 Unauthorized.
402 Checkout token expired.

Refund

Refund a charge. (add link to refund info)

Request

URL

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

Options

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

Data

Parameter Type Description
public_api_key string Your public API key. Required
private_api_key string Your private API key. Required
charge_id string The charge ID. Required
amount 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). Optional

Response

Status Response
200
{
  "created": "2014-03-18T19:20:30Z",
  "fee_refunded": 1500,
  "amount": 50000,
  "type": "refund",
  "id": "OWA49MWUCA29SBVQ",
  "transaction_id": "r86zdkHONPcaiVJJ"
}
400 Refund request failed.
401 Unauthorized.
402 Authorization expired.

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/checkout/<charge_id>/update
Live: https://api.affirm.com/api/v2/checkout/<charge_id>/update

Options

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

Data

Parameter Type Description
public_api_key string Your public API key. Required
private_api_key string Your private API key. Required
charge_id string The charge ID. Required
order_id string Your internal Order ID stored for your future reference. Optional
shipping_carrier string The shipping carrier used to ship the items in the charge. Optional
shipping_confirmation string The tracking number for the shipment. Optional
shipping object The customer contact information for shipping. Optional

Response

Status Response
200
{  
   "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.

Parameter Type Description
merchant object The URLs for when a customer either confirms a loan or exits the loan process and an optional external name. Required
shipping object The customer contact information for shipping. Optional
billing object The customer contact information for billing. Required
items object A list items the customer is purchasing. Each item is an object. Required
discounts object A hash of coupon codes to discount objects. Passed discounts must have a name and positive integer dollar amount. Optional
metadata 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. Optional
order_id string Your internal Order ID stored for your future reference. Optional
shipping_amount integer The total shipping amount, stated in USD cents (e.g., $100 = 10000). Default is 0. Required
tax_amount integer The total tax amount computed after all discounts have been applied, stated in USD cents (e.g., $100 = 10000). Default is 0. Required
total 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. Required

Merchant object

Parameter Type Description
user_confirmation_url 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.

Required

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

Required

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

Shipping object

Parameter Type Description
name object The customer’s first and last, or full name, which is used to pre-populate the account sign-up form. Required
address object The customer's address information, which is validated against public address service APIs. Required
phone_number 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. Optional
email list (? - string?) The customer’s email address. Optional

Billing object

Parameter Type Description
name object The customer’s first and last, or full name, which is used to pre-populate the account sign-up form. Required
address object The customer's address information, which is validated against public address service APIs. Required
phone_number 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. Optional
email list (? - string?) The customer’s email address. Optional

Name object

Parameter Type Description
first string The customer’s first name, which can contain multiple names (e.g., middle names). Required
last string The customer's last name. Required
full string The customer’s full name. Required if first and last parameters are missing. String must contain at least two names. Optional
first string The customer’s first name, which can contain multiple names (e.g., middle names). Required

Address object

Parameter Type Description
line1 string Valid U.S. street address, which will be verified by public address service APIs. Required
line2 string Apartment, suite, floor, etc. Optional
city string City name, which will be verified by public address service APIs. Required
state string 2-letter state ISO code or full state name, which will be verified by public address service APIs. Required
zipcode string Zipcode must match other provided address information and will be verified by public address service APIs. Required
country string If provided, must be 'US' or 'USA' (3-letter ISO code). Affirm is only available to U.S. residents. Optional

Item object

Parameter Type Description
display_name string The display name of the item. Required
sku string The item SKU. Required
unit_price integer The item price, stated in USD cents (e.g., $100 = 10000). Required
qty integer The item quantity. Required
item_image_url url The item's product image URL. Required
item_url url The item's product description page URL. Required

Discount object

Parameter Type Description
discount_amount integer The amount of the discount being applied, stated in USD cents (e.g., $100 = 10000). Required
discount_display_name string Your internal name for the discount. Required

Metadata object

Parameter Type Description
shipping_type string The shipping method (e.g., UPS Ground). Required
entity_name string Your internal sub-brand name. (?) Optional
platform_type string Your e-commerce platform (e.g., Magento). Optional
webhook_session_id string Customer or session specific ID used to reconcile incoming webhooks. Optional
mode enum Set to modal to enable the modal checkout flow (default uses redirect checkout flow). Optional

Errors

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

Error Field Type Description
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.

Code Error Field Values Description
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.

Type Error Field Values Description
invalid-request A generic error that indicates invalid request inputs.
unauthorized Invalid API keys.

The status_code error field can have the following values. 

Status_Code Error Field Values Description
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.