Split Capture API Reference
Split Capture uses our Transactions API which represents Affirm loans issued to the end-user. You can use this API to interact with transactions via the Transactions
object in order to change the state of that transaction, update metadata, or retrieve details.
Endpoints |
---|
POST v1/transactions |
POST v1/transactions/id/capture |
POST v1/transactions/id/void |
POST v1/transactions/id/refund |
POST v1/transactions/id/update |
GET v1/transactions/id |
Authorization
Authorizing a transaction occurs after a user completes the Affirm checkout flow and returns to the merchant site. Authorizing the charge generates a transaction_id
that will be used to reference it moving forward. You must authorize a transaction to fully create it.
Endpoint
<https://api.affirm.com/api/v1/transactions
>
Header parameters
Parameter |
---|
Idempotency-Key string REQUIRED: Unique identifiers pre-generated by the client and used by the server to recognize successive calls to the same endpoint. This is required for Split Capture and encouraged for single transaction functionality. |
Body parameters
Parameters |
---|
transaction_id string REQUIRED: Unique token used for authorization. Received to the user_confirmation_url |
order_id string Optional: Identifies the order within the merchant's order management system that this transaction corresponds to. Only returned in the response if included in the request. |
reference_id string Optional: A unique identifier that may be associated with each transaction event and reconciled with the system of record used by the merchant. |
Request
curl https://sandbox.affirm.com/api/v1/transactions \
-X POST \
-u "<public_api_key>:<private_api_key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <idempotency_value>" \
-d '{"transaction_id": "<checkout_token>","order_id": "<order_id_value>"}'
Response
"status": "authorized",
"amount_refunded": 0,
"provider_id": 1,
"created": "2020-06-12T20:32:09Z",
"order_id": "random",
"checkout_id": "LBQFHCCGETZF21GY",
"currency": "USD",
"amount": 99999,
"events": [
{
"currency": "USD",
"amount": 99999,
"type": "auth",
"id": "95FD5182N72JJ20Y",
"created": "2020-06-12T20:35:47Z"
}
],
"authorization_expiration": "2020-12-09T20:35:48Z",
"id": "R1CN-7IIP"
}
Capture
Capture the funds of an authorized transaction, similar to capturing a credit card transaction.
Endpoint
POST <https://api.affirm.com/api/v1/transactions/{transaction_id}/capture
>
Header parameters
Parameter |
---|
Idempotency-Key string REQUIRED: Unique identifiers pre-generated by the client and used by the server to recognize successive calls to the same endpoint. This is required for Split Capture and encouraged for single transaction functionality. |
Path parameters
Parameters |
---|
transaction_id string REQUIRED: A unique identifier representing the transaction. The value is an alphanumeric string of 9 or 12 characters in length, depending on whether it represents an installment loan or a lease, respectively. |
Body parameters
Parameters |
---|
amount int32 REQUIRED: Pass the amount to be captured. If you want to capture $50.80, the amount value would be 5080. |
order_id string Optional: Identifies the order within the merchant's order management system that this transaction corresponds to. Only returned in the response if included in the request. |
reference_id string Optional: A unique identifier that may be associated with each transaction event and reconciled with the system of record used by the merchant. |
shipping_carrier string Optional: The shipping carrier (e.g. “USPS”) used to ship the items. |
shipping_confirmation string Optional: The tracking number of the shipment. |
Request
curl https://sandbox.affirm.com/api/v1/transactions/{transaction_id}/capture \
-X POST \
-u "<public_api_key>:<private_api_key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <idempotency_value>" \
-d '{"amount":<enter_amount>, "order_id": "<order_id_value>", "shipping_carrier": "<carrier_value>", "shipping_confirmation": "<shipping_confirmation_value>"}'
Response
{
"fee": 22,
"created": "2020-06-12T20:38:18Z",
"order_id": "R1CN-7IIP",
"shipping_confirmation": "shipping_confirmation_id",
"shipping_carrier": "UPS",
"currency": "USD",
"amount": 1000,
"type": "split_capture",
"id": "02PWU4FLAU07GYW4"
}
Void
Cancel an authorized transaction.
Endpoint
POST <https://api.affirm.com/api/v1/transactions/{transaction_id}/void
>
Header parameters
Parameter |
---|
Idempotency-Key string REQUIRED: Unique identifiers pre-generated by the client and used by the server to recognize successive calls to the same endpoint. This is required for Split Capture and encouraged for single transaction functionality. |
Path parameters
Parameters |
---|
transaction_id string REQUIRED: A unique identifier representing the transaction. The value is an alphanumeric string of 9 or 12 characters in length, depending on whether it represents an installment loan or a lease, respectively. |
Body parameters
Parameters |
---|
amount int32 REQUIRED: Pass the amount to be voided. If you want to void $50.80, the amount value would be 5080. |
reference_id string Optional: A unique identifier that may be associated with each transaction event and reconciled with the system of record used by the merchant. |
Request
curl https://sandbox.affirm.com/api/v1/transactions/{transaction_id}/void \
-X POST \
-u "<public_api_key>:<private_api_key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <idempotency_value>" \
-d '{"amount":<enter_amount>}'
Response
{
"currency": "USD",
"amount": 2000,
"type": "refund_voided",
"id": "Y5NVH0OHZLHR20IA",
"created": "2020-06-12T20:38:58Z"
}
Refund
Refund a transaction.
Endpoint
POST <https://api.affirm.com/api/v1/transactions/{transaction_id}/refund
>
Header parameters
Parameter |
---|
Idempotency-Key string REQUIRED: Unique identifiers pre-generated by the client and used by the server to recognize successive calls to the same endpoint. This is required for Split Capture and encouraged for single transaction functionality. |
Path parameters
Parameters |
---|
transaction_id string REQUIRED: A unique identifier representing the transaction. The value is an alphanumeric string of 9 or 12 characters in length, depending on whether it represents an installment loan or a lease, respectively. |
Body parameters
Parameters |
---|
amount int32 REQUIRED: Pass the amount to be refunded. If you want to refund $50.80, the amount value would be 5080. |
reference_id string Optional: A unique identifier that may be associated with each transaction event and reconciled with the system of record used by the merchant. |
Request
curl https://sandbox.affirm.com/api/v1/transactions/{transaction_id}/refund \
-X POST \
-u "<public_api_key>:<private_api_key>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: <idempotency_value>" \
-d '{"amount":<enter_amount>}'
Response
{
"created": "2020-06-12T20:40:54Z",
"fee_refunded": 22,
"currency": "USD",
"amount": 1000,
"type": "refund",
"id": "DKJYFG2LYG264LGK"
}
Update
Update a transaction with new fulfillment or order information, such as shipment tracking number, shipping carrier, or order ID.
Endpoint
POST <https://api.affirm.com/api/v1/transactions/{transaction_id}
>
Path parameters
Parameters |
---|
transaction_id string REQUIRED: A unique identifier representing the transaction. The value is an alphanumeric string of 9 or 12 characters in length, depending on whether it represents an installment loan or a lease, respectively. |
Body parameters
Parameters |
---|
order_id string Optional: Identifies the order within the merchant's order management system that this transaction corresponds to. Only returned in the response if included in the request. |
reference_id string Optional: A unique identifier that may be associated with each transaction event and reconciled with the system of record used by the merchant. |
shipping string Optional: A Contact object containing the shipping information of the customer. |
shipping_carrier string Optional: The shipping carrier (e.g. “USPS”) used to ship the items. |
shipping_confirmation string Optional: The tracking number of the shipment. |
Request
curl https://sandbox.affirm.com/api/v1/transactions/{transaction_id} \
-X POST \
-u "<public_api_key>:<private_api_key>" \
-H "Content-Type: application/json" \
-d '{"order_id": "JLKM4321", "shipping_carrier": "USPS", "shipping_confirmation": "1Z23223", "shipping": {"name":{ "full": "John Doe"}, "address": {"line1": "325 Pacific Ave", "state": "CA", "city": "San Francisco", "zipcode": "94111", "country": "USA"}}}'
Response
{
"created": "2020-06-12T20:43:23Z",
"order_id": "R1CN-7IIP",
"shipping_confirmation": "shipping_confirmation_id_1591994603",
"shipping_carrier": "UPS",
"type": "update",
"id": "L88BIOQTCQNP2JAZ"
}
Read
Read the transaction information, current transaction status, and checkout data for one or more transactions. This is useful for updating your records or order management system with current transaction states before performing actions on them. It also allows you to keep your system in sync with Affirm if your staff manually manages loans in the merchant dashboard.
Endpoint
GET <https://api.affirm.com/api/v1/transactions/{transaction_id}
>
Path parameters
Parameters |
---|
transaction_id string REQUIRED: A unique identifier representing the transaction. The value is an alphanumeric string of 9 or 12 characters in length, depending on whether it represents an installment loan or a lease, respectively. |
Query parameters
Parameters |
---|
expand string A comma-separated set of related objects to expand in the response. Valid values are: events |
Request
curl https://sandbox.affirm.com/api/v1/transactions/{transaction_id} \
-X GET \
-u "<public_api_key>:<private_api_key>"
Response
{
"status": "partially_refunded",
"amount_refunded": 1000,
"provider_id": 1,
"created": "2020-06-12T20:32:09Z",
"order_id": "R1CN-7IIP",
"checkout_id": "LBQFHCCGETZF21GY",
"currency": "USD",
"amount": 99999,
"events": [],
"authorization_expiration": "2020-12-09T20:35:48Z",
"id": "R1CN-7IIP"
}
Updated 3 months ago