Review this guide for step-by-step instructions on how to switch from the Charges API to the Transactions API.

Introduction

Affirm is moving to a new post-origination API that has features such as Split Capture, Idempotency, and expanded error handling. The API has also included parameters to specify if the checkout or event details are needed, so that Affirm is not passing back unnecessary data.

To use the same functionality as the Charges endpoint, the following changes are required: change the URL base path, store and use the transaction_id, and add the expand parameters to get the transaction data being used. This guide outlines the Transactions API implementation details and provides notes that specify what has been added, changed, or removed from the Charges API.

GET Read Charge → GET Read Transaction

Old URL : GET /api/v2/charges/<charge_id>
New URL : GET /api/v1/transactions/

New Query Parameters

Key

Value

Expand

expand

Possible values separated by a comma:
events, checkout

expand=checkout
Or
expand=checkout,events

Returns the Transaction Object.

Expanded error handling for the following errors:

(This is not returned in Charges.)

  • Status Code: 404 - Error Message: The transaction could not be found.

POST Authorize Charge → POST Authorize Transaction

Old URL : POST /api/v2/charges
New URL : POST /api/v1/transactions

Request header parameters

Key

Value

Data type

Changes for Transactions

Idempotency-Key

Identifying string used to get idempotent responses.

*Optional string

(If Split Capture is configured in your merchant settings, the Idempotency-Key is required.)

New field

Request body parameters

Key

Value

Data type

Changes for Transactions

transaction_id

The checkout_id generated on the client.

string

This is named the checkout_token in the charges endpoint.

expand

Possible values separated by a comma:
events, checkout

Optional string

New field

order_id

The merchant’s internal order ID.

Optional string

reference_id

The merchant’s reference ID.

Optional string

New field

Returns the Transaction Object.

POST Capture Charge → POST Capture Transaction

Old URL : POST /api/v2/charges/<charge_id>/capture
New URL : POST /api/v1/transactions//capture

Request header parameters

KeyValueData typeChanges for Transactions
Idempotency-KeyIdentifying string used to get idempotent responses.Optional stringNew field

Request body parameters
(The request body must be null, an empty json object, or a json object with the following key/value pairs. Formerly, in the Charges API an empty string was accepted.)

KeyValueData typeChanges for Transactions
amountThe amount to capture.Optional integerNew field; Used for split capture.
order_idThe merchant’s internal order ID.Optional string
reference_idThe merchant’s reference ID.Optional stringThis is named the merchant_transaction_id in the charges endpoint.
shipping_carrierThe merchant’s shipping carrier.Optional string
shipping_confirmationThe merchant’s tracking number.Optional string
metadataOptional data object for your reference.Optional objectNew field

Returns the Transaction Event Object.

Returned fields that are no longer returned from the Charges endpoint

Fields that have been removed

KeyValueData typeChanges for Transactions
transaction_idID for the request.stringField removed

Expanded error handling for the following errors:

(These are not returned in Charges.)

  • Status Code: 404 - Error Message: The transaction could not be found.
  • Status Code: 403 - Error Message: The transaction cannot be captured or refunded while it is disputed.
  • Status Code: 403 - Error Message: Refund amount is required for a partially refunded transaction.
  • Status Code: 403 - Error Message: The refund amount exceeds the remaining loan balance.
  • Status Code: 403 - Error Message: The idempotency key provided has already been used.
  • Status Code: 403 - Error Message: This transaction cannot be refunded while the refund amount is negative.
  • Status Code: 403 - Error Message: The transaction is on the Virtual Card Network and may not be refunded by the Transaction API.
  • Status Code: 403 - Error Message: The transaction is authorized and may not be refunded. Try voiding the transaction instead.
  • Status Code: 403 - Error Message: The transaction has been voided and cannot be refunded.
  • Status Code: 403 - Error Message: The transaction is past its refundable period and cannot be refunded. Please contact [email protected] for assistance.
  • Status Code: 409 - Error Message: The transaction with this idempotency key is processing. Please wait to retry or use a different idempotency key.

POST Void Charge → POST Void Transaction

Old URL : POST /api/v2/charges/<charge_id>/void
New URL : POST /api/v1/transactions//void

Request header parameters

KeyValueData typeChanges for Transactions
Idempotency-KeyIdentifying string used to get idempotent responses.Optional stringNew field

Request body parameters

