{ "openapi": "3.1.0", "info": { "title": "Platforms (Connect) API", "version": "1.0.0", "description": "The Chargeflow Platform API enables partners to integrate with Chargeflow and manage connected merchant accounts. Use this API to manage merchant accounts, configure integrations." }, "security": [ { "apiKey": [] } ], "tags": [ { "name": "Disputes", "description": "Disputes management endpoints" }, { "name": "Webhooks Events", "description": "Webhook event notifications" } ], "servers": [ { "url": "https://api.chargeflow.io", "description": "Production server" } ], "paths": { "/public/2024-03-18/disputes": { "get": { "tags": ["Disputes"], "summary": "Get Disputes", "description": "Note: This endpoint is not supported for platforms. Please use the new endpoint at /public/2025-04-01/disputes", "parameters": [ { "in": "query", "name": "limit", "description": "Maximum number of disputes to return in a single response", "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 15, "description": "Maximum number of disputes to return in a single response", "examples": [15] }, "example": "10" }, { "in": "query", "name": "offset", "description": "Number of disputes to skip for pagination", "schema": { "type": "number", "minimum": 0, "default": 0, "description": "Number of disputes to skip for pagination", "examples": [0] }, "example": "0" }, { "in": "query", "name": "dateCreatedFrom", "description": "Filter disputes created after this date (ISO 8601 format)", "schema": { "type": "string", "description": "Filter disputes created after this date (ISO 8601 format)", "examples": ["2024-01-01T00:00:00Z"] } }, { "in": "query", "name": "dateCreatedTo", "description": "Filter disputes created before this date (ISO 8601 format)", "schema": { "type": "string", "description": "Filter disputes created before this date (ISO 8601 format)", "examples": ["2024-03-18T23:59:59Z"] } }, { "in": "query", "name": "amountFrom", "description": "Filter disputes with amount greater than or equal to this value", "schema": { "type": "number", "minimum": 0, "default": 0, "description": "Filter disputes with amount greater than or equal to this value", "examples": [100] } }, { "in": "query", "name": "amountTo", "description": "Filter disputes with amount less than or equal to this value", "schema": { "type": "number", "minimum": 0, "default": 1000, "description": "Filter disputes with amount less than or equal to this value", "examples": [1000] } }, { "in": "query", "name": "statusNames", "description": "Filter disputes by status (comma-separated values)", "schema": { "type": "string", "description": "Filter disputes by status (comma-separated values)", "examples": ["needs_response"], "enum": [ "won", "lost", "refunded", "under_review", "warning_under_review", "needs_response", "warning_needs_response", "warning_awaiting_response", "awaiting_response", "warning_won", "appealable", "insured", "open", "action_required", "processing" ] } }, { "in": "query", "name": "reason", "description": "Filter disputes by reason (comma-separated values)", "schema": { "type": "string", "description": "Filter disputes by reason (comma-separated values)", "examples": ["fraud"], "enum": [ "bank_cannot_process", "check_returned", "credit_not_processed", "customer_initiated", "debit_not_authorized", "duplicate", "general", "incorrect_account_details", "insufficient_funds", "product_not_received", "product_unacceptable", "not_received", "not_as_described", "subscription_canceled", "canceled", "duplicate_charge", "payment_by_other_means", "unrecognized", "incorrect_amount", "fraud", "canceled_recurring_billing", "other", "problem_with_remittance", "unauthorized" ] } }, { "in": "query", "name": "processorNames", "description": "Filter disputes by payment processor (comma-separated values)", "schema": { "type": "string", "description": "Filter disputes by payment processor (comma-separated values)", "examples": ["stripe"], "enum": ["stripe", "shopify", "klarna", "afterpay", "paypal", "adyen"] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalCount": { "type": "number", "description": "Total number of disputes available in the database", "examples": [100] }, "hasMore": { "type": "boolean", "description": "Indicates if there are more disputes available beyond the current response", "examples": [true] }, "data": { "type": "array", "items": { "type": "object", "properties": { "chargeflowDisputeId": { "type": "string", "description": "The Chargeflow dispute id", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "dispute": { "type": "object", "properties": { "processorId": { "type": "string", "description": "The processor dispute id", "examples": ["PP-D-4012"] }, "processor": { "type": "string", "description": "The dispute processor", "examples": ["paypal"] }, "amount": { "type": "object", "properties": { "value": { "type": "number", "minimum": 0, "description": "The amount value", "examples": [100] }, "currency": { "type": "string", "maxLength": 10, "description": "The three-letter ISO 4217 currency code represents the currency used for the amount", "examples": ["USD"] } }, "additionalProperties": false }, "status": { "type": "string", "enum": [ "under_review", "lost", "awaiting_response", "refunded", "won", "needs_response", "appealable" ], "description": "The dispute status", "examples": ["won"] }, "reason": { "type": "string", "enum": [ "bank_cannot_process", "check_returned", "credit_not_processed", "customer_initiated", "debit_not_authorized", "duplicate", "general", "incorrect_account_details", "insufficient_funds", "product_not_received", "product_unacceptable", "not_received", "not_as_described", "subscription_canceled", "canceled", "duplicate_charge", "payment_by_other_means", "unrecognized", "incorrect_amount", "fraud", "canceled_recurring_billing", "other", "problem_with_remittance", "unauthorized" ], "description": "The processor dispute reason", "examples": ["fraud"] }, "responseDueDate": { "type": "string", "format": "date-time", "description": "The response due date in ISO8601 format", "examples": ["2021-01-01T00:00:00Z"] } } }, "transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "The transaction id", "examples": ["123e4567-e89b-12d3-a456-426614174000"] }, "creationDate": { "type": "string", "format": "date-time", "description": "The creation date of the webhook in ISO8601 format", "examples": ["2021-01-01T00:00:00Z"] }, "source": { "type": ["string", "null"], "description": "The source of the transaction", "examples": ["stripe"] }, "orderId": { "type": "string", "description": "As recieved from the payment processor, if available", "examples": ["4141404271159"] }, "customerEmail": { "type": "string", "format": "email", "description": "The customer email, as recieved from the payment processor, if available", "examples": ["john@example.com"] } } } } }, "description": "Array of dispute objects returned in the response" } } } } } } } }, "post": { "tags": ["Disputes"], "summary": "Create Dispute", "description": "Creates a dispute in Chargeflow that can either be viewed through the Chargeflow platform or managed by Chargeflow.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "disputeId": { "type": "string", "maxLength": 10000, "description": "The id of the dispute in your payment processor.", "examples": ["dp_1MykdxFtDWhhyHE1BFAV3osZ"] }, "creationDate": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp - when the charge was disputed.", "examples": ["2022-01-01T00:00:00Z"] }, "due_by": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp - when dispute evidence needs to be disputed by.", "examples": ["2022-01-01T00:00:00Z"] }, "charge": { "type": "string", "maxLength": 10000, "description": "The id of the disputed charge in your payment processor.", "examples": ["ch_3MmlLrLkdIwHu7ix0snN0B15"] }, "transactionId": { "type": "string", "maxLength": 128, "description": "The id of the transaction in your payment processor.", "examples": ["pi_1MykXhFtDWhhyHE1UjsZZ3xQ"] }, "transactionDate": { "type": "string", "format": "date-time", "description": "The date and time when the transaction was created, in ISO 8601 format", "examples": ["2022-01-01T00:00:00Z"] }, "reason": { "type": "string", "enum": [ "general", "fraudulent", "duplicate", "subscription_canceled", "product_unacceptable", "product_not_received", "unrecognized", "credit_not_processed", "incorrect_account_details", "insufficient_funds", "bank_cannot_process", "debit_not_authorized", "goods_services_returned_or_refused", "goods_services_cancelled", "transaction_amount_differs", "retrieved" ], "description": "The bank provided reason for the dispute.", "examples": ["general"] }, "disputeAmount": { "type": "number", "minimum": 0, "description": "The amount of the disputed charge. Amounts are in cents (or other minor currency unit.)", "examples": [100] }, "currency": { "type": "string", "maxLength": 10, "description": "The currency code of the disputed charge. e.g. 'USD'.", "examples": ["USD"] }, "processor": { "type": "string", "maxLength": 128, "description": "The payment processor for the charge.", "examples": ["Stripe, Shopify, Braintree etc."] }, "status": { "type": "string", "enum": ["needs_response", "warning_needs_response"], "description": "The status of the dispute.", "examples": ["needs_response"] }, "isChargeRefundable": { "type": "boolean", "description": "Is the disputed charge refundable.", "examples": [true] }, "addressLine1Check": { "type": "string", "enum": ["pass", "fail", "unavailable", "unchecked"], "description": "State of address check (if available). One of pass, fail, unavailable, unchecked.", "examples": ["fail"] }, "addressZipCheck": { "type": "string", "enum": ["pass", "fail", "unavailable", "unchecked"], "description": "State of address zip check (if available). One of pass, fail, unavailable, unchecked.", "examples": ["pass"] }, "cvcCheck": { "type": "string", "enum": ["pass", "fail", "unavailable", "unchecked"], "description": "State of cvc check (if available). One of pass, fail, unavailable, unchecked.", "examples": ["pass"] }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "minimum": 0, "description": "The product id" }, "variantId": { "type": "number", "minimum": 0, "description": "The product variant id" }, "name": { "type": "string", "maxLength": 256, "description": "The name of the product included in the order", "examples": ["Product Name"] }, "price": { "type": "object", "properties": { "value": { "type": "number", "minimum": 0, "description": "The amount value", "examples": [100] }, "currency": { "type": "string", "maxLength": 10, "description": "The three-letter ISO 4217 currency code represents the currency used for the amount", "examples": ["USD"] } }, "additionalProperties": false }, "imageUrl": { "type": "string", "format": "uri", "description": "A publicly available URL leading to an image of the product", "examples": ["https://example.com/image.png"] }, "description": { "type": "string", "maxLength": 10000, "description": "A description of the product, providing details about its features, specifications, or usage" }, "refundTransactionId": { "type": "string", "maxLength": 128, "description": "If the product was refunded refers to the transaction Id. The transaction with that id is expected to be found in transactions array" }, "quantity": { "type": "number", "minimum": 0, "description": "The quantity of this product ordered" }, "discount": { "type": "object", "properties": { "value": { "type": "number", "minimum": 0, "description": "The amount value", "examples": [100] }, "currency": { "type": "string", "maxLength": 10, "description": "The three-letter ISO 4217 currency code represents the currency used for the amount", "examples": ["USD"] } }, "additionalProperties": false, "description": "An object that represents the total discounts associated with this order" }, "shipmentId": { "type": "string", "maxLength": 128, "description": "The shipment id associated with the product" } }, "additionalProperties": false }, "description": "List of products the customer purchased." }, "pastPayments": { "type": "array", "items": { "type": "string" }, "description": "History of the customer's valid, non-disputed transactions using the same card.", "examples": [["null"]] }, "handleByChargeflow": { "type": "boolean", "description": "Whether you wish Chargeflow to handle the dispute or not. If True - Chargeflow will submit evidence for the dispute. If False - Chargeflow will not handle the dispute.", "examples": [true] } }, "required": [ "disputeId", "creationDate", "due_by", "disputeAmount", "currency", "processor", "isChargeRefundable", "handleByChargeflow" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "The request id for tracking and auditing" } }, "required": ["requestId"] } } } } } } } }, "webhooks": { "integration.access.error": { "post": { "summary": "Integration Access Error Event", "tags": ["Webhooks Events"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The webhook type", "examples": ["integration.access_error"] }, "data": { "type": "object", "properties": { "account_id": { "type": "string", "description": "The unique Chargeflow object identifier of the account.", "examples": ["acct_1234567890"] }, "integration_id": { "type": "string", "description": "The unique Chargeflow object identifier of the integration.", "examples": ["int_1234567890"] }, "error_message": { "type": "string", "description": "The error message describing the access error.", "examples": ["Access token expired or invalid."] } } }, "creationDate": { "type": "string", "format": "date-time", "description": "The creation date of the webhook in ISO8601 format", "examples": ["2021-01-01T00:00:00Z"] }, "webhookId": { "type": "string", "format": "uuid", "default": "2ce92305-2f21-4888-a09f-3256bf7c678e", "description": "The webhook id", "examples": ["123e4567-e89b-12d3-a456-426614174000"] } } } } } }, "responses": { "200": { "description": "OK" } } } }, "evidence.ready": { "post": { "summary": "Evidence Ready Event", "tags": ["Webhooks Events"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow object identifier", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "disputeId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow dispute identifier", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "evidenceId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow evidence identifier", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "fileUrl": { "type": "string", "description": "The URL to the generated evidence file", "examples": [ "https://cdn.chargeflow.io/evidence/ev_abc123456789/v2/evidence.pdf" ] }, "version": { "type": "number", "description": "The version number of the evidence file", "examples": [1] }, "createdAt": { "type": "string", "default": "2026-05-07T16:25:29.880Z", "description": "The timestamp when the evidence was generated" } }, "required": ["accountId", "disputeId", "evidenceId", "fileUrl", "version"] } } } }, "responses": { "200": { "description": "OK" } } } }, "evidence.error": { "post": { "summary": "Evidence Error Event", "tags": ["Webhooks Events"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow object identifier", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "disputeId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow dispute identifier", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "evidenceId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow evidence identifier", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "errorCode": { "type": "string", "description": "The error code indicating the type of failure", "examples": ["EVIDENCE_GENERATION_FAILED"] }, "errorMessage": { "type": "string", "description": "A descriptive message explaining the error", "examples": ["Failed to generate evidence PDF due to missing dispute data"] }, "version": { "type": "number", "description": "The version number of the evidence file", "examples": [1] }, "createdAt": { "type": "string", "default": "2026-05-07T16:25:29.880Z", "description": "The timestamp when the error occurred" } }, "required": [ "accountId", "disputeId", "evidenceId", "errorCode", "errorMessage", "version" ] } } } }, "responses": { "200": { "description": "OK" } } } }, "dispute.created": { "post": { "summary": "Dispute Created Event", "tags": ["Webhooks Events"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The webhook type", "examples": ["dispute.created"] }, "data": { "type": "object", "properties": { "chargeflowDisputeId": { "type": "string", "description": "The Chargeflow dispute id", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "dispute": { "type": "object", "properties": { "processorId": { "type": "string", "description": "The processor dispute id", "examples": ["PP-D-4012"] }, "processor": { "type": "string", "description": "The dispute processor", "examples": ["paypal"] }, "amount": { "type": "object", "properties": { "value": { "type": "number", "minimum": 0, "description": "The amount value", "examples": [100] }, "currency": { "type": "string", "maxLength": 10, "description": "The three-letter ISO 4217 currency code represents the currency used for the amount", "examples": ["USD"] } }, "additionalProperties": false }, "status": { "type": "string", "enum": [ "under_review", "lost", "awaiting_response", "refunded", "won", "needs_response", "appealable" ], "description": "The dispute status", "examples": ["won"] }, "reason": { "type": "string", "enum": [ "bank_cannot_process", "check_returned", "credit_not_processed", "customer_initiated", "debit_not_authorized", "duplicate", "general", "incorrect_account_details", "insufficient_funds", "product_not_received", "product_unacceptable", "not_received", "not_as_described", "subscription_canceled", "canceled", "duplicate_charge", "payment_by_other_means", "unrecognized", "incorrect_amount", "fraud", "canceled_recurring_billing", "other", "problem_with_remittance", "unauthorized" ], "description": "The processor dispute reason", "examples": ["fraud"] }, "responseDueDate": { "type": "string", "format": "date-time", "description": "The response due date in ISO8601 format", "examples": ["2021-01-01T00:00:00Z"] } } }, "transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "The transaction id", "examples": ["123e4567-e89b-12d3-a456-426614174000"] }, "creationDate": { "type": "string", "format": "date-time", "description": "The creation date of the webhook in ISO8601 format", "examples": ["2021-01-01T00:00:00Z"] }, "source": { "type": ["string", "null"], "description": "The source of the transaction", "examples": ["stripe"] }, "orderId": { "type": "string", "description": "As recieved from the payment processor, if available", "examples": ["4141404271159"] }, "customerEmail": { "type": "string", "format": "email", "description": "The customer email, as recieved from the payment processor, if available", "examples": ["john@example.com"] } } }, "vendorAccountId": { "type": "string", "description": "The vendor account id", "examples": ["55617"] }, "accountId": { "type": "string", "description": "The account id", "examples": ["67598401g210baf852j1f6dd"] } } }, "creationDate": { "type": "string", "format": "date-time", "description": "The creation date of the webhook in ISO8601 format", "examples": ["2021-01-01T00:00:00Z"] }, "webhookId": { "type": "string", "format": "uuid", "default": "e11e21e3-41ec-4c9d-9381-442cb6030ce1", "description": "The webhook id", "examples": ["123e4567-e89b-12d3-a456-426614174000"] } } } } } }, "responses": { "200": { "description": "OK" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Your Chargeflow API key, sent on every request. Generate one in the [Chargeflow App](https://app.chargeflow.io/settings#developers), or see [API keys](/docs/reference/api-fundamentals/test-credentials)." } } } }