Affirm Disputes API
Operations for listing, retrieving, contesting, and closing payment disputes initiated by customers.
OpenAPI Specification
openapi: 3.1.0
info:
title: Affirm Checkout Authorization Disputes 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: Disputes
description: Operations for listing, retrieving, contesting, and closing payment disputes initiated by customers.
paths:
/disputes:
get:
operationId: listDisputes
summary: Affirm List Disputes
description: Returns a paginated list of all payment disputes for the authenticated merchant. Disputes represent customer-initiated challenges to Affirm transactions. Results include dispute status, associated transaction identifiers, dispute reason codes, and submission deadlines for evidence. Use filtering parameters to narrow results by status or date range.
tags:
- Disputes
parameters:
- name: status
in: query
required: false
description: Filter disputes by their current status.
schema:
type: string
enum:
- open
- closed
- won
- lost
example: open
- name: limit
in: query
required: false
description: Maximum number of dispute records to return per page.
schema:
type: integer
minimum: 1
maximum: 100
default: 20
example: 1
- name: cursor
in: query
required: false
description: Pagination cursor returned from a previous list response.
schema:
type: string
example: example_value
responses:
'200':
description: A list of dispute objects.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Dispute'
next_cursor:
type: string
description: Cursor token for fetching the next page of results.
examples:
listDisputes200Example:
summary: Default listDisputes 200 response
x-microcks-default: true
value:
data:
- id: {}
transaction_id: {}
charge_id: {}
status: {}
reason_code: {}
amount: {}
currency: {}
created: {}
evidence_due_by: {}
closed_at: {}
outcome: {}
evidence: {}
next_cursor: example_value
'401':
$ref: '#/components/responses/Unauthorized'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/disputes/{dispute_id}:
get:
operationId: getDispute
summary: Affirm Get a Dispute
description: Retrieves the full details of a specific dispute by its unique identifier. Returns dispute status, reason code, associated transaction and charge information, evidence submission deadline, evidence already submitted, and the dispute resolution outcome if the dispute has been closed.
tags:
- Disputes
parameters:
- $ref: '#/components/parameters/DisputeId'
responses:
'200':
description: Dispute object retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Dispute'
examples:
getDispute200Example:
summary: Default getDispute 200 response
x-microcks-default: true
value:
id: '500123'
transaction_id: '500123'
charge_id: '500123'
status: open
reason_code: example_value
amount: 1
currency: USD
created: '2025-03-15T14:30:00Z'
evidence_due_by: '2025-03-15T14:30:00Z'
closed_at: '2025-03-15T14:30:00Z'
outcome: merchant_won
evidence:
- {}
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/disputes/{dispute_id}/close:
post:
operationId: closeDispute
summary: Affirm Close a Dispute
description: Closes a dispute and transitions it to the merchant-lost state, indicating the merchant accepts the dispute and concedes to the customer's claim. This action is irreversible and results in the disputed amount being returned to the customer. Use this endpoint when the merchant chooses not to contest the dispute or determines the customer's claim is valid.
tags:
- Disputes
parameters:
- $ref: '#/components/parameters/DisputeId'
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
reason:
type: string
description: Optional explanation for why the merchant is closing the dispute without contesting it.
examples:
closeDisputeRequestExample:
summary: Default closeDispute request
x-microcks-default: true
value:
reason: example_value
responses:
'200':
description: Dispute closed successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Dispute'
examples:
closeDispute200Example:
summary: Default closeDispute 200 response
x-microcks-default: true
value:
id: '500123'
transaction_id: '500123'
charge_id: '500123'
status: open
reason_code: example_value
amount: 1
currency: USD
created: '2025-03-15T14:30:00Z'
evidence_due_by: '2025-03-15T14:30:00Z'
closed_at: '2025-03-15T14:30:00Z'
outcome: merchant_won
evidence:
- {}
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/disputes/{dispute_id}/evidence:
post:
operationId: submitDisputeEvidence
summary: Affirm Submit Dispute Evidence
description: Submits supporting evidence to contest an open dispute on behalf of the merchant. Evidence may include uploaded file references (obtained from the Files API), text descriptions, tracking information, and other supporting documentation. Evidence must be submitted before the dispute's evidence submission deadline. The submitted evidence is reviewed by Affirm to determine the dispute outcome.
tags:
- Disputes
parameters:
- $ref: '#/components/parameters/DisputeId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EvidenceRequest'
examples:
submitDisputeEvidenceRequestExample:
summary: Default submitDisputeEvidence request
x-microcks-default: true
value:
files:
- example_value
explanation: example_value
tracking_number: example_value
shipping_carrier: example_value
customer_communication: example_value
refund_policy_disclosure: example_value
responses:
'200':
description: Evidence submitted successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Dispute'
examples:
submitDisputeEvidence200Example:
summary: Default submitDisputeEvidence 200 response
x-microcks-default: true
value:
id: '500123'
transaction_id: '500123'
charge_id: '500123'
status: open
reason_code: example_value
amount: 1
currency: USD
created: '2025-03-15T14:30:00Z'
evidence_due_by: '2025-03-15T14:30:00Z'
closed_at: '2025-03-15T14:30:00Z'
outcome: merchant_won
evidence:
- {}
'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'
schemas:
Dispute:
type: object
description: Represents a payment dispute filed by a customer against an Affirm transaction, including its current status, reason, and any evidence submitted by the merchant.
properties:
id:
type: string
description: Unique identifier for this dispute.
example: '500123'
transaction_id:
type: string
description: The identifier of the Affirm transaction being disputed.
example: '500123'
charge_id:
type: string
description: The identifier of the charge associated with this dispute.
example: '500123'
status:
type: string
description: Current status of the dispute.
enum:
- open
- closed
- won
- lost
example: open
reason_code:
type: string
description: Standardized reason code categorizing the nature of the dispute (e.g., item_not_received, item_not_as_described, unauthorized).
example: example_value
amount:
type: integer
description: The disputed amount in cents.
example: 1
currency:
type: string
description: ISO 4217 currency code for the disputed amount.
example: USD
created:
type: string
format: date-time
description: Timestamp when this dispute was created, in RFC 3339 format.
example: '2025-03-15T14:30:00Z'
evidence_due_by:
type: string
format: date-time
description: Deadline by which the merchant must submit evidence to contest this dispute, in RFC 3339 format.
example: '2025-03-15T14:30:00Z'
closed_at:
type: string
format: date-time
nullable: true
description: Timestamp when this dispute was closed, if applicable.
example: '2025-03-15T14:30:00Z'
outcome:
type: string
nullable: true
description: Final outcome of the dispute after review. Only set when status is won or lost.
enum:
- merchant_won
- merchant_lost
example: merchant_won
evidence:
type: array
description: List of evidence items submitted by the merchant for this dispute.
items:
$ref: '#/components/schemas/EvidenceItem'
example:
- example_value
EvidenceRequest:
type: object
description: Request body for submitting evidence to contest a dispute. May include file references, textual explanations, and shipping/tracking details.
properties:
files:
type: array
description: Array of file identifiers uploaded via the Files API to attach as documentary evidence.
items:
type: string
example:
- example_value
explanation:
type: string
description: Textual explanation of the merchant's position and why the dispute should be decided in the merchant's favor.
example: example_value
tracking_number:
type: string
description: Shipment tracking number demonstrating that the order was delivered as expected.
example: example_value
shipping_carrier:
type: string
description: Name of the shipping carrier used for the disputed order.
example: example_value
customer_communication:
type: string
description: Description or summary of communications with the customer regarding the disputed order.
example: example_value
refund_policy_disclosure:
type: string
description: Description of the merchant's refund policy as shown to the customer at the time of purchase.
example: example_value
EvidenceItem:
type: object
description: A single piece of evidence associated with a dispute.
properties:
id:
type: string
description: Unique identifier for this evidence item.
example: '500123'
type:
type: string
description: Type of evidence (file, text, tracking).
enum:
- file
- text
- tracking
example: file
content:
type: string
description: For text evidence, the content of the explanation. For file evidence, the file identifier.
example: example_value
submitted_at:
type: string
format: date-time
description: Timestamp when this evidence was submitted, 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
parameters:
DisputeId:
name: dispute_id
in: path
required: true
description: The unique identifier of the dispute.
schema:
type: string
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