Affirm Settlement Events API

openapi: 3.1.0
info:
  title: Affirm Checkout Authorization Settlement Events API
  description: The Affirm Checkout API enables merchants to initiate and manage the Affirm buy now pay later checkout flow for customers at the point of purchase. It provides endpoints to create and store checkout sessions, read and update checkout objects, and resend checkout links via email or SMS. The API supports both redirect and direct checkout integration patterns. Once a customer authorizes a loan, the resulting checkout token is exchanged server-side to complete the transaction authorization via the Transactions API. Authentication uses HTTP Basic Authentication with the merchant's public and private API keys.
  version: '1.0'
  contact:
    name: Affirm Developer Support
    url: https://docs.affirm.com/developers/docs/development-quickstart
  termsOfService: https://www.affirm.com/legal/merchant-terms
servers:
- url: https://api.affirm.com/api/v1
  description: Production Server
- url: https://sandbox.affirm.com/api/v1
  description: Sandbox Server
security:
- basicAuth: []
tags:
- name: Settlement Events
  description: Operations for listing settlement events and summaries that track disbursement activity.
paths:
  /settlement_events:
    get:
      operationId: listSettlementEvents
      summary: Affirm List Settlement Events
      description: Returns a paginated list of settlement events representing individual disbursement line items from Affirm to the merchant. Each settlement event is tied to a transaction event and includes the net amount disbursed after fees. Used for financial reconciliation and accounting.
      tags:
      - Settlement Events
      parameters:
      - $ref: '#/components/parameters/PageLimit'
      - $ref: '#/components/parameters/PageCursor'
      responses:
        '200':
          description: A list of settlement event objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SettlementEvent'
                  next_cursor:
                    type: string
                    description: Cursor for the next page of results.
              examples:
                listSettlementEvents200Example:
                  summary: Default listSettlementEvents 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - id: {}
                      transaction_id: {}
                      transaction_event_id: {}
                      amount: {}
                      currency: {}
                      created: {}
                      type: {}
                    next_cursor: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /settlement_event_summaries:
    get:
      operationId: listSettlementEventSummaries
      summary: Affirm List Settlement Event Summaries
      description: Returns a paginated list of settlement event summary records that aggregate settlement activity by disbursement batch. Each summary includes the total amount disbursed, the date of the disbursement, and a count of associated settlement events. Used for high-level financial reconciliation.
      tags:
      - Settlement Events
      parameters:
      - $ref: '#/components/parameters/PageLimit'
      - $ref: '#/components/parameters/PageCursor'
      responses:
        '200':
          description: A list of settlement event summary objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SettlementEventSummary'
                  next_cursor:
                    type: string
                    description: Cursor for the next page of results.
              examples:
                listSettlementEventSummaries200Example:
                  summary: Default listSettlementEventSummaries 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - id: {}
                      total_amount: {}
                      currency: {}
                      event_count: {}
                      disbursed_at: {}
                    next_cursor: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  parameters:
    PageLimit:
      name: limit
      in: query
      required: false
      description: Maximum number of records to return per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    PageCursor:
      name: cursor
      in: query
      required: false
      description: Pagination cursor returned from a previous list response.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Unauthorized. Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    SettlementEventSummary:
      type: object
      description: An aggregated summary of settlement activity for a single disbursement batch from Affirm to the merchant.
      properties:
        id:
          type: string
          description: A unique identifier for this settlement event summary.
          example: '500123'
        total_amount:
          type: integer
          description: Total amount disbursed in this batch in the smallest currency unit.
          example: 1
        currency:
          type: string
          description: ISO 4217 currency code for this disbursement.
          example: USD
        event_count:
          type: integer
          description: Number of individual settlement events included in this batch.
          example: 1
        disbursed_at:
          type: string
          format: date-time
          description: Timestamp when the disbursement was initiated, in RFC 3339 format.
          example: '2025-03-15T14:30:00Z'
    SettlementEvent:
      type: object
      description: Represents a single disbursement line item from Affirm to the merchant, associated with a specific transaction event.
      properties:
        id:
          type: string
          description: A unique identifier for the settlement event.
          example: '500123'
        transaction_id:
          type: string
          description: The identifier of the transaction this settlement event belongs to.
          example: '500123'
        transaction_event_id:
          type: string
          description: The identifier of the specific transaction event that triggered this settlement.
          example: '500123'
        amount:
          type: integer
          description: Net disbursement amount in the smallest currency unit.
          example: 1
        currency:
          type: string
          description: ISO 4217 currency code for this settlement.
          example: USD
        created:
          type: string
          format: date-time
          description: Timestamp when this settlement event was created, in RFC 3339 format.
          example: '2025-03-15T14:30:00Z'
        type:
          type: string
          description: The type of settlement event corresponding to the transaction action.
          enum:
          - capture
          - refund
          - void
          example: capture
    Error:
      type: object
      description: Standard error response returned by the Affirm API.
      properties:
        status_code:
          type: integer
          description: HTTP status code of the error.
          example: 1
        code:
          type: string
          description: Machine-readable error code string.
          example: example_value
        message:
          type: string
          description: Human-readable description of the error.
          example: example_value
        field:
          type: string
          description: The specific field that caused the error, if applicable.
          example: example_value
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using the merchant's public API key as the username and private API key as the password, Base64-encoded as per RFC 7617.
externalDocs:
  description: Affirm Checkout API Reference
  url: https://docs.affirm.com/developers/reference/the-checkout-object