KeyValueData typeChanges for Transactions
amountThe amount to be voided.Optional integerNew field; Only used for Split Capture.
reference_idYour reference ID.Optional stringNew field
metadataOptional data object for your reference.Optional objectNew field

Returns the Transaction Event Object.

Returned fields that are no longer available from the Charges endpoint

Fields that have been removed

KeyValueData typeChanges for Transactions
transaction_idID for the request.stringField removed

Expanded error handling for the following errors:

(These are not returned in Charges.)

  • Status Code: 404 - Error Message: The transaction could not be found.
  • Status Code: 403 - Error Message: The transaction cannot be captured or refunded while it is disputed.
  • Status Code: 403 - Error Message: The transaction has been captured and may no longer be voided.
  • Status Code: 403 - Error Message: The transaction must be authorized before it may be voided.
  • Status Code: 403 - Error Message: The transaction has an expired authorization and may not be voided.
  • Status Code: 403 - Error Message: The transaction is on the Virtual Card Network and may not be voided by the Transaction API.
  • Status Code: 403 - Error Message: The transaction is partially refunded and may not be voided. Try fully refunding the transaction instead.
  • Status Code: 403 - Error Message: The transaction is fully refunded and does not have to be voided.
  • Status Code: 409 - Error Message: Void amount is not allowed for a merchant not supporting split capture.
  • Status Code: 409 - Error Message: The total amount to be voided cannot be greater than the total capturable balance.
  • Status Code: 409 - Error Message: The transaction with this idempotency key is processing. Please wait to retry or use a different idempotency key.

Transaction object

Attribute

Data type

Description

Changes for Transactions

currency

string

Three-letter ISO currency code, in uppercase.
Possible values:
USD,CAD.

id

string

Unique identifier for the object (or commonly referred as the loan id).

under_dispute

boolean

Whether the loan has been disputed.

user_id

string

ID of the customer this loan is for.

platform

string

TBD

details

object

See details reference.

Only included if the expand=checkout parameter is sent.

refundable

boolean

Whether the loan has been fully refunded. If the loan is only partially refunded, this attribute will still be true.

charge_event_count

integer

TBD

events

Array

An Array of events reference.

Only included if the expand=events parameter is sent.

pending

boolean

TBD

merchant_external_reference

string

Unique identifier for the object (or commonly referred as the loan id) set by the merchant.

status

string

The status of the loan is either authorized, captured, etc. Possible values:

  • opened
  • authorized
  • captured
  • disputed
  • refunded

order_id

string

Unique identifier for the object (or commonly referred as the loan id) set by the merchant. TBD - duplicate.

void

boolean

Whether the charge has been voided.

authorization_expiration

timestamp

TBD

This is named expires in the charges object.

payable

integer

TBD

merchant_id

string

Unique identifier for the merchant.

auth_hold

integer

Equals the amount in the loan that doesn't include the downpayment. Typically, the auth_hold and amount equal the same total, though in downpayment scenarios that can be different.

amount_refunded

integer

TBD

This is named refunded_amount in the charges object.

created

timestamp

TBD

is_instore

boolean

Whether the charge has been in-store.

amount

integer

Amount intended to be charged by this loan. A positive integer representing how much, in USD or CAD cents, to charge (e.g., 100 cents to charge $1.00).

is_marqeta_charge

boolean

TBD

balance

integer

Net amount of the loan, in cents.

financing_program

string

TBD

provider_id

integer

Possible Values
1,2,3

New field

remove_tax

boolean

Used for the Affirm Connect product to flag when the provider remits tax to the customer.

New field

Transaction event object

Attribute

Data type

Description

Changes for Transactions

amount

string

The total value of the transaction, including tax and shipping. The value is non-negative and is represented in the smallest currency unit, such as cents instead of dollars. If the type is captured, this field represents the amount captured. If the type is refund, this field represents the amount refunded, including the fee that was refunded.

created

string

The time when the transaction event was created. The value is formatted in RFC 3339.

currency

string

The local currency of the transaction with its being a valid subset of the ISO 4217 currency code.

fee

integer

The merchant fee.

fee_refunded

integer

Portion of the refunded amount that is subtracted from the merchant fee.

id

string

A unique identifier for the transaction event.

reference_id

string

An optional, unique identifier that is returned if it was sent by the merchant.

This is named merchant_transaction_id in the charges response.

type

string

Possible values:
-auth
-capture
-confirm
-refund
-update
-void