Transaction API

Release date: July 16, 2021

Overview

Affirm has moved to the new Transactions API, an improved post-origination API. Transactions was initially utilized to support Affirm Connect, a unified interface to process online payments financed by installment loans serviced by Affirm and leases serviced by a lease-to-own (LTO) provider in partnership with Affirm.

While there are some similar functionalities to the Charges API, Transactions includes additional features such as Split Capture, idempotency, and expanded error handling. Additionally, the api/v1/transaction endpoint lets you programmatically authorize, capture, refund, or void various payment options processed by Affirm.

What's changed?

This section provides details on the differences between the Transactions and Charges APIs.

GET Read Charge → GET Read Transaction

Charges URL : GET /api/v2/charges/<charge_id>
Transactions URL : GET /api/v1/transactions/<id>

📘
Note that the id used in this endpoint is returned from the Transactions object retrieved from the Authorize Transactions response.

New query parameters

Key	Example	Description
`expand`	`expand=checkout` Or `expand=checkout,events`	Possible comma-delimited values: `events`, `checkout`

Returns the Transaction object.

POST Authorize Charge → POST Authorize Transaction

Charges URL : POST /api/v2/charges
Transactions URL : POST /api/v1/transactions

Request header parameters

Key	Data type	Description
`Idempotency-Key` optional	string	Identifying string used to get idempotent responses. This is a new field.

Request body parameters

Key	Data type	Description
`transaction_id` required	string	The `checkout_id` generated on the client. This is named the `checkout_token` in the `Charges` endpoint.
`expand` optional	string	Possible comma-delimited values: `events`, `checkout` This is a new field.
`order_id` optional	string	The merchant's internal order ID.
`reference_id` optional	string	The merchant’s reference ID. This is a new field.

Returns the Transaction object.

POST Capture Charge → POST Capture Transaction

Charges URL : POST /api/v2/charges/<charge_id>/capture
Transactions URL : POST /api/v1/transactions/<id>/capture

Request header parameters

Key	Data type	Description
`Idempotency-Key` optional	string	Identifying string used to get idempotent responses. This is a new field.

Request body parameters

📘
Note that the request body must be null, an empty json object, or a json object with the key/value pairs in the table below. The Charges API accepted an empty string.

Key	Data type	Description
`amount` optional	integer	The amount to capture. This is a new field used for Split Capture.
`order_id` optional	string	The merchant’s internal order ID.
`reference_id` optional	string	The merchant’s reference ID. This is named the `merchant_transaction_id` in the `Charges` endpoint.
`shipping_carrier` optional	string	The merchant’s shipping carrier.
`shipping_confirmation` optional	string	The merchant’s tracking number.
`metadata` optional	object	Optional data object for your reference. This is a new field.

Returns the transaction event object.

The following returned fields have been removed for the Transactions endpoint:

Key	Data type	Description
`order_id` optional	string	An order ID included in the checkout or authorization request.
`transaction_id`	string	The ID for the request.

POST Refund Charge → POST Refund Transaction

Charges URL : POST /api/v2/charges/<charge_id>/refund
Transactions URL : POST /api/v1/transactions/<id>/refund

Request header parameters

Key	Data type	Description
`Idempotency-Key` optional	string	Identifying string used to get idempotent responses. This is a new field.

Request body parameters

Key	Data type	Description
`amount` optional	integer	The amount to be refunded.
`reference_id` optional	string	The merchant’s reference ID. This is a new field.
`transaction_event_count` optional	integer	The number of transaction events. This is a new field.
`metadata` optional	object	An optional data object for your reference. This is a new field.

Returns the transaction event object.

The following returned fields have been removed for the Transactions endpoint:

Key	Data type	Description
`transaction_id`	string	The ID for the request.

POST Update Charge → POST Update Transaction

Charges URL : POST /api/v2/charges/<charge_id>/update' Transactions URL : POST /api/v1/transactions/`

Request header parameters

Key	Data type	Description
`Idempotency-Key` optional	string	Identifying string used to get idempotent responses. This is a new field.

Request body parameters

Key	Data type	Description
`order_id` optional	string	Identifies the merchant's order ID.
`reference_id` optional	string	The merchant’s reference ID. This is a new field.
`shipping_carrier` optional	string	The shipping carrier used to ship the items.
shipping_confirmation optional	string	The tracking number of the shipment.

Expanded error handling

We've expanded error handling for Transactions. See Errors in our API Reference for additional information.