Skip to main content

Merchant Help

 

Affirm Merchant Help

Direct Checkout API

If you can't use our default method of using Affirm.js to create an Affirm checkout, you can use this Direct Checkout API to generate a redirect URL from your back-end. Your front-end would then redirect the customer to Affirm to complete their loan.

Methods

Checkout

Request

curl https://affirm.com/api/v2/checkout/direct/
     -X POST
     -u "<public_api_key>:<private_api_key>"
     -H "Content-Type: application/json"
     -d '{"checkout_object": "<checkout_object>"}'

URL

Sandbox: https://sandbox.affirm.com/api/v2/checkout/direct
Live: https://api.affirm.com/api/v2/checkout/direct

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_object object The checkout object describing the full customer order. Required

Response

The response to your request will contain the URL where you'll need to send the customer as a full-browser redirect and a checkout ID related to the request.

Status Response
200
{
  "redirect_url": "https://sandbox.affirm.com/checkout/ABCDEF123456/new/123456ABCDEF/",
  "checkout_id": "123456ABCDEF"
}

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. Required
billing object The customer contact information for billing. Optional
items list A list items the customer is purchasing. Each item is an object. Required
discounts hash 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. Default is 0. Required
tax_amount integer The total tax amount computed after all discounts have been applied. Default is 0. Required
total integer The total amount of the checkout, which determines the total amount charged to the user. 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
public_api_key string Your public API key. Required
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

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

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.

Examples

PHP

<?php
    $endpoint = "https://sandbox.affirm.com/api/v2/checkout/direct";
    $rawData = array( 
        "merchant" => array (
            "public_api_key" => "ABCDEF123456",
            "user_cancel_url" => "https://secure.merchant.com/affirm/cancel",
            "user_confirmation_url" => "https://secure.merchant.com/affirm/confirm",
        ),
        "items" => array (
            array (
                "display_name" => "Acme SLR-NG",
                "item_image_url" => "https://www.merchant.com/ACME-SLR-NG-01/item.png",
                "item_url" => "https://www.merchant.com/ACME-SLR-NG-01/",
                "qty" => "1",
                "sku" => "ACME-SLR-NG-01",
                "unit_price" => "10000"
            )
        ),
        "shipping" => array (
            "address" => array (
                "city" => "San Francisco",
                "line1" => "225 Bush St",
                "state" => "CA",
                "zipcode" => "94104"
            ),
            "name" => array (
                "full" => "Joe Consumer"
            )
        ),
        "total" => "10000"
    );
            
    $data = json_encode($rawData, JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT);
    $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 );
?>

Parse the returned JSON object and redirect the customer to the redirect_url.

{"redirect_url": "https://sandbox.affirm.com/checkout/ABCDEF123456/new/123456ABCDEF/", "checkout_id": "123456ABCDEF"}