Transaction API

Release date: July 16, 2021

Aperçu

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

Clé	Exemple	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

Clé	Type de données	Description
`Idempotency-Key` optional	string	Identifying string used to get idempotent responses. This is a new field.

Request body parameters

Clé	Type de données	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

Clé	Type de données	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.

Clé	Type de données	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	objet	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:

Clé	Type de données	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

Clé	Type de données	Description
`Idempotency-Key` optional	string	Identifying string used to get idempotent responses. This is a new field.

Request body parameters

Clé	Type de données	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	objet	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:

Clé	Type de données	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

Clé	Type de données	Description
`Idempotency-Key` optional	string	Identifying string used to get idempotent responses. This is a new field.

Request body parameters

Clé	Type de données	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.
shippingconfirmation _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.