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.


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 recording 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 instalment 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 recording 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 instalment 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 recording 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 instalment 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 recording 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 instalment 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 recording 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 instalment 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"
}