Create a charge

Use Affirm's Charges API and your server-side action to process charges.

Authorize charge

The Authorize endpoint creates a loan and reserves the funds. When you authorize, Affirm will generate a charge_id that you’ll use to reference the charge moving forward. You must authorize a charge to fully create it.

❗️

If you do not authorize a charge, it will not be considered active. This means the user will not see the loan, and you will not be able to capture the funds. For this reason, you should authorize the loan as soon as you receive a checkout token.

To authorize a charge, you'll need the checkout_token returned from your client integration.

curl https://sandbox.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": "{order_id}"}'
$endpoint = "https://sandbox.affirm.com/api/v2/charges";
$data = '{"checkout_token": "' . $_POST["checkout_token"] . '"}';
try {
 $response = callAffirm($endpoint, $data);
 // Handle the response
} catch (Exception $e) {
 // Handle the exception
}
using(var httpClient = new HttpClient()) {
	using(var request = new HttpRequestMessage(new HttpMethod("POST"), "https://sandbox.affirm.com/api/v2/charges")) {
		var base64authorization = Convert.ToBase64String(Encoding.ASCII.GetBytes("<public_api_key>:<private_api_key>"));
		request.Headers.TryAddWithoutValidation("Authorization", $ "Basic {base64authorization}");
		request.Content = new StringContent("{\"checkout_token\":\"<checkout_token>\"}");
		request.Content.Headers.ContentType = MediaTypeHeaderValue.Parse("application/json");
		var response = await httpClient.SendAsync(request);
		HttpContent responseContent = response.Content;
		using(var reader = new StreamReader(await responseContent.ReadAsStreamAsync())) {
			Console.WriteLine(await reader.ReadToEndAsync());
		}
		Console.ReadKey();
	}
}

You should receive a response that looks like this with the charge_id.

{
   "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"
         },
        "phone_number": "4153334567",
        "email": "[email protected]"
      },
      "discounts": {
        "RETURN5": {
          "discount_amount":    500,
          "discount_display_name": "Returning customer 5% discount"
        },
        "PRESDAY10": {
          "discount_amount":    1000,
          "discount_display_name": "President's Day 10% off"
        }
      }
   }
}

After successfully authorizing a charge and receiving the response object, your site should do the following:

  • Validate that the authorized amount equals the order total
  • Store the charge_id
  • Mark the order payment as pending

If the authorization fails, your site could potentially store this checkout attempt, as it is not required on our end.

📘

You should only authorize a given Affirm loan once for the entire amount of the
transaction being purchased. If you have a specific use case where this may be
difficult, please contact us at [email protected] or use the widget at the bottom of the page.

Capture a charge

Once an order has been fulfilled, you must send a Capture API request to Affirm in order to capture or settle the funds. You will want to perform this activity from your secure back-end systems. To capture a previous authorization, you'll need the charge_id provided in the Authorization API response. There aren't any required fields that need to be stored from the Capture response.

Capturing the funds is similar to capturing a credit card transaction. After capturing the loan, we do the following:

  • We notify the customer that the loan has been captured and that their first payment is due to Affirm in 30 days
  • Pay the merchant within 2-3 business days
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": "{order_id}", "shipping_carrier": "USPS", "shipping_confirmation": "1Z23223"}'
$endpoint = "https://sandbox.affirm.com/api/v2/charges";
$url = $endpoint . "/" . $_GET["id"] . "/capture";
$data = '';
try {
 $response = callAffirm($url, $data);
// Handle the response
} catch (Exception $e) {
 // Handle the exception

You will then receive back a response with the confirmation.

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