--- updatedAt: 2026-08-17T16:30:44.000Z agentTools: siteIndex: https://docs.affirm.com/llms.txt projectIndex: https://docs.affirm.com/developers/llms.txt --- # Authorize Transaction Authorizes a transaction. After a user completes the Affirm checkout flow and returns to the merchant site, the merchant should call the Authorize Transaction endpoint. Authorizing a transaction generates a unique `id` that will be used as a reference moving forward. **New Required Fields** The new required fields are the following: * `currency`: Three-letter ISO currency code in uppercase. Accepted currencies are USD, CAD, and GBP. * `items`: Various details of the item being sold. * `shipping`: The shipping details. * `total`: The total amount of the checkout in the lowest denomination of the currency. (e.g., 100 cents to charge $1.00). # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Merchant Transaction API", "version": "1.0.0" }, "servers": [ { "url": "https://sandbox.affirm.com/api/v1" }, { "url": "https://api.affirm.com/api/v1" } ], "security": [ { "basicAuth": [] } ], "paths": { "/transactions": { "post": { "tags": [ "Transactions API" ], "summary": "Authorize Transaction", "description": "Authorizes a transaction. After a user completes the Affirm checkout flow and returns to the merchant site, the merchant should call the Authorize Transaction endpoint. Authorizing a transaction generates a unique `id` that will be used as a reference moving forward.", "operationId": "authorize_transaction", "parameters": [ { "name": "Idempotency-Key", "in": "header", "description": "Unique identifier pre-generated by the client and used by the server to recognize successive calls to the same endpoint. This is required for Split Capture and encouraged for single transaction functionality. Note: If a request fails or times out, use the same idempotency key to retry the operation without risk of double-processing. For details, see the [Idempotency section on About Split Capture](https://docs.affirm.com/payments/docs/split-capture#idempotency).", "required": false, "schema": { "type": "string" } } ], "requestBody": { "description": "The request body used to create a transaction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizeRequest" } } } }, "responses": { "200": { "description": "HTTP 200 OK", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Transaction2" } } } }, "400": { "description": "HTTP 400 Bad Request", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorBadRequest" } } } }, "401": { "description": "HTTP 401 Unauthorized", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorUnauthorized" } } } }, "404": { "description": "HTTP 404 Not Found", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/ErrorNotFound" } } } } }, "x-swagger-router-controller": "affirm.http.api.merchant.transaction.v1.api" } } }, "components": { "schemas": { "ErrorBadRequest": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message.", "example": "Bad Request" }, "status_code": { "type": "integer", "description": "The HTTP status code.", "example": 400 }, "type": { "type": "string", "description": "The error type.", "example": "BAD_REQUEST" }, "code": { "type": "string", "description": "The error type.", "example": "BAD_REQUEST" } } }, "ErrorNotFound": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message.", "example": "Not Found" }, "status_code": { "type": "integer", "description": "The HTTP status code.", "example": 404 }, "type": { "type": "string", "description": "The error type.", "example": "NOT_FOUND" }, "code": { "type": "string", "description": "The error type.", "example": "NOT_FOUND" } } }, "ErrorUnauthorized": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message.", "example": "Unauthorized" }, "status_code": { "type": "integer", "description": "The HTTP status code.", "example": 401 }, "type": { "type": "string", "description": "The error type.", "example": "UNAUTHORIZED" }, "code": { "type": "string", "description": "The error type.", "example": "UNAUTHORIZED" } } }, "AuthorizeRequest": { "type": "object", "properties": { "expand": { "type": "string", "description": "A comma-separated set of related objects to expand in the response.", "example": "checkout" }, "order_id": { "maxLength": 128, "minLength": 1, "type": "string", "description": "Identifies the order within the merchant's order management system that this transaction corresponds to. It is only returned in the response if included in the request.", "example": "order_125" }, "reference_id": { "maxLength": 128, "minLength": 1, "type": "string", "description": "An optional, unique identifier that may be associated with each transaction event and reconciled with the system of record used by the merchant.", "example": "202307011027" }, "transaction_id": { "maxLength": 16, "minLength": 9, "type": "string", "description": "Required. A unique identifier representing the checkout.", "example": "1234567890ABCDEF" }, "currency": { "type": "string", "description": "Three-letter ISO currency code in uppercase.", "example": "USD" }, "total": { "type": "integer", "description": "The total amount of the checkout in the lowest denomination of the currency.", "example": 1999 }, "shipping": { "$ref": "#/components/schemas/AuthorizeShippingAddress" }, "items": { "type": "array", "properties": {}, "description": "An array of various details of the item being sold.", "x-nullable": true, "items": { "$ref": "#/components/schemas/AuthorizeItemsSKU" } } } }, "AuthorizeShippingAddress": { "type": "object", "properties": { "name": { "type": "object", "properties": { "first": { "type": "string", "description": "Customer's first name. Can also contain multiple words (for middle names).", "example": "John" }, "last": { "type": "string", "description": "Customer's last name.", "example": "Doe" }, "full": { "type": "string", "description": "Required if `first` and `last` keys are missing. The string must contain at least two words.", "example": "John Doe" } } }, "address": { "type": "object", "properties": { "line1": { "type": "string", "description": "Address line 1 (e.g., street, PO Box, or company name).", "example": "123 Example Street" }, "line2": { "type": "string", "description": "Address line 2 (The apartment", "example": "Apt 123" }, "city": { "type": "string", "description": "City, district, suburb, town, or village.", "example": "San Francisco" }, "state": { "type": "string", "description": "State, county, province, or region.", "example": "CA" }, "zipcode": { "type": "string", "description": "ZIP or postal code.", "example": 94107 }, "country": { "type": "string", "description": "Two-letter country code (ISO 3166-1 alpha-2).", "example": "US" } } }, "phone_number": { "type": "string", "description": "The phone number of the customer.", "example": 1234567890 }, "email": { "type": "string", "description": "The email address of the customer.", "example": "test@example.com", "x-nullable": true } } }, "AuthorizeItemsSKU": { "type": "object", "title": "Item object", "properties": { "item": { "properties": { "display_name": { "type": "string", "description": "The display name of the product.", "example": "Awesome Pants" }, "sku": { "type": "string", "description": "The product SKU.", "example": "ABC-123" }, "unit_price": { "type": "integer", "description": "The item price amount in USD or CAD cents.", "example": 1999 }, "qty": { "type": "integer", "description": "The item quantity expressed as an integer.", "example": 3 }, "item_image_url": { "type": "string", "description": "The item's product image URL.", "example": "http://merchantsite.com/images/awesome-pants.jpg" }, "item_url": { "type": "string", "description": "The item's product description page URL.", "example": "http://merchantsite.com/products/awesome-pants.html" } } } } }, "Transaction2": { "type": "object", "properties": { "status": { "type": "string", "description": "The status of the transaction.", "example": "authorized" }, "amount_refunded": { "type": "integer", "description": "The amount refunded back to the customer from this transaction. The value may be less than the total amount financed if a partial refund was issued. The value is non-negative and is represented in the smallest currency unit, such as cents instead of dollars.", "example": 5000 }, "provider_id": { "type": "integer", "description": "A unique identifier of the provider that is financing the transaction.", "example": 1 }, "amount": { "type": "integer", "description": "The original amount financed to the customer in this transaction. The value is non-negative and is represented in the smallest currency unit, such as cents instead of dollars.", "example": 20000 }, "authorization_expiration": { "type": "string", "description": "The time when the transaction can no longer be authorized. The value is formatted in RFC 3339.", "example": "2019-01-01T00:00:00.000Z" }, "checkout_id": { "type": "string", "description": "A unique identifier representing the transaction’s checkout ID.", "example": "HTSZAGURU7PZ8ZAG" }, "id": { "type": "string", "description": "A unique identifier representing the transaction’s loan or charge ID.", "example": "ABCD-1234" }, "events": { "type": "array", "properties": {}, "description": "An array of TransactionEvent objects.", "x-nullable": true, "items": { "$ref": "#/components/schemas/TransactionEvent8" } }, "remove_tax": { "type": "boolean", "description": "Indicates if tax was paid by the provider (Affirm, LTO). Used by platform integrations to remove tax.", "example": true }, "currency": { "type": "string", "description": "The local currency of the transaction with its being a valid subset of the ISO 4217 currency code.", "example": "USD" }, "order_id": { "maxLength": 128, "minLength": 1, "type": "string", "description": "Identifies the order within the merchant's order management system that this transaction corresponds to.", "example": "order_125" }, "created": { "type": "string", "description": "The time when the transaction was created. The value is formatted in RFC 3339.", "example": "2019-01-01T00:00:00.000Z" } } }, "TransactionEvent8": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of event, such as auth, auth_expired, capture, charge_off, confirm, confirmation_expired, expire_authorization, expire_confirmation, refund, split_capture, update, void, partial_void, and refund_voided.", "example": "refund" }, "currency": { "type": "string", "description": "The local currency of the transaction with its being a valid subset of the ISO 4217 currency code.", "example": "USD" }, "created": { "type": "string", "description": "The time when the transaction event was created. The value is formatted in RFC 3339.", "example": "2019-01-01T00:00:00.000Z" }, "amount": { "type": "integer", "description": "The total value of the transaction event, 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 capture, this field represents the amount captured. If the type is refund, this field represents the amount refunded, including the fee that was refunded.", "example": 20000 }, "fee": { "type": "integer", "description": "The correctness of this value may be inaccurate for certain loan types, refer to the settlement reports for the accurate merchant fee information for accounting and reconciliation purposes.", "example": 500 }, "id": { "type": "string", "description": "A unique ID for the transaction event.", "example": "1234567890ABCDEF" } } } }, "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true, "samples-enabled": true } } ``` # Sibling pages * [List Transactions](https://docs.affirm.com/developers/reference/list_transactions.md) * [List Transaction Events](https://docs.affirm.com/developers/reference/list_transaction_events.md) * [Read Transaction](https://docs.affirm.com/developers/reference/read_transaction.md) * [Update Transaction](https://docs.affirm.com/developers/reference/update_transaction.md) * [Capture Transaction](https://docs.affirm.com/developers/reference/capture_transaction.md) * [Refund Transaction](https://docs.affirm.com/developers/reference/refund_transaction.md) * [Void Transaction](https://docs.affirm.com/developers/reference/void_transaction.md) * [List Settlement Events](https://docs.affirm.com/developers/reference/list_settlement_events.md) * [List Settlement Event Summaries](https://docs.affirm.com/developers/reference/list_settlement_event_summaries.md)