AFaffirm
Transactions API

Authorize Transaction

Changed on

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.

post/transactions

Request

  • Base URL
    https://sandbox.affirm.com/api/v1
  • URL
    https://sandbox.affirm.com/api/v1/transactions
  • Auth
    HTTP basic

Headers

Idempotency-Keystring

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.

Request body

expandstring

A comma-separated set of related objects to expand in the response.

order_idstring

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.

reference_idstring

An optional, unique identifier that may be associated with each transaction event and reconciled with the system of record used by the merchant.

transaction_idstring

Required. A unique identifier representing the checkout.

currencystring

Three-letter ISO currency code in uppercase.

totalinteger

The total amount of the checkout in the lowest denomination of the currency.

Example request

{
  "expand": "checkout",
  "order_id": "order_125",
  "reference_id": "202307011027",
  "transaction_id": "1234567890ABCDEF",
  "currency": "USD",
  "total": 1999,
  "shipping": {
    "name": {
      "first": "John",
      "last": "Doe",
      "full": "John Doe"
    },
    "address": {
      "line1": "123 Example Street",
      "line2": "Apt 123",
      "city": "San Francisco",
      "state": "CA",
      "country": "US"
    },
    "email": "test@example.com"
  },
  "items": [
    {
      "item": {
        "display_name": "Awesome Pants",
        "sku": "ABC-123",
        "unit_price": 1999,
        "qty": 3,
        "item_image_url": "http://merchantsite.com/images/awesome-pants.jpg",
        "item_url": "http://merchantsite.com/products/awesome-pants.html"
      }
    }
  ]
}

Response

HTTP 200 OK

statusstring

The status of the transaction.

amount_refundedinteger

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.

provider_idinteger

A unique identifier of the provider that is financing the transaction.

amountinteger

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.

authorization_expirationstring

The time when the transaction can no longer be authorized. The value is formatted in RFC 3339.

checkout_idstring

A unique identifier representing the transaction’s checkout ID.

idstring

A unique identifier representing the transaction’s loan or charge ID.

remove_taxboolean

Indicates if tax was paid by the provider (Affirm, LTO). Used by platform integrations to remove tax.

currencystring

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

order_idstring

Identifies the order within the merchant's order management system that this transaction corresponds to.

createdstring

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

Example response

{
  "status": "authorized",
  "amount_refunded": 5000,
  "provider_id": 1,
  "amount": 20000,
  "authorization_expiration": "2019-01-01T00:00:00.000Z",
  "checkout_id": "HTSZAGURU7PZ8ZAG",
  "id": "ABCD-1234",
  "events": [
    {
      "type": "refund",
      "currency": "USD",
      "created": "2019-01-01T00:00:00.000Z",
      "amount": 20000,
      "fee": 500,
      "id": "1234567890ABCDEF"
    }
  ],
  "remove_tax": true,
  "currency": "USD",
  "order_id": "order_125",
  "created": "2019-01-01T00:00:00.000Z"
}

Changes

  • 360ca87d6c3eRevision changes
    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status