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 theTransactions
object retrieved from theAuthorize Transactions
response.
New query parameters
Key | Example | Description |
---|---|---|
|
| Possible comma-delimited values: |
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 |
---|---|---|
| string | Identifying string used to get idempotent responses. |
Request body parameters
Key | Data type | Description |
---|---|---|
| string | The This is named the |
| string | Possible comma-delimited values: |
| string | The merchant's internal order ID. |
| string | The merchant’s reference ID. |
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 |
---|---|---|
| string | Identifying string used to get idempotent responses. |
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. TheCharges
API accepted an empty string.
Key | Data type | Description |
---|---|---|
| integer | The amount to capture. |
| string | The merchant’s internal order ID. |
| string | The merchant’s reference ID. This is named the |
| string | The merchant’s shipping carrier. |
| string | The merchant’s tracking number. |
| object | Optional data object for your reference. |
Returns the transaction event object.
The following returned fields have been removed for the Transactions
endpoint:
Key | Data type | Description |
---|---|---|
| string | An order ID included in the checkout or authorization request. |
| 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 |
---|---|---|
| string | Identifying string used to get idempotent responses. |
Request body parameters
Key | Data type | Description |
---|---|---|
| integer | The amount to be refunded. |
| string | The merchant’s reference ID. |
| integer | The number of transaction events. |
| object | An optional data object for your reference. |
Returns the transaction event object.
The following returned fields have been removed for the Transactions
endpoint:
Key | Data type | Description |
---|---|---|
| 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 |
---|---|---|
| string | Identifying string used to get idempotent responses. |
Request body parameters
Key | Data type | Description |
---|---|---|
| string | Identifies the merchant's order ID. |
| string | The merchant’s reference ID. |
| string | The shipping carrier used to ship the items. |
shipping_confirmation | 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.