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

Introduction

In order to support Affirm's global integration, it is required to move to a new post-origination API that also provides 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 and support Affirm's global integration, the following changes are required:

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/<transaction_id>

New query parameters

KeyValueExpand
expandPossible values separated by a comma:
events, checkout
expand=checkout
Or
expand=checkout,events

Returns the Transaction Object.

New request header

KeyValueData Type
country-codeRequired param to identify the country in which Affirm is used and uses an "alpha-3" three-letter country code. Supported countries are the United States (USA) and Canada (CAN).String required

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

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

(If Split Capture is configured in your merchant settings, the Idempotency-Key is required.)
New field
country-codeRequired param to identify the country in which Affirm is used and uses an "alpha-3" three-letter country code. Supported countries are the United States (USA) and Canada (CAN).String requiredNew field

Request body parameters

KeyValueData typeChanges for Transactions
transaction_idThe checkout_id generated on the client.stringThis is named the checkout_token in the charges endpoint.
expandPossible values separated by a comma:
events, checkout
Optional stringNew field
order_idThe merchant’s internal order ID.Optional string
reference_idThe merchant’s reference ID.Optional stringNew 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/<transaction_id>/capture

Request header parameters

KeyValueData typeChanges for Transactions
Idempotency-KeyIdentifying string used to get idempotent responses.Optional stringNew field
country-codeRequired param to identify the country in which Affirm is used and uses an "alpha-3" three-letter country code. Supported countries are the United States (USA) and Canada (CAN).String requiredNew 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 Refund Charge → POST Refund Transaction

Old URL: POST /api/v2/charges/<charge_id>/refund
*New URL: POST /api/v1/transactions/<transaction_id>/refund

Request header parameters

KeyValueData typeChanges for Transactions
Idempotency-KeyIdentifying string used to get idempotent responses.Optional stringNew field
country-codeRequired param to identify the country in which Affirm is used and uses an "alpha-3" three-letter country code. Supported countries are the United States (USA) and Canada (CAN).Required 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
transaction_event_countAn optional, expected transaction event countOptional integerNew 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 idempotency key provided has already been used.
  • Status Code: 403 - Error Message: The transaction is past its capturable period and cannot be captured. Please contact [email protected] for assistance.
  • Status Code: 403 - Error Message: The transaction has been voided and may no longer be captured.
  • Status Code: 403 - Error Message: The transaction has already been voided.
  • Status Code: 403 - Error Message: The transaction must be authorized before it may be captured.
  • Status Code: 409 - Error Message: Charges on this instrument cannot be captured for an amount that is greater than the total capturable balance.
  • Status Code: 409 - Error Message: Charges on this instrument cannot be captured for an amount unequal to authorization hold amount.
  • Status Code: 409 - Error Message: Charges on this instrument cannot be captured for an amount that is not equal to 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.

POST Void Charge → POST Void Transaction

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

Request header parameters

KeyValueData typeChanges for Transactions
Idempotency-KeyIdentifying string used to get idempotent responses.Optional stringNew field
country-codeRequired param to identify the country in which Affirm is used and uses an "alpha-3" three-letter country code. Supported countries are the United States (USA) and Canada (CAN).Required 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.

GET List Charges → GET List Transactions

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

Request header parameters

KeyValueData typeChanges for Transactions
Has_Strict_ValidationUsed to denote whether client-side strict validation is used. Defaults to True if no param provided.Optional booleanNew field
country-codeRequired param to identify the country in which Affirm is used and uses an "alpha-3" three-letter country code. Supported countries are the United States (USA) and Canada (CAN).Required stringNew field

Request body parameters

