Authorize and Capture Transactions

Authorize transaction

The Authorize resource endpoint creates a loan and reserves the funds. When you authorize a transaction, Affirm generates a unique id that you can use to reference the transaction. You must authorize a transaction to fully create it.

1936 — This represents the authorize and capture flow.

❗️
If you do not authorize a transaction, it is not considered active. This means the user cannot see the loan, and you cannot capture the funds. For this reason, you should authorize the loan as soon as you receive a checkout_token.

To authorize a transaction, you need to pass the checkout_token returned from your client integration into the transaction_id parameter:

curl https://api.global.sandbox.affirm.com/api/v1/transactions
     -X POST
     -u "{public_api_key}:{private_api_key}"
     -H "Content-Type: application/json"
     -H "country-code: CAN"
     -d '{"transaction_id": "{checkout_token}","order_id": "{order_id}"}'

$endpoint = "https://sandbox.affirm.com/api/v1/transactions";
$data = '{"transaction_id": "' . $_POST["transactions_id"] . '"}';
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/v1/transactions")) {
		var base64authorization = Convert.ToBase64String(Encoding.ASCII.GetBytes("<public_api_key>:<private_api_key>"));
		request.Headers.TryAddWithoutValidation("Authorization", $ "Basic {base64authorization}");
		request.Content = new StringContent("{\"transaction_id\":\"<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 id:

{
    "status": "authorized",
    "amount_refunded": 0,
    "provider_id": 1,
    "created": "2021-06-23T23:25:55Z",
    "order_id": "ABC123",
    "checkout_id": "7WYDR0M83CGE47GJ",
    "currency": "CAN",
    "amount": 49999,
    "events": [
        {
            "currency": "CAN",
            "amount": 49999,
            "type": "auth",
            "id": "7M8T1AMJP01FLI6B",
            "created": "2021-06-23T23:26:28Z"
        }
    ],
    "remove_tax": false,
    "authorization_expiration": "2021-07-23T23:26:28Z",
    "id": "AMLC-5X0W"
}

If the authorization is successful and you receive the response object, your site:

Validates that the authorized amount equals the order total.
Stores the charge_id
Marks the order payment as pending.

If the authorization fails, your site can potentially store the checkout attempt. It is not required on Affirm's end.

📘
You may 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 transaction

Once an order has been fulfilled, you must send a Capture API request to Affirm to capture or settle the funds. Perform this activity from your secure back-end systems. To capture an authorized transaction, you need the id provided in the Authorization API response. There aren't 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:

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://api.global.sandbox.affirm.com/api/v1/transactions/{id}/capture 
     -X POST
     -u {public_api_key}:{private_api_key}"
     -H "Content-Type: application/json"
     -H "country-code: CAN"
     -d '{"order_id": "{order_id}", "shipping_carrier": "USPS", "shipping_confirmation": "1Z23223"}'

$endpoint = "https://sandbox.affirm.com/api/v1/transactions";
$url = $endpoint . "/" . $_GET["id"] . "/capture";
$data = '';
try {
 $response = callAffirm($url, $data);
// Handle the response
} catch (Exception $e) {
 // Handle the exception

You then receive a response with the confirmation.

{
    "fee": 1500,
    "created": "2021-06-23T23:27:13Z",
    "order_id": "XYZ123",
    "currency": "CAN",
    "amount": 49999,
    "reference_id": "6789",
    "type": "capture",
    "id": "QU9IEPR45ZN97AK6"
}