added

Transactions API

Release date: July 30, 2019


We're excited to announce the Transaction API. The Transaction API provides a unified interface to process online payments financed by the following consumer lending products:

  • Installment loans serviced by Affirm
  • Leases serviced by a lease-to-own (LTO) provider in partnership with Affirm

While the /api/v2/charges endpoint only provides support for processing payments financed by installment loans, the api/v1/transaction endpoint lets you programmatically authorize, capture, refund, or void various payment options processed by Affirm. 

Backward-incompatible changes

This section provides details on backward-incompatible (breaking) changes when upgrading from api/v2/charges to api/v1/transactions.  If you're using any fields that have been removed in your existing order creation and management process, your integration may break.

Charge object

We've renamed the Charge object to the Transaction object. With this upgrade, the following fields from the Charge object have been removed or changed:

  • The auth_hold field has been removed.
  • The balance field has been removed.
  • The charge_event_count field has been removed.
  • The checkout_id field has been added.
  • The details field has been renamed to checkout and made optional. This will only be included as part of the response to read_transaction if the request includes the expand parameter.
  • The expires field has been renamed to authorization_expiration.
  • The financing_progam field has been removed.
  • The is_instore field has been removed.
  • The is_marqeta_charge field has been removed.
  • The merchant_id field has been removed.
  • The merchant_external_reference field has been removed. This is equivalent to the order_id field.
  • The payable field has been removed.
  • The pending field has been removed. This is equivalent to the value of the status field being authorized.
  • The platform field has been removed.
  • The order_id field no longer accepts integers as a value. The expected value is a string.
  • The refundable field has been removed.
  • The refunded_amount field has been renamed to amount_refunded.
  • The under_dispute field has been removed. This is equivalent to the value of the status field being disputed.
  • The resolve_by field has been removed.
  • The user_id field has been removed.
  • The void field has been removed. This is equivalent to the value of the status field being voided.

ChargeEvent object

  • Renamed ChargeEvent object to the TransactionEvent object 
  • Removed the transaction_id field in favor of using reference_id as the reconciling identifier

Authorize charge endpoint

  • Renamed the Authorize charge endpoint to Authorize transaction
  • Changed the relative URL from /api/v2/charges to /api/v1/transactions
  • Renamed the merchant_transaction_id parameter to reference_id

Capture charge endpoint

  • Renamed the Capture charge endpoint to Capture transaction
  • Updated the relative URL from /api/v2/charges/<charge_id/capture to /api/v1/transactions/<transaction_id>/capture
  • Renamed the merchant_transaction_id parameter to reference_id
  • Doesn't return fees in the response for a transaction_id

Refund charge endpoint

  • Renamed the Refund charge endpoint to Refund transaction 
  • Updated the relative URL from /api/v2/charges/<charge_id>/refund to /api/v1/transactions/<transaction_id>/refund
  • The merchant_transaction_id parameter has been renamed to reference_id
  • Doesn't return fees in the response for a transaction_id

Update charge endpoint

  • Renamed the Update charge endpoint to Update transaction
  • Updated the relative URL from /api/v2/charges/<charge_id/update to /api/v1/transactions/<transaction_id>/update
  • Added the entire Transaction object to the response instead of a subset of fields 

Void charge endpoint

  • Renamed the Void charge endpoint to Void transaction
  • Updated the relative URL from /api/v2/charges/<charge_id>/void to /api/v1/transactions/<transaction_id>/void
  • The merchant_transaction_id parameter has been renamed to reference_id