improved

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.