API Reference for Split Capture

Overview

Split Capture uses the Transactions API which represents Affirm loans issued to the end-user. You can use the Transactions API to interact with transactions via the Transactions object to change the state of a 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"
}