KeyValueData typeChanges for Transactions
transaction_typeType of transaction to be listed, list one of charge or leaseString requiredNew field
allow_marqeta_viewIf we want to allow marqeta view, only relevant for chargesOptional booleanNew field
beforeOptional end ARI of query, used during pagination. Mutually exclusive with the after query parameter—that is, only specify one of after or before in one request. We need the Loan ARI which is represented by the id in the resultOptional string
afterOptional start ARI of query, used during pagination. Mutually exclusive with the before query parameter—that is, only specify one of after or before in one requestOptional string
limitMax number of transactions to list per page. Default is 20. The max limit is 100Optional string
before_dateEnd date of query (MM-DD-YYYY). This date is inclusive. For example, if you request loans before 01-28-22, all loans created on that date will be includedOptional stringNew field
after_dateStart date of query (MM-DD-YYYY). This date is inclusive. For example, if you request loans after 01-28-22, all loans created on that date will be includedOptional stringNew field
before_timestampUnix timestamp representing the end time of the queryOptional stringNew field
queryString to filter results on. Filters include order ID, transaction ID, status, amount, customer email, name, and phone number (only for charges)Optional stringNew field
merchant_idOptional ARI of merchant issuing the list requestOptional stringNew field
expandA comma-separated set of related objects to expand in the response. Allowed value is checkoutOptional stringNew field

GET List Charge Events → GET List Transaction Events

Old URL: GET /api/v2/charges/events
New URL: GET /api/v1/transactions/events

Request header parameters

KeyValueData typeChanges for Transactions
country-codeRequired param to identify the country in which Affirm is used and uses an "alpha-3" three-letter country code. Supported countries are the United States (USA) and Canada (CAN).Required stringNew field

Request body parameters

KeyValueData typeChanges for Transactions
transaction_typeType of transaction to be listed, list one of charge or leaseRequired string
transaction_event_typeType of transaction events to be listed, list one of authorize, capture, refund, void, or allRequired string
limitMax number of transaction events to list per page. Default is 5Optional string
before_dateEnd date of queryOptional string
after_dateStart date of queryOptional string
before_ariOptional end event ARI of query, used during pagination. Mutually exclusive with the after_ari query parameter - i.e. only one of after_ari or before_ari can be specified in one requestOptional stringNew field
after_ariOptional start event ARI of query, used during pagination. Mutually exclusive with the before_ari query parameter - i.e. only one of after_ari or before_ari can be specified in one requestOptional stringNew field
merchant_idOptional ARI of merchant issuing the list events requestOptional stringNew field

Transaction object

AttributeData typeDescriptionChanges for Transactions
currencystringThree-letter ISO currency code, in uppercase.
Possible values:
USD,CAD.
idstringUnique identifier for the object (or commonly referred as the loan id).
under_disputebooleanWhether the loan has been disputed.
user_idstringID of the customer this loan is for.
platformstringTBD
detailsobjectSee details reference.Only included if the expand=checkout parameter is sent.
refundablebooleanWhether the loan has been fully refunded. If the loan is only partially refunded, this attribute will still be true.
charge_event_countintegerTBD
eventsArrayAn Array of events reference.Only included if the expand=events parameter is sent.
pendingbooleanTBD
merchant_external_referencestringUnique identifier for the object (or commonly referred as the loan id) set by the merchant.
statusstringThe status of the loan is either authorized, captured, etc. Possible values:

- opened
- authorized
- captured
- disputed
- refunded
order_idstringUnique identifier for the object (or commonly referred as the loan id) set by the merchant. TBD - duplicate.
voidbooleanWhether the charge has been voided.
authorization_expirationtimestampTBDThis is named expires in the charges object.
payableintegerTBD
merchant_idstringUnique identifier for the merchant.
auth_holdintegerEquals 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_refundedintegerTBDThis is named refunded_amount in the charges object.
createdtimestampTBD
is_instorebooleanWhether the charge has been in-store.
amountintegerAmount 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_chargebooleanTBD
balanceintegerNet amount of the loan, in cents.
financing_programstringTBD
provider_idintegerPossible Values
1,2,3
New field
remove_taxbooleanUsed for the Affirm Connect product to flag when the provider remits tax to the customer.New field

Transaction event object

AttributeData typeDescriptionChanges for Transactions
amountstringThe 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.
createdstringThe time when the transaction event was created. The value is formatted in RFC 3339.
currencystringThe local currency of the transaction with its being a valid subset of the ISO 4217 currency code.
feeintegerThe merchant fee.
fee_refundedintegerPortion of the refunded amount that is subtracted from the merchant fee.
idstringA unique identifier for the transaction event.
reference_idstringAn optional, unique identifier that is returned if it was sent by the merchant.This is named merchant_transaction_id in the charges response.
typestringPossible values:
-auth
-capture
-confirm
-refund
-update
-void