openapi: 3.1.0
info:
  title: Affirm Checkout Authorization Cards 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: Cards
  description: Operations for managing virtual card numbers (VCN) issued via the Affirm Lite integration pattern.
paths:
  /cards/{id}:
    get:
      operationId: readCard
      summary: Affirm Read a Card
      description: Retrieves the details of a virtual card number (VCN) issued via Affirm Lite. Returns card number, expiration, CVV, and billing address information needed for payment processing through traditional card networks.
      tags:
      - Cards
      parameters:
      - $ref: '#/components/parameters/CardId'
      responses:
        '200':
          description: Card retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
              examples:
                readCard200Example:
                  summary: Default readCard 200 response
                  x-microcks-default: true
                  value:
                    id: '500123'
                    checkout_id: '500123'
                    status: active
                    number: example_value
                    cvv: example_value
                    expiration: example_value
                    billing:
                      address:
                        line1: {}
                        city: {}
                        state: {}
                        zipcode: {}
                        country: {}
                    amount: 1
                    currency: USD
                    created: '2025-03-15T14:30:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /cards/{id}/cancel:
    post:
      operationId: cancelCard
      summary: Affirm Cancel a Card
      description: Cancels a virtual card number (VCN) issued via Affirm Lite, rendering it unusable for further charges. Used when an order is cancelled or the card is no longer needed.
      tags:
      - Cards
      parameters:
      - $ref: '#/components/parameters/CardId'
      responses:
        '200':
          description: Card cancelled successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
              examples:
                cancelCard200Example:
                  summary: Default cancelCard 200 response
                  x-microcks-default: true
                  value:
                    id: '500123'
                    checkout_id: '500123'
                    status: active
                    number: example_value
                    cvv: example_value
                    expiration: example_value
                    billing:
                      address:
                        line1: {}
                        city: {}
                        state: {}
                        zipcode: {}
                        country: {}
                    amount: 1
                    currency: USD
                    created: '2025-03-15T14:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /cards/{id}/finalize:
    post:
      operationId: finalizeCard
      summary: Affirm Finalize a Card
      description: Finalizes a virtual card number (VCN), updating the card details with the final purchase amount and completing the Affirm Lite transaction lifecycle.
      tags:
      - Cards
      parameters:
      - $ref: '#/components/parameters/CardId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: integer
                  description: Final authorized amount in cents.
                order_id:
                  type: string
                  description: Merchant order identifier for this finalization.
            examples:
              finalizeCardRequestExample:
                summary: Default finalizeCard request
                x-microcks-default: true
                value:
                  amount: 1
                  order_id: '500123'
      responses:
        '200':
          description: Card finalized successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
              examples:
                finalizeCard200Example:
                  summary: Default finalizeCard 200 response
                  x-microcks-default: true
                  value:
                    id: '500123'
                    checkout_id: '500123'
                    status: active
                    number: example_value
                    cvv: example_value
                    expiration: example_value
                    billing:
                      address:
                        line1: {}
                        city: {}
                        state: {}
                        zipcode: {}
                        country: {}
                    amount: 1
                    currency: USD
                    created: '2025-03-15T14:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    Unauthorized:
      description: Unauthorized. Authentication credentials are missing or invalid.
      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'
    NotFound:
      description: Not found. The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    CardId:
      name: id
      in: path
      required: true
      description: The unique identifier of the virtual card.
      schema:
        type: string
  schemas:
    Card:
      type: object
      description: Represents an Affirm-issued virtual card number (VCN) used in the Affirm Lite integration pattern to process payments through traditional card networks.
      properties:
        id:
          type: string
          description: Unique identifier for this virtual card.
          example: '500123'
        checkout_id:
          type: string
          description: Checkout session identifier associated with this card.
          example: '500123'
        status:
          type: string
          description: Current status of the virtual card.
          enum:
          - active
          - cancelled
          - finalized
          example: active
        number:
          type: string
          description: Virtual card number (PAN).
          example: example_value
        cvv:
          type: string
          description: Card verification value.
          example: example_value
        expiration:
          type: string
          description: Card expiration date in MM/YY format.
          example: example_value
        billing:
          type: object
          description: Billing address associated with this virtual card.
          properties:
            address:
              type: object
              properties:
                line1:
                  type: string
                  description: Street address line 1.
                city:
                  type: string
                  description: City.
                state:
                  type: string
                  description: State code.
                zipcode:
                  type: string
                  description: ZIP or postal code.
                country:
                  type: string
                  description: ISO 3166-1 alpha-2 country code.
          example:
            address:
              line1: example_value
              city: example_value
              state: example_value
              zipcode: example_value
              country: example_value
        amount:
          type: integer
          description: Authorized amount on this virtual card in cents.
          example: 1
        currency:
          type: string
          description: ISO 4217 currency code.
          example: USD
        created:
          type: string
          format: date-time
          description: Card creation 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
  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