Affirm Authorization API

openapi: 3.2.0
info:
  title: Affirm Direct Authorization API
  description: The Affirm Direct API is a flexible integration that allows merchants to embed the full Affirm checkout and payment authorization flow directly into their website, giving complete control over the front-end user experience and back-end transaction processing logic.
  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: Authorization
  description: Server-side operations for authorizing Affirm transactions after a customer completes the checkout flow and a checkout token is returned.
paths:
  /transactions:
    post:
      operationId: authorizeDirectTransaction
      summary: Affirm Authorize a Transaction
      description: Exchanges a checkout token for a transaction authorization, completing the server-side portion of the Direct API flow. This call must be made from the merchant server after the browser-side affirm.js returns a checkout token via the user_confirmation_url callback. The authorization places a hold on the customer's Affirm credit. The resulting transaction must be captured within the authorization window to transfer funds to the merchant.
      tags:
      - Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - checkout_token
              properties:
                checkout_token:
                  type: string
                  description: The checkout token returned by the Affirm checkout flow via the user_confirmation_url callback. This token is single-use and expires after a short window.
                order_id:
                  type: string
                  description: The merchant's internal order identifier to associate with this authorization for reconciliation purposes.
            examples:
              authorizeDirectTransactionRequestExample:
                summary: Default authorizeDirectTransaction request
                x-microcks-default: true
                value:
                  checkout_token: abc123def456abc123def456abc123de
                  order_id: '500123'
      responses:
        '200':
          description: Transaction authorized successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
              examples:
                authorizeDirectTransaction200Example:
                  summary: Default authorizeDirectTransaction 200 response
                  x-microcks-default: true
                  value:
                    id: '500123'
                    checkout_id: '500123'
                    order_id: '500123'
                    status: authorized
                    amount: 1
                    amount_refunded: 1
                    currency: USD
                    created: '2025-03-15T14:30:00Z'
                    authorization_expiration: '2025-03-15T14:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /files:
    post:
      operationId: uploadFile
      summary: Affirm Upload a File
      description: Uploads a file to Affirm's servers for use as dispute evidence. Returns a file identifier that can be referenced when submitting evidence via the Disputes API. Supported file types include images (JPEG, PNG) and documents (PDF).
      tags:
      - Authorization
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                  description: The file to upload as binary data.
                purpose:
                  type: string
                  description: The intended purpose of the uploaded file.
                  enum:
                  - dispute_evidence
      responses:
        '200':
          description: File uploaded successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileObject'
              examples:
                uploadFile200Example:
                  summary: Default uploadFile 200 response
                  x-microcks-default: true
                  value:
                    id: '500123'
                    filename: Example Merchant
                    size: 1
                    content_type: standard
                    purpose: example_value
                    created: '2025-03-15T14:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /files/{id}:
    get:
      operationId: downloadFile
      summary: Affirm Download a File
      description: Downloads a previously uploaded file by its identifier. Returns the raw file content with the appropriate content type header.
      tags:
      - Authorization
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the file to download.
        schema:
          type: string
        example: '500123'
      responses:
        '200':
          description: File content returned successfully.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    NotFound:
      description: Not found. The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request. The request body or parameters are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized. Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    FileObject:
      type: object
      description: Represents a file uploaded to Affirm's servers.
      properties:
        id:
          type: string
          description: Unique identifier for the uploaded file.
          example: '500123'
        filename:
          type: string
          description: Original filename of the uploaded file.
          example: Example Merchant
        size:
          type: integer
          description: File size in bytes.
          example: 1
        content_type:
          type: string
          description: MIME type of the uploaded file.
          example: standard
        purpose:
          type: string
          description: Intended purpose of the file.
          example: example_value
        created:
          type: string
          format: date-time
          description: Upload timestamp in RFC 3339 format.
          example: '2025-03-15T14:30:00Z'
    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
    Transaction:
      type: object
      description: Represents an Affirm payment transaction at any point in its lifecycle.
      properties:
        id:
          type: string
          description: Unique identifier for this transaction.
          example: '500123'
        checkout_id:
          type: string
          description: Identifier of the checkout session that originated this transaction.
          example: '500123'
        order_id:
          type: string
          description: Merchant's internal order identifier.
          example: '500123'
        status:
          type: string
          description: Current lifecycle status of the transaction.
          enum:
          - authorized
          - captured
          - voided
          - refunded
          - partially_refunded
          example: authorized
        amount:
          type: integer
          description: Original authorized amount in cents.
          example: 1
        amount_refunded:
          type: integer
          description: Cumulative amount refunded in cents.
          example: 1
        currency:
          type: string
          description: ISO 4217 currency code.
          example: USD
        created:
          type: string
          format: date-time
          description: Creation timestamp in RFC 3339 format.
          example: '2025-03-15T14:30:00Z'
        authorization_expiration:
          type: string
          format: date-time
          description: Timestamp after which the authorization can no longer be captured.
          example: '2025-03-15T14:30:00Z'
  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 Direct API Overview
  url: https://docs.affirm.com/payments/docs/direct-api-overview