About Split Capture

Capture different parts of a multi-item order at different points in time.

Overview

With Split Capture, you can collect or "capture" funds at checkout for individual items as they're shipped. This makes it easy to recognize revenue at the appropriate times for your Affirm transaction.

How Split Capture works


Understanding how Split Capture works will help you implement a simple checkout structure to incrementally handle orders containing multiple items that may not ship at the same time. You'll read about the following details in this guide:

Authorization

At the start of the loan, you’ll use the Transaction API to send a single authorization request, which will authorize the entire loan. This creates an authorization window to capture funds in increments you’ll control later.

Authorization window

The authorization window is defined as the number of days you have to capture funds.

Authorization expiry

Capture requests will only be approved during the authorization window. Once the authorization period elapses, we’ll void any uncollected funds and return them to the customer. You’ll receive an email 7 days before the authorization expiration date with a list of loans close to expiration, and loans with uncollected funds.

Multiple captures

You can initiate multiple Capture requests within a specified authorization window. After authorizing the full purchase amount, you'll use the Capture API to pass us the specified funds to be captured in the amount parameter. You can send Capture requests as many times as needed within the authorization window as long as the total captured doesn't exceed the authorized amount.

Error handling

We’ve built a robust structure for Split Capture that supports the following:

  • The ability to make multiple capture calls without generating errors
  • Established checkpoints to identify potential duplicate requests
  • Idempotency, which is further explained here

Handling partially captured refunds

Refunds work the same way as our standard Direct API integration and you can process them using the Refund API. If you’ve already shipped an item and captured the funds, initiate a refund for the captured amount and we’ll credit those funds back to the loan.

❗️

Refunding captured funds

  • Once you refund an amount, you cannot capture it again.
  • If the loan is in the Captured state and you don't pass an amount, the entire loan will be refunded.

Partial voids

When you initiate Split Capture requests and know that a specific amount won’t be captured before authorization expires, call the Void endpoint for the specified amount of funds that will not be captured. After initiating a void, we’ll credit the specified amount back to the customer’s loan.

🚧

Additional notes

  • Voids can be completed at any time during the auth window if there is an authorized but uncaptured balance on the loan.
  • If you don't pass an amount in the Void request, the currently authorized amount will be voided. This only applies if the entire order is cancelled and the full loan amount is in an Authorized state.

Idempotency

The Split Capture API supports idempotency by using idempotency keys which make multiple calls to the same endpoint without causing an error. Idempotency keys are unique identifiers pre-generated by the client and used by the server to recognize successive calls to the same endpoint; these keys are required to employ the Split Capture API. This is useful when utilizing Split Capture and needing to repeat requests, or if the client fails to receive a successful response and you need to retry the request. For example, if you initiate a Capture Transaction request and don’t receive a response, you can use the same unique idempotency key to retry the request and ensure it won’t be interpreted as a duplicate.

To perform an idempotent request, add an Idempotency-Key header to the request. The key value should be unique enough to positively identify a single operation you initiated over the last 30 days. Split Capture idempotency functions by storing the response and status code of the initial request sent for a given idempotency key. Subsequent requests using the same key will result in the same success or failure response.