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:

Change the Sandbox and Production URLs:
- Sandbox:
  - (old)https://sandbox.affirm.com/api/v2/charges
  - (new)https://api.global-sandbox.affirm.com/api/v1/transactions
- Production:
  - (old) https://api.affirm.com/api/v2/charges
  - (new) https://api.global.affirm.com/api/v1/transactions
Change the URL base path
Store and use the transaction_id
Add the expand parameters to get the transaction data being used.
Add country-code to the request header where 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

Key	Value	Expand
`expand`	Possible values separated by a comma: `events, checkout`	`expand`=`checkout` Or `expand`=`checkout,events`

Returns the Transaction Object.

New request header

Key	Value	Data Type
`country-code`	Required 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

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

country-code

Required 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

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

Request header parameters

Key	Value	Data type	Changes for Transactions
`Idempotency-Key`	Identifying string used to get idempotent responses.	Optional string	New field
`country-code`	Required 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	New 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.)

Key	Value	Data type	Changes for Transactions
`amount`	The amount to capture.	Optional integer	New field; Used for split capture.
`order_id`	The merchant’s internal order ID.	Optional string
`reference_id`	The merchant’s reference ID.	Optional string	This is named the `merchant_transaction_id` in the charges endpoint.
`shipping_carrier`	The merchant’s shipping carrier.	Optional string
`shipping_confirmation`	The merchant’s tracking number.	Optional string
`metadata`	Optional data object for your reference.	Optional object	New field

Returns the Transaction Event Object.

Returned fields that are no longer returned from the Charges endpoint

Fields that have been removed

Key	Value	Data type	Changes for Transactions
`transaction_id`	ID for the request.	string	Field 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: Refundamount 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 contactmerchanthelp@affirm.com 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

Key	Value	Data type	Changes for Transactions
`Idempotency-Key`	Identifying string used to get idempotent responses.	Optional string	New field
`country-code`	Required 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 string	New field

Request body parameters

Key	Value	Data type	Changes for Transactions
`amount`	The amount to be voided.	Optional integer	New field; Only used for Split Capture.
`reference_id`	Your reference ID.	Optional string	New field
`metadata`	Optional data object for your reference.	Optional object	New field
`transaction_event_count`	An optional, expected transaction event count	Optional integer	New field

Returns the Transaction Event Object.

Returned fields that are no longer available from the Charges endpoint

Fields that have been removed

Key	Value	Data type	Changes for Transactions
`transaction_id`	ID for the request.	string	Field removed

Expanded error handling for the following errors:

(These arenot 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 contactmerchanthelp@affirm.com 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

Key	Value	Data type	Changes for Transactions
`Idempotency-Key`	Identifying string used to get idempotent responses.	Optional string	New field
`country-code`	Required 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 string	New field

Request body parameters

Key	Value	Data type	Changes for Transactions
`amount`	The amount to be voided.	Optional integer	New field; Only used for Split Capture.
`reference_id`	Your reference ID.	Optional string	New field
`metadata`	Optional data object for your reference.	Optional object	New field

Returns the Transaction Event Object.

Returned fields that are no longer available from the Charges endpoint

Fields that have been removed

Key	Value	Data type	Changes for Transactions
`transaction_id`	ID for the request.	string	Field 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

Key	Value	Data type	Changes for Transactions
`Has_Strict_Validation`	Used to denote whether client-side strict validation is used. Defaults to True if no param provided.	Optional boolean	New field
`country-code`	Required 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 string	New field

Request body parameters

Key	Value	Data type	Changes for Transactions
`transaction_type`	Type of transaction to be listed, list one of `charge` or `lease`	String required	New field
`allow_marqeta_view`	If we want to allow marqeta view, only relevant for charges	Optional boolean	New field
`before`	Optional 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 result	Optional string
`after`	Optional 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 request	Optional string
`limit`	Max number of transactions to list per page. Default is 20. The max limit is 100	Optional string
`before_date`	End 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 included	Optional string	New field
`after_date`	Start 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 included	Optional string	New field
`before_timestamp`	Unix timestamp representing the end time of the query	Optional string	New field
`query`	String to filter results on. Filters include `order ID`, `transaction ID`, `status`, `amount`, `customer email`, `name`, and `phone number` (only for charges)	Optional string	New field
`merchant_id`	Optional ARI of merchant issuing the list request	Optional string	New field
`expand`	A comma-separated set of related objects to expand in the response. Allowed value is `checkout`	Optional string	New 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

Key	Value	Data type	Changes for Transactions
`country-code`	Required 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 string	New field

Request body parameters

Key	Value	Data type	Changes for Transactions
`transaction_type`	Type of transaction to be listed, list one of `charge` or `lease`	Required string
`transaction_event_type`	Type of transaction events to be listed, list one of `authorize`, `capture`, `refund`, `void`, or `all`	Required string
`limit`	Max number of transaction events to list per page. Default is 5	Optional string
`before_date`	End date of query	Optional string
`after_date`	Start date of query	Optional string
`before_ari`	Optional 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 request	Optional string	New field
`after_ari`	Optional 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 request	Optional string	New field
`merchant_id`	Optional ARI of merchant issuing the list events request	Optional string	New field

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