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:
- Change the Sandbox and Production URLs:
- Sandbox:
- Production:
- Change the
URL base path - Store and use the
transaction_id - Add the
expandparameters to get the transaction data being used. - Add
country-codeto 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=checkoutOr 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: Refundamountis 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
| 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 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
| 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 |