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 anamount
, 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 canceled and the full loan amount is in anAuthorized
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.
Updated 10 months ago