{ "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": "Accounts", "description": "Accounts related endpoints" }, { "name": "Merchants Disputes", "description": "Merchants disputes management endpoints" }, { "name": "Evidence", "description": "Evidence management endpoints" }, { "name": "Webhooks Events", "description": "Webhook event notifications" } ], "servers": [ { "url": "https://api.chargeflow.io", "description": "Production server" } ], "paths": { "/public/2025-04-01/accounts": { "post": { "tags": [ "Accounts" ], "summary": "Create Account", "description": "Creates a new Chargeflow account and allow your merchants to log in and use Chargeflow.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "owner_name": { "type": "string", "maxLength": 10000, "description": "The account owner's name.", "example": "Example Merchants Ltd." }, "business_name": { "type": "string", "maxLength": 10000, "description": "The account name, which represents the business name of the account.", "example": "Example Merchants Ltd." }, "business_url": { "type": "string", "format": "uri", "maxLength": 10000, "description": "The public URL of the business website.", "example": "https://example.com" }, "email": { "type": "string", "format": "email", "maxLength": 128, "description": "The account owner's email address, used to log in and contact the account owner.", "example": "merchant@example.com" }, "ext_account_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique account identifier appears on the platform. Null if not set by the platform.", "example": "platform_987654321" }, "status": { "type": "string", "enum": [ "active", "inactive" ], "default": "active", "description": "The status of the account; defaults to active.", "example": "active" }, "enrichments": { "type": [ "object", "null" ], "properties": { "company_description": { "type": [ "string", "null" ], "maxLength": 10000, "description": "A brief overview of the company, including target market, key products or services, and any essential details that help introduce the company." }, "support_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 128, "description": "The company's support email address where they receive and reply to their buyers' tickets." }, "industry": { "type": [ "string", "null" ], "enum": [ "retail", "travel", "car_rental", "hospitality", "transportation", "telecom", "saas", "igaming", "food_and_beverages", "ticketing", "digital_services", "e_learning", "health", "crypto" ], "description": "The industry in which the company operates; different industries require different approaches and strategies to streamline transactions and dispute processes." }, "product_types": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "physical_goods", "digital_goods", "physical_services", "digital_services" ] }, "description": "The types of products or services the company offers to its buyers." }, "payment_models": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "subscription", "single_payment", "trial_period", "top_ups", "buy_now_pay_later" ] }, "description": "The payment processing types that the company supports for accepting payments." }, "policies": { "type": [ "object", "null" ], "properties": { "terms_and_conditions_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL which is available on the company website and outlines the company's terms and conditions. Must be a valid URL (e.g., https://mycompany.com/shipping_policy)." }, "shipping_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL which is available on the company website and outlines the company's shipping and delivery policy. Must be a valid URL (e.g., https://mycompany.com/shipping_policy)." }, "cancellation_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL which is available on the company website and outlines the company's cancellation policy. Must be a valid URL (e.g., https://mycompany.com/cancellation_policy)." }, "refund_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL which is available on the company website and outlines the company's refund policy. Must be a valid URL (e.g., https://mycompany.com/refund_policy)." }, "return_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL which is available on the company website and outlines the company's return policy. Must be a valid URL (e.g., https://mycompany.com/return_policy)." }, "subscription_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL which is available on the company website and outlines the company's subscription policy. Must be a valid URL (e.g., https://mycompany.com/subscription_policy)." }, "gaming_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL which is available on the company website and outlines the company's gaming policy. Must be a valid URL (e.g., https://mycompany.com/gaming_policy)." } }, "description": "The policies that are available on the company website." }, "checkout_process": { "type": [ "object", "null" ], "properties": { "pre_checkout_elements": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "terms_and_conditions", "product_details", "pricing", "shipping_details", "cancellation_details", "reviews", "order_protection", "stock_availability", "frequently_asked_questions", "size_guide", "support_channels" ] }, "description": "The elements that are available for the buyer before the checkout process." }, "post_checkout_elements": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "order_confirmation", "digital_receipt", "product_care", "order_modification", "subscription_confirmation", "support_channels", "tracking_information", "estimated_delivery_date", "refund_policy", "return_policy", "confirmation_email" ] }, "description": "The elements that are available for the buyer after the checkout process." } }, "description": "The elements available before and after the company's checkout process; this information helps to streamline approaches and strategies to manage transactions and dispute processes." }, "buyer_verifications": { "type": [ "object", "null" ], "properties": { "during_sign_up": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "email_verification", "phone_verification", "confirmation_call", "address_verification", "identity_verification" ] }, "description": "The verification methods used during the sign up process to authenticate the buyer before accessing the company's products or services." }, "post_purchase": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "email_verification", "phone_verification", "confirmation_call", "address_verification", "identity_verification" ] }, "description": "The verification methods used post-purchase to authenticate the buyer before accessing the company's products or services." } }, "description": "The verification methods the company uses to authenticate legitimate customers to reduce fraudulent transactions; this information is used to streamline approaches and strategies for managing transactions and dispute processes." } }, "description": "The enrichments object containing company-level data that plays a critical role in tailoring and improving account-specific results. This information enhances the accuracy, relevance, and overall performance." } }, "required": [ "owner_name", "business_name", "business_url", "email" ], "additionalProperties": false, "description": "Creates a new Chargeflow account and allows your merchants to log in and use Chargeflow." } } } }, "responses": { "200": { "description": "Account created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow object identifier of the account.", "example": "66e6ea9ecd94925a9f8060d9" }, "ext_account_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique account identifier appears on the platform. Null if not set by the platform.", "example": "platform_987654321" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the account was created in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "owner_name": { "type": [ "string", "null" ], "maxLength": 10000, "description": "The account owner's name.", "example": "Example Merchants Ltd." }, "business_name": { "type": [ "string", "null" ], "maxLength": 10000, "description": "The account name, which represents the Business name.", "example": "Example Merchants Ltd." }, "business_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 10000, "description": "The public URL of the company website.", "example": "https://example.com" }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 128, "description": "The account owner's email address, used to log in and contact.", "example": "merchant@example.com" }, "status": { "type": [ "string", "null" ], "enum": [ "active", "inactive" ], "description": "The status of the account; defaults to active.", "example": "active" }, "enrichments": { "type": [ "object", "null" ], "properties": { "company_description": { "type": [ "string", "null" ], "maxLength": 10000, "description": "A brief overview of the company, including target market, key products or services, and any essential details that help introduce the company." }, "support_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 128, "description": "The company's support email address where they receive and reply to their buyers' tickets." }, "industry": { "type": [ "string", "null" ], "enum": [ "retail", "travel", "car_rental", "hospitality", "transportation", "telecom", "saas", "igaming", "food_and_beverages", "ticketing", "digital_services", "e_learning", "health", "crypto" ], "description": "The industry in which the company operates; different industries require different approaches and strategies to streamline transactions and dispute processes." }, "product_types": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "physical_goods", "digital_goods", "physical_services", "digital_services" ] }, "description": "The types of products or services the company offers to its buyers." }, "payment_models": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "subscription", "single_payment", "trial_period", "top_ups", "buy_now_pay_later" ] }, "description": "The payment processing types that the company supports for accepting payments." }, "policies": { "type": [ "object", "null" ], "properties": { "terms_and_conditions_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL which is available on the company website and outlines the company's terms and conditions. Must be a valid URL (e.g., https://mycompany.com/shipping_policy)." }, "shipping_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL which is available on the company website and outlines the company's shipping and delivery policy. Must be a valid URL (e.g., https://mycompany.com/shipping_policy)." }, "cancellation_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL which is available on the company website and outlines the company's cancellation policy. Must be a valid URL (e.g., https://mycompany.com/cancellation_policy)." }, "refund_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL which is available on the company website and outlines the company's refund policy. Must be a valid URL (e.g., https://mycompany.com/refund_policy)." }, "return_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL which is available on the company website and outlines the company's return policy. Must be a valid URL (e.g., https://mycompany.com/return_policy)." }, "subscription_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL which is available on the company website and outlines the company's subscription policy. Must be a valid URL (e.g., https://mycompany.com/subscription_policy)." }, "gaming_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL which is available on the company website and outlines the company's gaming policy. Must be a valid URL (e.g., https://mycompany.com/gaming_policy)." } }, "description": "The policies that are available on the company website." }, "checkout_process": { "type": [ "object", "null" ], "properties": { "pre_checkout_elements": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "terms_and_conditions", "product_details", "pricing", "shipping_details", "cancellation_details", "reviews", "order_protection", "stock_availability", "frequently_asked_questions", "size_guide", "support_channels" ] }, "description": "The elements that are available for the buyer before the checkout process." }, "post_checkout_elements": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "order_confirmation", "digital_receipt", "product_care", "order_modification", "subscription_confirmation", "support_channels", "tracking_information", "estimated_delivery_date", "refund_policy", "return_policy", "confirmation_email" ] }, "description": "The elements that are available for the buyer after the checkout process." } }, "description": "The elements available before and after the company's checkout process; this information helps to streamline approaches and strategies to manage transactions and dispute processes." }, "buyer_verifications": { "type": [ "object", "null" ], "properties": { "during_sign_up": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "email_verification", "phone_verification", "confirmation_call", "address_verification", "identity_verification" ] }, "description": "The verification methods used during the sign up process to authenticate the buyer before accessing the company's products or services." }, "post_purchase": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "email_verification", "phone_verification", "confirmation_call", "address_verification", "identity_verification" ] }, "description": "The verification methods used post-purchase to authenticate the buyer before accessing the company's products or services." } }, "description": "The verification methods the company uses to authenticate legitimate customers to reduce fraudulent transactions; this information is used to streamline approaches and strategies for managing transactions and dispute processes." } }, "description": "The enrichments object containing company-level data that plays a critical role in tailoring and improving account-specific results. This information enhances the accuracy, relevance, and overall performance." } }, "additionalProperties": false, "description": "An account is the primary entity that interacts with our system. It serves as the foundation for authentication, authorization, and access to various resources and services within the platform." } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "invalid_request_error", "description": "The type of error", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_parameter", "missing_parameter", "invalid_format" ], "description": "Specific error code", "example": "invalid_parameter" }, "message": { "type": "string", "enum": [ "Bad Request", "Invalid request parameters" ], "description": "Human-readable error message", "example": "Bad Request" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Bad Request - The request contains invalid parameters or is malformed", "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Bad Request", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "BadRequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "authentication_error", "description": "The type of error", "example": "authentication_error" }, "code": { "type": "string", "enum": [ "unauthorized", "invalid_credentials", "missing_credentials" ], "description": "Specific error code", "example": "unauthorized" }, "message": { "type": "string", "enum": [ "Unauthorized access", "Authentication credentials are missing or invalid" ], "description": "Human-readable error message", "example": "Unauthorized access" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Unauthorized - Authentication is required or has failed", "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "Unauthorized access", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "UnauthorizedError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "permission_error", "description": "The type of error", "example": "permission_error" }, "code": { "type": "string", "enum": [ "forbidden", "insufficient_permissions" ], "description": "Specific error code", "example": "forbidden" }, "message": { "type": "string", "enum": [ "Forbidden", "You do not have permission to access this resource" ], "description": "Human-readable error message", "example": "Forbidden" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Forbidden - The request is understood but has been refused due to insufficient permissions", "example": { "error": { "type": "permission_error", "code": "forbidden", "message": "Forbidden", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "ForbiddenError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "invalid_request_error", "description": "The type of error", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "account_not_found", "platform_not_found" ], "description": "Specific error code", "example": "account_not_found" }, "message": { "type": "string", "enum": [ "Account not found", "Platform not found" ], "description": "Human-readable error message", "example": "Account not found" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "The requested account or platform does not exist", "example": { "error": { "type": "invalid_request_error", "code": "account_not_found", "message": "Account not found", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "AccountNotFoundError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "api_error", "description": "The type of error", "example": "api_error" }, "code": { "type": "string", "enum": [ "internal_error", "server_error", "account_creation_failed", "account_retrieval_failed", "account_update_failed" ], "description": "Specific error code", "example": "internal_error" }, "message": { "type": "string", "enum": [ "Internal server error", "An unexpected error occurred", "Failed to create account", "Failed to get accounts", "Failed to update account" ], "description": "Human-readable error message", "example": "Internal server error" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Internal Server Error - Something went wrong on our end. Please try again later.", "example": { "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "InternalServerError" } } } } } } }, "/public/2025-04-01/accounts/{accountId}": { "get": { "tags": [ "Accounts" ], "summary": "Get Account By ID", "description": "Retrieve a single account details.", "parameters": [ { "in": "path", "name": "accountId", "description": "The unique Chargeflow object identifier of the account.", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow object identifier of the account.", "example": "66e6ea9ecd94925a9f8060d9" }, "required": true } ], "responses": { "200": { "description": "Account retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow object identifier of the account.", "example": "66e6ea9ecd94925a9f8060d9" }, "ext_account_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique account identifier appears on the platform. Null if not set by the platform.", "example": "platform_987654321" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the account was created in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "owner_name": { "type": [ "string", "null" ], "maxLength": 10000, "description": "The account owner's name.", "example": "Example Merchants Ltd." }, "business_name": { "type": [ "string", "null" ], "maxLength": 10000, "description": "The account name, which represents the Business name.", "example": "Example Merchants Ltd." }, "business_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 10000, "description": "The public URL of the company website.", "example": "https://example.com" }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 128, "description": "The account owner's email address, used to log in and contact.", "example": "merchant@example.com" }, "status": { "type": [ "string", "null" ], "enum": [ "active", "inactive" ], "description": "The status of the account; defaults to active.", "example": "active" }, "enrichments": { "type": [ "object", "null" ], "properties": { "company_description": { "type": [ "string", "null" ], "maxLength": 10000, "description": "A brief overview of the company, including target market, key products or services, and any essential details that help introduce the company." }, "support_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 128, "description": "The company's support email address where they receive and reply to their buyers' tickets." }, "industry": { "type": [ "string", "null" ], "enum": [ "retail", "travel", "car_rental", "hospitality", "transportation", "telecom", "saas", "igaming", "food_and_beverages", "ticketing", "digital_services", "e_learning", "health", "crypto" ], "description": "The industry in which the company operates; different industries require different approaches and strategies to streamline transactions and dispute processes." }, "product_types": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "physical_goods", "digital_goods", "physical_services", "digital_services" ] }, "description": "The types of products or services the company offers to its buyers." }, "payment_models": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "subscription", "single_payment", "trial_period", "top_ups", "buy_now_pay_later" ] }, "description": "The payment processing types that the company supports for accepting payments." }, "policies": { "type": [ "object", "null" ], "properties": { "terms_and_conditions_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL which is available on the company website and outlines the company's terms and conditions. Must be a valid URL (e.g., https://mycompany.com/shipping_policy)." }, "shipping_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL which is available on the company website and outlines the company's shipping and delivery policy. Must be a valid URL (e.g., https://mycompany.com/shipping_policy)." }, "cancellation_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL which is available on the company website and outlines the company's cancellation policy. Must be a valid URL (e.g., https://mycompany.com/cancellation_policy)." }, "refund_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL which is available on the company website and outlines the company's refund policy. Must be a valid URL (e.g., https://mycompany.com/refund_policy)." }, "return_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL which is available on the company website and outlines the company's return policy. Must be a valid URL (e.g., https://mycompany.com/return_policy)." }, "subscription_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL which is available on the company website and outlines the company's subscription policy. Must be a valid URL (e.g., https://mycompany.com/subscription_policy)." }, "gaming_url": { "type": [ "string", "null" ], "format": "uri", "description": "The URL which is available on the company website and outlines the company's gaming policy. Must be a valid URL (e.g., https://mycompany.com/gaming_policy)." } }, "description": "The policies that are available on the company website." }, "checkout_process": { "type": [ "object", "null" ], "properties": { "pre_checkout_elements": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "terms_and_conditions", "product_details", "pricing", "shipping_details", "cancellation_details", "reviews", "order_protection", "stock_availability", "frequently_asked_questions", "size_guide", "support_channels" ] }, "description": "The elements that are available for the buyer before the checkout process." }, "post_checkout_elements": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "order_confirmation", "digital_receipt", "product_care", "order_modification", "subscription_confirmation", "support_channels", "tracking_information", "estimated_delivery_date", "refund_policy", "return_policy", "confirmation_email" ] }, "description": "The elements that are available for the buyer after the checkout process." } }, "description": "The elements available before and after the company's checkout process; this information helps to streamline approaches and strategies to manage transactions and dispute processes." }, "buyer_verifications": { "type": [ "object", "null" ], "properties": { "during_sign_up": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "email_verification", "phone_verification", "confirmation_call", "address_verification", "identity_verification" ] }, "description": "The verification methods used during the sign up process to authenticate the buyer before accessing the company's products or services." }, "post_purchase": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "email_verification", "phone_verification", "confirmation_call", "address_verification", "identity_verification" ] }, "description": "The verification methods used post-purchase to authenticate the buyer before accessing the company's products or services." } }, "description": "The verification methods the company uses to authenticate legitimate customers to reduce fraudulent transactions; this information is used to streamline approaches and strategies for managing transactions and dispute processes." } }, "description": "The enrichments object containing company-level data that plays a critical role in tailoring and improving account-specific results. This information enhances the accuracy, relevance, and overall performance." } }, "additionalProperties": false, "description": "An account is the primary entity that interacts with our system. It serves as the foundation for authentication, authorization, and access to various resources and services within the platform." } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "invalid_request_error", "description": "The type of error", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_parameter", "missing_account_id" ], "description": "Specific error code", "example": "invalid_parameter" }, "message": { "type": "string", "enum": [ "Bad Request", "Account ID is required" ], "description": "Human-readable error message", "example": "Bad Request" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Invalid or missing account ID parameter", "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Bad Request", "request_id": "req_abc123def456" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "authentication_error", "description": "The type of error", "example": "authentication_error" }, "code": { "type": "string", "enum": [ "unauthorized", "invalid_credentials", "missing_credentials" ], "description": "Specific error code", "example": "unauthorized" }, "message": { "type": "string", "enum": [ "Unauthorized access", "Authentication credentials are missing or invalid" ], "description": "Human-readable error message", "example": "Unauthorized access" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Unauthorized - Authentication is required or has failed", "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "Unauthorized access", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "UnauthorizedError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "permission_error", "description": "The type of error", "example": "permission_error" }, "code": { "type": "string", "enum": [ "forbidden", "insufficient_permissions" ], "description": "Specific error code", "example": "forbidden" }, "message": { "type": "string", "enum": [ "Forbidden", "You do not have permission to access this resource" ], "description": "Human-readable error message", "example": "Forbidden" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Forbidden - The request is understood but has been refused due to insufficient permissions", "example": { "error": { "type": "permission_error", "code": "forbidden", "message": "Forbidden", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "ForbiddenError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "invalid_request_error", "description": "The type of error", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "account_not_found" ], "description": "Specific error code", "example": "account_not_found" }, "message": { "type": "string", "enum": [ "Account not found" ], "description": "Human-readable error message", "example": "Account not found" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "The requested account does not exist", "example": { "error": { "type": "invalid_request_error", "code": "account_not_found", "message": "Account not found", "request_id": "req_abc123def456" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "api_error", "description": "The type of error", "example": "api_error" }, "code": { "type": "string", "enum": [ "internal_error", "server_error", "account_creation_failed", "account_retrieval_failed", "account_update_failed" ], "description": "Specific error code", "example": "internal_error" }, "message": { "type": "string", "enum": [ "Internal server error", "An unexpected error occurred", "Failed to create account", "Failed to get accounts", "Failed to update account" ], "description": "Human-readable error message", "example": "Internal server error" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Internal Server Error - Something went wrong on our end. Please try again later.", "example": { "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "InternalServerError" } } } } } } }, "/public/2025-04-01/evidence": { "post": { "tags": [ "Evidence" ], "summary": "Generate Evidence", "description": "Instantly generate high-quality, AI-powered evidence in a PDF format tailored for dispute response.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the evidence belongs.", "example": "66e6ea9ecd94925a9f8060d9" }, "dispute": { "anyOf": [ { "type": "object", "properties": { "dispute_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow dispute identifier to which the evidence associated with.", "example": "dp_112233445" } }, "required": [ "dispute_id" ], "additionalProperties": false }, { "type": "object", "properties": { "dispute_data": { "type": "object", "properties": { "source_id": { "type": "string", "maxLength": 128, "description": "The unique dispute identifier appears on the source (processor) from which the dispute originated.", "example": "du_123456789" }, "created_at": { "type": "string", "format": "date-time", "description": "The time at which the dispute was created at the processor in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "reason": { "type": "string", "enum": [ "fraud", "not_received", "not_as_described", "canceled_recurring_billing", "duplicate_charge", "credit_not_processed", "other" ], "description": "The reason the cardholder has disputed the transaction.", "example": "fraud" }, "due_by": { "type": "string", "format": "date-time", "description": "The deadline to submit evidence to challenge the dispute in ISO 8601 format.", "example": "2024-02-20T12:00:00Z" }, "amount": { "type": "number", "minimum": 0, "description": "Disputed amount. Equal to or less than the disputed transaction amount.", "example": 100 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "status": { "type": "string", "enum": [ "needs_response", "under_review", "won", "lost" ], "description": "The current status of the dispute.", "example": "needs_response" }, "stage": { "type": "string", "enum": [ "Chargeback", "Inquiry", "Pre_arbitration", "Arbitration" ], "default": "Chargeback", "description": "The stage of the dispute. Default is chargeback.", "example": "Chargeback" }, "transaction": { "type": "object", "properties": { "source_id": { "type": "string", "maxLength": 128, "description": "The unique transaction identifier appears on the source from which the transaction originated.", "example": "tx_1234567890" }, "created_at": { "type": "string", "format": "date-time", "description": "The time at which the transaction was created at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "type": { "type": "string", "enum": [ "paid", "partially_paid", "refunded", "partially_refunded" ], "description": "The type of the transaction", "example": "paid" }, "amount": { "type": "number", "minimum": 0, "description": "Transaction total amount after all deductions.", "example": 100 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "payment_method": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The full name of the person to which the payment method belongs to.", "example": "John Doe" }, "type": { "type": [ "string", "null" ], "enum": [ "card", "wallet" ], "description": "The type of the payment method", "example": "card" }, "last4": { "type": [ "string", "null" ], "pattern": "^\\d{4}$", "minLength": 4, "maxLength": 4, "description": "The last four digits of the card used for the transaction. `card`", "example": "1234" }, "expiry_month": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 12, "description": "The month when the card used for the transaction is expired. `card`", "example": 1 }, "expiry_year": { "type": [ "integer", "null" ], "minimum": 2019, "maximum": 2100, "description": "The year when the card used for the transaction is expired. `card`", "example": 2025 }, "brand": { "type": [ "string", "null" ], "enum": [ "visa", "mastercard", "discover", "amex", "jcb", "unionpay", "diners", "other" ], "description": "The card brand used for the transaction. `card`", "example": "visa" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "The card issuance country - two-letter country code (ISO 3166-1 alpha-2). `card`", "example": "US" }, "wallet": { "type": [ "string", "null" ], "enum": [ "paypal", "klarna", "affirm", "afterpay", "sezzle", "zip", "venmo", "apple", "other" ], "description": "The name of the wallet which used for the transaction. `wallet`", "example": "paypal" }, "checks": { "type": "object", "properties": { "three_d_secure_result": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The 3D secure authentication outcome. `card`", "example": "passed" }, "avs_results": { "type": [ "string", "null" ], "enum": [ "N", "A", "Y", "Z" ], "description": "The address verification system outcome. `card`", "example": "N" }, "address_line1_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The address line1 check result. `card`", "example": "passed" }, "address_zip_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The address zip or postal code check result. `card`", "example": "passed" }, "cvc_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The card verification code result. `card`", "example": "passed" } }, "description": "The checks performed by the network at the time of payment. `card`" }, "wallet_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 128, "description": "The email address of the wallet which used for the transaction. `wallet`", "example": "john.doe@example.com" }, "wallet_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The wallet unique identifier which used for the transaction. `wallet`", "example": "1234567890" } }, "description": "The payment method used by the customer to process the transaction." }, "billing_address": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The name of the person associated with the billing address.", "example": "John Doe" }, "line1": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "example": "123 Main St" }, "line2": { "type": [ "string", "null" ], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "example": "Apt 1" }, "city": { "type": [ "string", "null" ], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "example": "San Francisco" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Two-letter country code (ISO 3166-1 alpha-2) associated with the address lines", "example": "US" }, "state": { "type": [ "string", "null" ], "description": "State, county, province, or region associated with the address lines.", "example": "CA" }, "zip_code": { "type": [ "string", "null" ], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "example": "12345" }, "phone": { "type": [ "string", "null" ], "description": "The phone number of the person associated with the billing address.", "example": "1(123)4567890" } }, "description": "The billing address associated with the payment method at the time of the transaction" }, "order_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "example": "ord_1234567890" } ], "description": "The unique Chargeflow identifier of the order to which the transaction is linked.", "example": "66e6ea9ecd94925a9f8060d9" }, "subscription_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow identifier of the subscription to which the transaction is linked.", "example": "66e6ea9ecd94925a9f8060d9" } }, "required": [ "source_id", "created_at", "type", "amount", "currency" ] }, "subscription": { "type": "object", "properties": { "source_id": { "type": "string", "maxLength": 128, "description": "The unique subscription identifier appears on the source from which the subscription originated.", "example": "source_sub_1234567890" }, "account_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the subscription belongs. This field is `required` for platform users.", "example": "66e6ea9ecd94925a9f8060d9" }, "created_at": { "type": "string", "format": "date-time", "description": "The time at which the subscription was created at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "start_date": { "type": "string", "format": "date-time", "description": "The time at which the subscription was started at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "frequency": { "type": "string", "enum": [ "day", "week", "month", "year" ], "description": "The frequency at which a subscription is billed.", "example": "month" }, "frequency_count": { "type": "integer", "minimum": 1, "description": "The number of intervals per billing cycle. For example, if frequency = month and frequency_count = 1, the subscription renews every month. If frequency_count = 3, the subscription renews every three months.", "example": 1 }, "collection_method": { "type": "string", "enum": [ "automatically", "automatically_with_reminder", "send_invoice" ], "default": "automatically", "description": "The billing method for the subscription.", "example": "automatically" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was updated at the source in ISO 8601 format.", "example": "2024-02-15T12:00:00Z" }, "end_date": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was ended at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "cancellation_date": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was requested to be canceled at the source in ISO 8601 format. Returns null if a cancellation is never requested.", "example": "2024-07-10T12:00:00Z" }, "cancellation_reason": { "type": [ "string", "null" ], "enum": [ "too_expensive", "low_quality", "unused", "too_complex", "missing_features" ], "description": "The submitted reason for why the subscription has canceled.", "example": "too_expensive" }, "trial_start": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the trial of the subscription began at the source in ISO 8601 format. Returns null if no trial is offered or if the trial was not utilized.", "example": "2024-02-10T12:00:00Z" }, "trial_end": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the trial of the subscription ended at the source in ISO 8601 format. Returns null if no trial is offered or if the trial was not utilized.", "example": "2024-03-10T12:00:00Z" }, "renews_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription cycle renews at the source in ISO 8601 format. Returns null if the subscription has been canceled.", "example": "2024-03-10T12:00:00Z" }, "plan_name": { "type": [ "string", "null" ], "description": "The name of the plan associated with the subscription, representing the specific offering or service tier the subscriber is enrolled in.", "example": "Pro Plan" }, "pricing_model": { "type": "string", "enum": [ "fixed_price", "usage_base" ], "default": "fixed_price", "description": "The pricing model associated with the subscription.", "example": "fixed_price" }, "status": { "type": "string", "enum": [ "active", "inactive", "canceled" ], "default": "active", "description": "The current status of the subscription.", "example": "active" } }, "required": [ "source_id", "created_at", "start_date", "frequency", "frequency_count" ], "description": "Creates a new Chargeflow subscription." }, "order": { "type": "object", "properties": { "source_id": { "type": "string", "maxLength": 128, "description": "The unique order identifier appears on the source from which the order originated.", "example": "order_1234567890" }, "created_at": { "type": "string", "format": "date-time", "description": "The time at which the order was created at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "payment_status": { "type": "string", "enum": [ "paid", "partially_paid", "refunded", "partially_refunded" ], "description": "The financial status of the order", "example": "paid" }, "amount": { "type": "number", "minimum": 0, "description": "Order total amount after all deductions.", "example": 1000 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "name": { "type": "string", "maxLength": 128, "description": "The order name or number as appear in your source", "example": "#ORD-12345" }, "type": { "type": "string", "enum": [ "standard", "pre_order" ], "default": "standard", "description": "The type of the order; defaults to standard.", "example": "standard" }, "customer": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 128, "description": "The full name of the customer who have made this order.", "example": "John Doe" }, "email": { "type": "string", "format": "email", "maxLength": 128, "description": "The email address belong to the customer. Valid format:", "example": "example@mail.com" }, "customer_since": { "type": "string", "format": "date-time", "description": "The time at which the customer has made their first order with the merchant in ISO 8601 format.", "example": "2025-01-27T10:00:00Z" }, "order_count": { "type": "integer", "minimum": 0, "description": "The count of orders made by this customer with the merchant.", "example": 1 }, "phone_number": { "type": "string", "maxLength": 128, "description": "The phone number belong to the customer. Valid format:", "example": "1(123)4567890" }, "ip_address": { "type": "string", "maxLength": 128, "description": "The IP address belongs to the customer in the context of the given order. Valid format: IPv4 or IPv6.", "example": "192.168.1.1" }, "verified_email": { "type": "boolean", "description": "Whether the customer email address was verified by the merchant. If `true`, the customer's email was verified at least once by the merchant.", "example": true } }, "required": [ "name", "email" ], "description": "The customer who made this order." }, "products": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 128, "description": "The product name as appear on the merchant's product catalog.", "example": "Product Name" }, "id": { "type": "string", "maxLength": 128, "description": "The product unique identifier. Relevant to link it to tracking number and shipping method.", "example": "123456789" }, "type": { "type": "string", "enum": [ "physical_good", "digital_good", "service", "other" ], "description": "The type of the product", "example": "physical_good" }, "quantity": { "type": "integer", "minimum": 1, "description": "The number of items that were purchased.", "example": 1 }, "description": { "type": "string", "maxLength": 1000, "description": "A short description of the product as communicated to the customer in the merchant's product page.", "example": "Product Description" }, "image_url": { "type": "string", "format": "uri", "maxLength": 1000, "description": "A url of the primary product image associated with the product. Valid format:", "example": "https://myurl.com/image/product/123456789" }, "price": { "type": "number", "minimum": 0, "description": "The price amount of the given product in the order's currency.", "example": 100 } }, "required": [ "name", "type", "quantity", "price" ] }, "description": "An array of the products purchased in this order." }, "shipping_address": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The name of the person associated with the shipping address.", "example": "John Doe" }, "line1": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "example": "123 Main St" }, "line2": { "type": [ "string", "null" ], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "example": "Apt 1" }, "city": { "type": [ "string", "null" ], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "example": "San Francisco" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Two-letter country code (ISO 3166-1 alpha-2) associated with the address lines", "example": "US" }, "state": { "type": [ "string", "null" ], "description": "State, county, province, or region associated with the address lines.", "example": "CA" }, "zip_code": { "type": [ "string", "null" ], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "example": "12345" }, "phone": { "type": [ "string", "null" ], "description": "The phone number of the person associated with the shipping address.", "example": "1(123)4567890" } } }, "fulfillments": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The product's unique identifier to which the shipping method and tracking number was applied. Set to null if this was applied to all products in this order.", "example": "123456789" }, "shipped_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the order was shipped in ISO 8601 format.", "example": "2025-01-27T10:00:00Z" }, "shipping_line_title": { "type": [ "string", "null" ], "maxLength": 128, "description": "The shipping line title.", "example": "FedEx" }, "shipping_method_price": { "type": [ "number", "null" ], "minimum": 0, "description": "The shipping method price as paid by the customer in the order's currency.", "example": 100 }, "tracking_number": { "type": [ "string", "null" ], "maxLength": 128, "description": "The tracking number that was provided to track the fulfillment journey.", "example": "123456789" }, "courier": { "type": [ "string", "null" ], "maxLength": 128, "description": "The shipping courier from which the tracking number originated and used to fulfill the order.", "example": "FedEx" } } } } }, "required": [ "source_id", "created_at", "payment_status", "amount", "currency" ] } }, "required": [ "source_id", "created_at", "reason", "due_by", "amount", "currency", "status" ] } }, "required": [ "dispute_data" ], "additionalProperties": false } ], "description": "Must provide exactly one: either dispute_id OR dispute object data (without account_id), but not both." } }, "required": [ "account_id", "dispute" ], "description": "You can either:\n\n1. Provide an existing `dispute_id` to associate the evidence with a previously created dispute, \n2. Create a new dispute inline by including all required parameters as defined in the Create a Dispute endpoint documentation" } } } }, "responses": { "200": { "description": "Evidence generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 1000, "description": "The unique Chargeflow object identifier of the evidence.", "example": "ev_abc123456789" }, "account_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the evidence belongs.", "example": "66e6ea9ecd94925a9f8060d9" }, "ext_account_id": { "type": "string", "maxLength": 1000, "description": "The unique account identifier appears on the platform.", "example": "ext_acct_54321" }, "dispute": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow dispute identifier to which the evidence associated with.", "example": "dp_112233445" }, "created_at": { "type": "string", "format": "date-time", "description": "The time at which the evidence was created at Chargeflow in ISO 8601 format.", "example": "2025-07-29T14:35:00Z" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "error" ], "description": "The status of the evidence generation.", "example": "in_progress" }, "file_url": { "type": "string", "format": "uri", "description": "A downloadable link to the generated evidence in a PDF format.", "example": "https://cdn.chargeflow.io/evidence/ev_abc123456789/v2/evidence.pdf" }, "file_version": { "type": "integer", "exclusiveMinimum": 0, "description": "The version number of the file; each version reflects a complete file regeneration of the evidence, incrementing with every regeneration to track the history of changes over time.", "example": 1 } }, "description": "Evidence-as-a-Service (EaaS) is an AI-powered engine designed to generate compelling, data-backed evidence for disputes. It creates high-quality narratives that support the merchant's position to refute disputes. The more relevant data provided, the stronger and more precise the output becomes, turning raw data into actionable, persuasive evidence at scale." } } } }, "400": { "description": "Bad Request - User is not a platform or EAAS is not enabled for this platform" }, "401": { "description": "Unauthorized - Missing or invalid authentication" }, "403": { "description": "Forbidden - User is not a platform" }, "404": { "description": "Not Found - Dispute not found" }, "500": { "description": "Internal Server Error" } } } }, "/public/2025-04-01/evidence/{evidenceId}": { "get": { "tags": [ "Evidence" ], "summary": "Get Evidence by ID", "description": "Retrieve a single evidence file details with the option to expand it with enriched dispute data using the expand request parameter.", "parameters": [ { "in": "path", "name": "evidenceId", "description": "The unique Chargeflow object identifier of the dispute.", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow object identifier of the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, "required": true }, { "in": "query", "name": "expand", "description": "### Available Expansions\n\nUse the `expand` parameter to include additional dispute resource details in the response.\n\n**Available options:**\n\n| Parameter | Description |\n|-----------|-------------|\n| `dispute` | Include the top-level dispute data in the response |\n| `dispute.transaction` | Full payment transaction details including amount, currency, payment method and more |\n| `dispute.order` | Complete order details including products, shipping, and fulfillment and more |\n| `dispute.subscription` | Complete subscription details including plan, frequency, cancellation reason and more |\n| `dispute.activity_logs` | Complete activity logs details including user events and interactions |\n\n", "schema": { "type": "array", "items": { "enum": [ "dispute", "dispute.transaction", "dispute.order", "dispute.subscription", "dispute.activity_logs" ] }, "title": "Expandable Fields", "description": "### Available Expansions\n\nUse the `expand` parameter to include additional dispute resource details in the response.\n\n**Available options:**\n\n| Parameter | Description |\n|-----------|-------------|\n| `dispute` | Include the top-level dispute data in the response |\n| `dispute.transaction` | Full payment transaction details including amount, currency, payment method and more |\n| `dispute.order` | Complete order details including products, shipping, and fulfillment and more |\n| `dispute.subscription` | Complete subscription details including plan, frequency, cancellation reason and more |\n| `dispute.activity_logs` | Complete activity logs details including user events and interactions |\n\n", "example": [ "dispute", "dispute.transaction" ] } } ], "responses": { "200": { "description": "Evidence details retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 1000, "description": "The unique Chargeflow object identifier of the evidence.", "example": "ev_abc123456789" }, "account_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the evidence belongs.", "example": "66e6ea9ecd94925a9f8060d9" }, "ext_account_id": { "type": "string", "maxLength": 1000, "description": "The unique account identifier appears on the platform.", "example": "ext_acct_54321" }, "dispute": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow object identifier of the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow object identifier of the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, "source": { "type": [ "string", "null" ], "enum": [ "paypal", "shopify", "maverick", "businessTrack", "cpanel", "globalPayments", "merlink", "braintree", "klarna", "square", "afterpay", "oceanpayment", "payarc", "firstview", "nexio", "elevate", "stripe", "goatPayments", "woopay", "nuvei", "safecharge", "zenPayments", "select", "checkout", "deposyt", "affirm", "adyen", "asana", "import", "import/induced", "samcart", "easyPayDirect", "paysafe", "bravapay", "micamp", "approvely", "platpay", "clover", "airwallex", "worldpay", "sezzle", "luqra", "paymentTech", "paymentsAI", "mamopay", "emsdata", "paymentsHub", "publicApi", "nmi", "wepay", "zippay", "paymentInsider", "trxServices", "merchantic", "wooPayments", "wooCommerce", "swipeSimple", "gmail", "zohoPayments", "recharge", "trustpay", "wixPayments", "venmo", "skrill", "blogicSystems", "useePay", "thinkific", "revolut", "kajabi", "tiktok", "authorizeNet", "nabankco", "finix", "zendesk", "gorgias", "cloudbeds", "swipearas", "amazonPay", "incheck", "platform", "ebanx", "kurvpay" ], "description": "The source of the dispute. name of the PSP", "example": "stripe" }, "source_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique dispute identifier appears on the source (processor) from which the dispute originated.", "example": "du_123456789" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the dispute belongs.", "example": "66e6ea9ecd94925a9f8060d9" }, "ext_account_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique account identifier appears on the platform. Null if not set by the platform.", "example": "acc_123456" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the dispute was created in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "reason": { "type": [ "string", "null" ], "enum": [ "fraud", "not_received", "not_as_described", "canceled_recurring_billing", "duplicate_charge", "credit_not_processed", "other" ], "description": "The reason the cardholder has disputed the transaction.", "example": "fraud" }, "due_by": { "type": [ "string", "null" ], "format": "date-time", "description": "The deadline to submit evidence to challenge the dispute in ISO 8601 format.", "example": "2024-02-20T12:00:00Z" }, "amount": { "type": [ "number", "null" ], "minimum": 0, "description": "Disputed amount. Equal to or less than the disputed transaction amount.", "example": 100 }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "status": { "type": [ "string", "null" ], "enum": [ "needs_response", "under_review", "won", "lost" ], "description": "The current status of the dispute.", "example": "needs_response" }, "stage": { "type": [ "string", "null" ], "enum": [ "Chargeback", "Inquiry", "Pre_arbitration", "Arbitration" ], "description": "The stage of the dispute.", "example": "Chargeback" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the dispute has been closed and resolved in ISO 8601 format. Returns null if the dispute is not yet closed.", "example": "2025-01-27T10:00:00Z" }, "transaction": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow transaction ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The transaction ID from the source.", "example": "tx_1234567890" } ], "description": "The transaction ID associated with the dispute. Can be a Chargeflow transaction identifier or a transaction identifier from the source.", "example": "tx_1234567890" }, { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow transaction ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The transaction ID from the source.", "example": "tx_1234567890" }, { "type": "null" } ], "description": "The transaction ID associated with the dispute. Can be a Chargeflow transaction identifier or a transaction identifier from the source.", "example": "tx_1234567890" }, "source_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique transaction identifier appears on the source from which the transaction originated.", "example": "tx_1234567890" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the transaction belongs.", "example": "66e6ea9ecd94925a9f8060d8" }, "ext_account_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique account identifier appears on the platform. Null if not set by the platform.", "example": "acc_123456" }, "order_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "example": "ord_1234567890" }, { "type": "null" } ], "description": "The order ID associated with the dispute. Can be a Chargeflow order identifier or an order identifier from the source.", "example": "ord_1234567890" }, "subscription_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow subscription ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The subscription ID from the source.", "example": "sub_1234567890" }, { "type": "null" } ], "description": "The subscription ID associated with the dispute. Can be a Chargeflow subscription identifier or a subscription identifier from the source.", "example": "66e6ea9ecd94925a9f8060d9" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the transaction was created at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "type": { "type": [ "string", "null" ], "enum": [ "paid", "partially_paid", "refunded", "partially_refunded" ], "description": "The type of the transaction", "example": "paid" }, "amount": { "type": [ "number", "null" ], "minimum": 0, "description": "Transaction total amount after all deductions.", "example": 100 }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "payment_method": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The full name of the person to which the payment method belongs to.", "example": "John Doe" }, "type": { "type": [ "string", "null" ], "enum": [ "card", "wallet" ], "description": "The type of the payment method", "example": "card" }, "last4": { "type": [ "string", "null" ], "pattern": "^\\d{4}$", "minLength": 4, "maxLength": 4, "description": "The last four digits of the card used for the transaction. `card`", "example": "1234" }, "expiry_month": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 12, "description": "The month when the card used for the transaction is expired. `card`", "example": 1 }, "expiry_year": { "type": [ "integer", "null" ], "minimum": 2019, "maximum": 2100, "description": "The year when the card used for the transaction is expired. `card`", "example": 2025 }, "brand": { "type": [ "string", "null" ], "enum": [ "visa", "mastercard", "discover", "amex", "jcb", "unionpay", "diners", "other" ], "description": "The card brand used for the transaction. `card`", "example": "visa" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "The card issuance country - two-letter country code (ISO 3166-1 alpha-2). `card`", "example": "US" }, "wallet": { "type": [ "string", "null" ], "enum": [ "paypal", "klarna", "affirm", "afterpay", "sezzle", "zip", "venmo", "apple", "other" ], "description": "The name of the wallet which used for the transaction. `wallet`", "example": "paypal" }, "checks": { "type": "object", "properties": { "three_d_secure_result": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The 3D secure authentication outcome. `card`", "example": "passed" }, "avs_results": { "type": [ "string", "null" ], "enum": [ "N", "A", "Y", "Z" ], "description": "The address verification system outcome. `card`", "example": "N" }, "address_line1_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The address line1 check result. `card`", "example": "passed" }, "address_zip_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The address zip or postal code check result. `card`", "example": "passed" }, "cvc_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The card verification code result. `card`", "example": "passed" } }, "description": "The checks performed by the network at the time of payment. `card`" }, "wallet_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 128, "description": "The email address of the wallet which used for the transaction. `wallet`", "example": "john.doe@example.com" }, "wallet_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The wallet unique identifier which used for the transaction. `wallet`", "example": "1234567890" } }, "description": "The payment method used for the transaction.", "example": { "type": "card", "name": "John Doe", "last4": "1234", "expiry_month": 1, "expiry_year": 2025, "brand": "visa" } }, "billing_address": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The name of the person associated with the billing address.", "example": "John Doe" }, "line1": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "example": "123 Main St" }, "line2": { "type": [ "string", "null" ], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "example": "Apt 1" }, "city": { "type": [ "string", "null" ], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "example": "San Francisco" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Two-letter country code (ISO 3166-1 alpha-2) associated with the address lines", "example": "US" }, "state": { "type": [ "string", "null" ], "description": "State, county, province, or region associated with the address lines.", "example": "CA" }, "zip_code": { "type": [ "string", "null" ], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "example": "12345" }, "phone": { "type": [ "string", "null" ], "description": "The phone number of the person associated with the billing address.", "example": "1(123)4567890" } }, "description": "The billing address associated with the payment method at the time of the transaction.", "example": { "name": "John Doe", "line1": "123 Main St", "line2": "Apt 1", "city": "Anytown", "state": "NY", "zip_code": "12345", "country": "US", "phone": "+1234567890" } } }, "description": "A transaction represents a money exchange between a buyer and a merchant in return for a physical product, digital product, service, booking, or other goods and offerings." }, { "type": "null" } ], "description": "The unique `Chargeflow` transaction identifier or the data of the transaction.", "example": "66e6ea9ecd94925a9f8060d9" }, "subscription": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The subscription ID associated with the dispute. Can be a Chargeflow subscription identifier or a subscription identifier from the source.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The subscription ID associated with the dispute. Can be a Chargeflow subscription identifier or a subscription identifier from the source.", "example": "66e6ea9ecd94925a9f8060d9" }, "source_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique subscription identifier appears on the source from which the subscription originated.", "example": "source_sub_1234567890" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the subscription belongs.", "example": "66e6ea9ecd94925a9f8060d9" }, "ext_account_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique account identifier appears on the platform. Null if not set by the platform.", "example": "acc_123456" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was created at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was updated at the source in ISO 8601 format.", "example": "2024-02-15T12:00:00Z" }, "start_date": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was started at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "end_date": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was ended at the source in ISO 8601 format.", "example": "2024-08-10T12:00:00Z" }, "cancellation_date": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was requested to be canceled at the source in ISO 8601 format. Returns null if a cancellation is never requested.", "example": "2024-07-10T12:00:00Z" }, "frequency": { "type": [ "string", "null" ], "enum": [ "day", "week", "month", "year" ], "description": "The frequency at which a subscription is billed.", "example": "month" }, "frequency_count": { "type": [ "integer", "null" ], "minimum": 1, "description": "The number of intervals per billing cycle. For example, if frequency = month and frequency_count = 1, the subscription renews every month. If frequency_count = 3, the subscription renews every three months.", "example": 1 }, "cancellation_reason": { "type": [ "string", "null" ], "enum": [ "too_expensive", "low_quality", "unused", "too_complex", "missing_features" ], "description": "The submitted reason for why the subscription has canceled.", "example": "too_expensive" }, "collection_method": { "type": [ "string", "null" ], "enum": [ "automatically", "automatically_with_reminder", "send_invoice" ], "description": "The billing method for the subscription.", "example": "automatically" }, "trial_start": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the trial of the subscription began at the source in ISO 8601 format. Returns null if no trial is offered or if the trial was not utilized.", "example": "2024-02-10T12:00:00Z" }, "trial_end": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the trial of the subscription ended at the source in ISO 8601 format. Returns null if no trial is offered or if the trial was not utilized.", "example": "2024-03-10T12:00:00Z" }, "renews_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription cycle renews at the source in ISO 8601 format. Returns null if the subscription has been canceled.", "example": "2024-03-10T12:00:00Z" }, "plan_name": { "type": [ "string", "null" ], "description": "The name of the plan associated with the subscription, representing the specific offering or service tier the subscriber is enrolled in.", "example": "Pro Plan" }, "pricing_model": { "type": [ "string", "null" ], "enum": [ "fixed_price", "usage_base" ], "description": "The pricing model associated with the subscription.", "example": "fixed_price" }, "status": { "type": [ "string", "null" ], "enum": [ "active", "inactive", "canceled" ], "description": "The current status of the subscription.", "example": "active" } }, "description": "A subscription represents a recurring payment between a buyer and a merchant." }, { "type": "null" } ], "description": "The unique `Chargeflow` subscription identifier or the data of the subscription.", "example": "66e6ea9ecd94925a9f8060d9" }, "order": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "example": "ord_1234567890" } ], "description": "The order ID associated with the dispute. Can be a Chargeflow order identifier or an order identifier from the source.", "example": "ord_1234567890" }, { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "example": "ord_1234567890" }, { "type": "null" } ], "description": "The order ID associated with the dispute. Can be a Chargeflow order identifier or an order identifier from the source.", "example": "ord_1234567890" }, "source_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique order identifier appears on the source from which the order originated.", "example": "order_1234567890" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the order belongs.", "example": "act_1234567890" }, "ext_account_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique account identifier appears on the platform. Null if not set by the platform.", "example": "acc_123456" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the order was created at the source in ISO 8601 format.", "example": "2025-01-27T10:00:00Z" }, "payment_status": { "type": [ "string", "null" ], "enum": [ "paid", "partially_paid", "refunded", "partially_refunded" ], "description": "The financial status of the order", "example": "paid" }, "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The order name or number as appear in your source", "example": "#ORD-12345" }, "type": { "type": [ "string", "null" ], "enum": [ "standard", "pre_order" ], "description": "The type of the order; defaults to standard.", "example": "standard" }, "amount": { "type": [ "number", "null" ], "minimum": 0, "description": "Order total amount after all deductions.", "example": 1000 }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "customer": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The full name of the customer who have made this order.", "example": "John Doe" }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 128, "description": "The email address belong to the customer. Valid format:", "example": "example@mail.com" }, "customer_since": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the customer has made their first order with the merchant in ISO 8601 format.", "example": "2025-01-27T10:00:00Z" }, "order_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "The count of orders made by this customer with the merchant.", "example": 1 }, "phone_number": { "type": [ "string", "null" ], "maxLength": 128, "description": "The phone number belong to the customer. Valid format:", "example": "1(123)4567890" }, "ip_address": { "type": [ "string", "null" ], "maxLength": 128, "description": "The IP address belongs to the customer in the context of the given order. Valid format: IPv4 or IPv6.", "example": "192.168.1.1" }, "verified_email": { "type": [ "boolean", "null" ], "description": "Whether the customer email address was verified by the merchant. If `true`, the customer's email was verified at least once by the merchant.", "example": true } }, "description": "The customer who made this order." }, "products": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The product name as appear on the merchant's product catalog.", "example": "Product Name" }, "id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The product unique identifier. Relevant to link it to tracking number and shipping method.", "example": "123456789" }, "type": { "type": [ "string", "null" ], "enum": [ "physical_good", "digital_good", "service", "other" ], "description": "The type of the product", "example": "physical_good" }, "quantity": { "type": [ "integer", "null" ], "minimum": 1, "description": "The number of items that were purchased.", "example": 1 }, "description": { "type": [ "string", "null" ], "maxLength": 1000, "description": "A short description of the product as communicated to the customer in the merchant's product page.", "example": "Product Description" }, "image_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 1000, "description": "A url of the primary product image associated with the product. Valid format:", "example": "https://myurl.com/image/product/123456789" }, "price": { "type": [ "number", "null" ], "minimum": 0, "description": "The price amount of the given product in the order's currency.", "example": 100 } } }, "description": "An array of the products purchased in this order." }, "shipping_address": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The name of the person associated with the shipping address.", "example": "John Doe" }, "line1": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "example": "123 Main St" }, "line2": { "type": [ "string", "null" ], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "example": "Apt 1" }, "city": { "type": [ "string", "null" ], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "example": "San Francisco" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Two-letter country code (ISO 3166-1 alpha-2) associated with the address lines", "example": "US" }, "state": { "type": [ "string", "null" ], "description": "State, county, province, or region associated with the address lines.", "example": "CA" }, "zip_code": { "type": [ "string", "null" ], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "example": "12345" }, "phone": { "type": [ "string", "null" ], "description": "The phone number of the person associated with the shipping address.", "example": "1(123)4567890" } }, "description": "The shipping address associated with the order." }, "fulfillments": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "product_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The product's unique identifier to which the shipping method and tracking number was applied. Set to null if this was applied to all products in this order.", "example": "123456789" }, "shipped_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the order was shipped in ISO 8601 format.", "example": "2025-01-27T10:00:00Z" }, "shipping_line_title": { "type": [ "string", "null" ], "maxLength": 128, "description": "The shipping line title.", "example": "FedEx" }, "shipping_method_price": { "type": [ "number", "null" ], "minimum": 0, "description": "The shipping method price as paid by the customer in the order's currency.", "example": 100 }, "tracking_number": { "type": [ "string", "null" ], "maxLength": 128, "description": "The tracking number that was provided to track the fulfillment journey.", "example": "123456789" }, "courier": { "type": [ "string", "null" ], "maxLength": 128, "description": "The shipping courier from which the tracking number originated and used to fulfill the order.", "example": "FedEx" } } }, "description": "Details about the order shipping lines and tracking numbers." } }, "description": "An order is a record of a customer's purchase request, detailing the items bought, payment information, fulfillment status, and more." }, { "type": "null" } ], "description": "The unique `Chargeflow` order identifier or the data of the order." } } } ] }, "created_at": { "type": "string", "format": "date-time", "description": "The time at which the evidence was created at Chargeflow in ISO 8601 format.", "example": "2025-07-29T14:35:00Z" }, "status": { "type": "string", "enum": [ "in_progress", "completed", "error" ], "description": "The status of the evidence generation.", "example": "in_progress" }, "file_url": { "type": "string", "format": "uri", "description": "A downloadable link to the generated evidence in a PDF format.", "example": "https://cdn.chargeflow.io/evidence/ev_abc123456789/v2/evidence.pdf" }, "file_version": { "type": "integer", "exclusiveMinimum": 0, "description": "The version number of the file; each version reflects a complete file regeneration of the evidence, incrementing with every regeneration to track the history of changes over time.", "example": 1 } }, "required": [ "dispute" ] } } } }, "400": { "description": "Bad Request:\n - Evidence ID is required\n - User is not a platform\n - EAAS is not enabled" }, "401": { "description": "Unauthorized - Missing or invalid authentication" }, "403": { "description": "Forbidden - Unauthorized access to resource" }, "404": { "description": "Not Found:\n - Evidence not found\n - This dispute was not found. Please recheck the dispute ID or create a new one inline/via the Disputes API" }, "500": { "description": "Internal Server Error" } } } }, "/public/2025-04-01/platform/disputes": { "post": { "tags": [ "Merchants 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": { "source_id": { "type": "string", "maxLength": 128, "description": "The unique dispute identifier appears on the source (processor) from which the dispute originated.", "example": "du_123456789" }, "account_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the dispute belongs. (Platforms only)", "example": "66e6ea9ecd94925a9f8060d9" }, "created_at": { "type": "string", "format": "date-time", "description": "The time at which the dispute was created at the processor in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "reason": { "type": "string", "enum": [ "fraud", "not_received", "not_as_described", "canceled_recurring_billing", "duplicate_charge", "credit_not_processed", "other" ], "description": "The reason the cardholder has disputed the transaction.", "example": "fraud" }, "due_by": { "type": "string", "format": "date-time", "description": "The deadline to submit evidence to challenge the dispute in ISO 8601 format.", "example": "2024-02-20T12:00:00Z" }, "amount": { "type": "number", "minimum": 0, "description": "Disputed amount. Equal to or less than the disputed transaction amount.", "example": 100 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "status": { "type": "string", "enum": [ "needs_response", "under_review", "won", "lost" ], "description": "The current status of the dispute.", "example": "needs_response" }, "stage": { "type": "string", "enum": [ "Chargeback", "Inquiry", "Pre_arbitration", "Arbitration" ], "default": "Chargeback", "description": "The stage of the dispute. Default is chargeback.", "example": "Chargeback" }, "transaction": { "type": "object", "properties": { "source_id": { "type": "string", "maxLength": 128, "description": "The unique transaction identifier appears on the source from which the transaction originated.", "example": "tx_1234567890" }, "account_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the transaction belongs.", "example": "66e6ea9ecd94925a9f8060d9" }, "created_at": { "type": "string", "format": "date-time", "description": "The time at which the transaction was created at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "type": { "type": "string", "enum": [ "paid", "partially_paid", "refunded", "partially_refunded" ], "description": "The type of the transaction", "example": "paid" }, "amount": { "type": "number", "minimum": 0, "description": "Transaction total amount after all deductions.", "example": 100 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "payment_method": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The full name of the person to which the payment method belongs to.", "example": "John Doe" }, "type": { "type": [ "string", "null" ], "enum": [ "card", "wallet" ], "description": "The type of the payment method", "example": "card" }, "last4": { "type": [ "string", "null" ], "pattern": "^\\d{4}$", "minLength": 4, "maxLength": 4, "description": "The last four digits of the card used for the transaction. `card`", "example": "1234" }, "expiry_month": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 12, "description": "The month when the card used for the transaction is expired. `card`", "example": 1 }, "expiry_year": { "type": [ "integer", "null" ], "minimum": 2019, "maximum": 2100, "description": "The year when the card used for the transaction is expired. `card`", "example": 2025 }, "brand": { "type": [ "string", "null" ], "enum": [ "visa", "mastercard", "discover", "amex", "jcb", "unionpay", "diners", "other" ], "description": "The card brand used for the transaction. `card`", "example": "visa" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "The card issuance country - two-letter country code (ISO 3166-1 alpha-2). `card`", "example": "US" }, "wallet": { "type": [ "string", "null" ], "enum": [ "paypal", "klarna", "affirm", "afterpay", "sezzle", "zip", "venmo", "apple", "other" ], "description": "The name of the wallet which used for the transaction. `wallet`", "example": "paypal" }, "checks": { "type": "object", "properties": { "three_d_secure_result": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The 3D secure authentication outcome. `card`", "example": "passed" }, "avs_results": { "type": [ "string", "null" ], "enum": [ "N", "A", "Y", "Z" ], "description": "The address verification system outcome. `card`", "example": "N" }, "address_line1_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The address line1 check result. `card`", "example": "passed" }, "address_zip_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The address zip or postal code check result. `card`", "example": "passed" }, "cvc_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The card verification code result. `card`", "example": "passed" } }, "description": "The checks performed by the network at the time of payment. `card`" }, "wallet_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 128, "description": "The email address of the wallet which used for the transaction. `wallet`", "example": "john.doe@example.com" }, "wallet_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The wallet unique identifier which used for the transaction. `wallet`", "example": "1234567890" } }, "description": "The payment method used by the customer to process the transaction." }, "billing_address": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The name of the person associated with the billing address.", "example": "John Doe" }, "line1": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "example": "123 Main St" }, "line2": { "type": [ "string", "null" ], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "example": "Apt 1" }, "city": { "type": [ "string", "null" ], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "example": "San Francisco" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Two-letter country code (ISO 3166-1 alpha-2) associated with the address lines", "example": "US" }, "state": { "type": [ "string", "null" ], "description": "State, county, province, or region associated with the address lines.", "example": "CA" }, "zip_code": { "type": [ "string", "null" ], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "example": "12345" }, "phone": { "type": [ "string", "null" ], "description": "The phone number of the person associated with the billing address.", "example": "1(123)4567890" } }, "description": "The billing address associated with the payment method at the time of the transaction" }, "order_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "example": "ord_1234567890" } ], "description": "The unique Chargeflow identifier of the order to which the transaction is linked.", "example": "66e6ea9ecd94925a9f8060d9" }, "subscription_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow identifier of the subscription to which the transaction is linked.", "example": "66e6ea9ecd94925a9f8060d9" } }, "required": [ "source_id", "account_id", "created_at", "type", "amount", "currency" ], "description": "Creates a new Chargeflow transaction." }, "subscription": { "type": "object", "properties": { "source_id": { "type": "string", "maxLength": 128, "description": "The unique subscription identifier appears on the source from which the subscription originated.", "example": "source_sub_1234567890" }, "account_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the subscription belongs. This field is `required` for platform users.", "example": "66e6ea9ecd94925a9f8060d9" }, "created_at": { "type": "string", "format": "date-time", "description": "The time at which the subscription was created at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "start_date": { "type": "string", "format": "date-time", "description": "The time at which the subscription was started at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "frequency": { "type": "string", "enum": [ "day", "week", "month", "year" ], "description": "The frequency at which a subscription is billed.", "example": "month" }, "frequency_count": { "type": "integer", "minimum": 1, "description": "The number of intervals per billing cycle. For example, if frequency = month and frequency_count = 1, the subscription renews every month. If frequency_count = 3, the subscription renews every three months.", "example": 1 }, "collection_method": { "type": "string", "enum": [ "automatically", "automatically_with_reminder", "send_invoice" ], "default": "automatically", "description": "The billing method for the subscription.", "example": "automatically" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was updated at the source in ISO 8601 format.", "example": "2024-02-15T12:00:00Z" }, "end_date": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was ended at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "cancellation_date": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was requested to be canceled at the source in ISO 8601 format. Returns null if a cancellation is never requested.", "example": "2024-07-10T12:00:00Z" }, "cancellation_reason": { "type": [ "string", "null" ], "enum": [ "too_expensive", "low_quality", "unused", "too_complex", "missing_features" ], "description": "The submitted reason for why the subscription has canceled.", "example": "too_expensive" }, "trial_start": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the trial of the subscription began at the source in ISO 8601 format. Returns null if no trial is offered or if the trial was not utilized.", "example": "2024-02-10T12:00:00Z" }, "trial_end": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the trial of the subscription ended at the source in ISO 8601 format. Returns null if no trial is offered or if the trial was not utilized.", "example": "2024-03-10T12:00:00Z" }, "renews_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription cycle renews at the source in ISO 8601 format. Returns null if the subscription has been canceled.", "example": "2024-03-10T12:00:00Z" }, "plan_name": { "type": [ "string", "null" ], "description": "The name of the plan associated with the subscription, representing the specific offering or service tier the subscriber is enrolled in.", "example": "Pro Plan" }, "pricing_model": { "type": "string", "enum": [ "fixed_price", "usage_base" ], "default": "fixed_price", "description": "The pricing model associated with the subscription.", "example": "fixed_price" }, "status": { "type": "string", "enum": [ "active", "inactive", "canceled" ], "default": "active", "description": "The current status of the subscription.", "example": "active" } }, "required": [ "source_id", "created_at", "start_date", "frequency", "frequency_count" ], "description": "Creates a new Chargeflow subscription." }, "order": { "type": "object", "properties": { "source_id": { "type": "string", "maxLength": 128, "description": "The unique order identifier appears on the source from which the order originated.", "example": "order_1234567890" }, "account_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the order belongs.", "example": "acct_1234567890" }, "created_at": { "type": "string", "format": "date-time", "description": "The time at which the order was created at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "payment_status": { "type": "string", "enum": [ "paid", "partially_paid", "refunded", "partially_refunded" ], "description": "The financial status of the order", "example": "paid" }, "amount": { "type": "number", "minimum": 0, "description": "Order total amount after all deductions.", "example": 1000 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "name": { "type": "string", "maxLength": 128, "description": "The order name or number as appear in your source", "example": "#ORD-12345" }, "type": { "type": "string", "enum": [ "standard", "pre_order" ], "default": "standard", "description": "The type of the order; defaults to standard.", "example": "standard" }, "customer": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 128, "description": "The full name of the customer who have made this order.", "example": "John Doe" }, "email": { "type": "string", "format": "email", "maxLength": 128, "description": "The email address belong to the customer. Valid format:", "example": "example@mail.com" }, "customer_since": { "type": "string", "format": "date-time", "description": "The time at which the customer has made their first order with the merchant in ISO 8601 format.", "example": "2025-01-27T10:00:00Z" }, "order_count": { "type": "integer", "minimum": 0, "description": "The count of orders made by this customer with the merchant.", "example": 1 }, "phone_number": { "type": "string", "maxLength": 128, "description": "The phone number belong to the customer. Valid format:", "example": "1(123)4567890" }, "ip_address": { "type": "string", "maxLength": 128, "description": "The IP address belongs to the customer in the context of the given order. Valid format: IPv4 or IPv6.", "example": "192.168.1.1" }, "verified_email": { "type": "boolean", "description": "Whether the customer email address was verified by the merchant. If `true`, the customer's email was verified at least once by the merchant.", "example": true } }, "required": [ "name", "email" ], "description": "The customer who made this order." }, "products": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 128, "description": "The product name as appear on the merchant's product catalog.", "example": "Product Name" }, "id": { "type": "string", "maxLength": 128, "description": "The product unique identifier. Relevant to link it to tracking number and shipping method.", "example": "123456789" }, "type": { "type": "string", "enum": [ "physical_good", "digital_good", "service", "other" ], "description": "The type of the product", "example": "physical_good" }, "quantity": { "type": "integer", "minimum": 1, "description": "The number of items that were purchased.", "example": 1 }, "description": { "type": "string", "maxLength": 1000, "description": "A short description of the product as communicated to the customer in the merchant's product page.", "example": "Product Description" }, "image_url": { "type": "string", "format": "uri", "maxLength": 1000, "description": "A url of the primary product image associated with the product. Valid format:", "example": "https://myurl.com/image/product/123456789" }, "price": { "type": "number", "minimum": 0, "description": "The price amount of the given product in the order's currency.", "example": 100 } }, "required": [ "name", "type", "quantity", "price" ] }, "description": "An array of the products purchased in this order." }, "shipping_address": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The name of the person associated with the shipping address.", "example": "John Doe" }, "line1": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "example": "123 Main St" }, "line2": { "type": [ "string", "null" ], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "example": "Apt 1" }, "city": { "type": [ "string", "null" ], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "example": "San Francisco" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Two-letter country code (ISO 3166-1 alpha-2) associated with the address lines", "example": "US" }, "state": { "type": [ "string", "null" ], "description": "State, county, province, or region associated with the address lines.", "example": "CA" }, "zip_code": { "type": [ "string", "null" ], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "example": "12345" }, "phone": { "type": [ "string", "null" ], "description": "The phone number of the person associated with the shipping address.", "example": "1(123)4567890" } } }, "fulfillments": { "type": "array", "items": { "type": "object", "properties": { "product_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The product's unique identifier to which the shipping method and tracking number was applied. Set to null if this was applied to all products in this order.", "example": "123456789" }, "shipped_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the order was shipped in ISO 8601 format.", "example": "2025-01-27T10:00:00Z" }, "shipping_line_title": { "type": [ "string", "null" ], "maxLength": 128, "description": "The shipping line title.", "example": "FedEx" }, "shipping_method_price": { "type": [ "number", "null" ], "minimum": 0, "description": "The shipping method price as paid by the customer in the order's currency.", "example": 100 }, "tracking_number": { "type": [ "string", "null" ], "maxLength": 128, "description": "The tracking number that was provided to track the fulfillment journey.", "example": "123456789" }, "courier": { "type": [ "string", "null" ], "maxLength": 128, "description": "The shipping courier from which the tracking number originated and used to fulfill the order.", "example": "FedEx" } } } } }, "required": [ "source_id", "account_id", "created_at", "payment_status", "amount", "currency" ], "description": "Creates a new Chargeflow order." } }, "required": [ "source_id", "account_id", "created_at", "reason", "due_by", "amount", "currency", "status" ] } } } }, "responses": { "200": { "description": "Dispute created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow object identifier of the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, "source": { "type": [ "string", "null" ], "enum": [ "paypal", "shopify", "maverick", "businessTrack", "cpanel", "globalPayments", "merlink", "braintree", "klarna", "square", "afterpay", "oceanpayment", "payarc", "firstview", "nexio", "elevate", "stripe", "goatPayments", "woopay", "nuvei", "safecharge", "zenPayments", "select", "checkout", "deposyt", "affirm", "adyen", "asana", "import", "import/induced", "samcart", "easyPayDirect", "paysafe", "bravapay", "micamp", "approvely", "platpay", "clover", "airwallex", "worldpay", "sezzle", "luqra", "paymentTech", "paymentsAI", "mamopay", "emsdata", "paymentsHub", "publicApi", "nmi", "wepay", "zippay", "paymentInsider", "trxServices", "merchantic", "wooPayments", "wooCommerce", "swipeSimple", "gmail", "zohoPayments", "recharge", "trustpay", "wixPayments", "venmo", "skrill", "blogicSystems", "useePay", "thinkific", "revolut", "kajabi", "tiktok", "authorizeNet", "nabankco", "finix", "zendesk", "gorgias", "cloudbeds", "swipearas", "amazonPay", "incheck", "platform", "ebanx", "kurvpay" ], "description": "The source of the dispute. name of the PSP", "example": "stripe" }, "source_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique dispute identifier appears on the source (processor) from which the dispute originated.", "example": "du_123456789" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the dispute belongs.", "example": "66e6ea9ecd94925a9f8060d9" }, "ext_account_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique account identifier appears on the platform. Null if not set by the platform.", "example": "acc_123456" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the dispute was created in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "reason": { "type": [ "string", "null" ], "enum": [ "fraud", "not_received", "not_as_described", "canceled_recurring_billing", "duplicate_charge", "credit_not_processed", "other" ], "description": "The reason the cardholder has disputed the transaction.", "example": "fraud" }, "due_by": { "type": [ "string", "null" ], "format": "date-time", "description": "The deadline to submit evidence to challenge the dispute in ISO 8601 format.", "example": "2024-02-20T12:00:00Z" }, "amount": { "type": [ "number", "null" ], "minimum": 0, "description": "Disputed amount. Equal to or less than the disputed transaction amount.", "example": 100 }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "status": { "type": [ "string", "null" ], "enum": [ "needs_response", "under_review", "won", "lost" ], "description": "The current status of the dispute.", "example": "needs_response" }, "stage": { "type": [ "string", "null" ], "enum": [ "Chargeback", "Inquiry", "Pre_arbitration", "Arbitration" ], "description": "The stage of the dispute.", "example": "Chargeback" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the dispute has been closed and resolved in ISO 8601 format. Returns null if the dispute is not yet closed.", "example": "2025-01-27T10:00:00Z" }, "transaction": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow transaction ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The transaction ID from the source.", "example": "tx_1234567890" } ], "description": "The transaction ID associated with the dispute. Can be a Chargeflow transaction identifier or a transaction identifier from the source.", "example": "tx_1234567890" }, { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow transaction ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The transaction ID from the source.", "example": "tx_1234567890" }, { "type": "null" } ], "description": "The transaction ID associated with the dispute. Can be a Chargeflow transaction identifier or a transaction identifier from the source.", "example": "tx_1234567890" }, "source_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique transaction identifier appears on the source from which the transaction originated.", "example": "tx_1234567890" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the transaction belongs.", "example": "66e6ea9ecd94925a9f8060d8" }, "ext_account_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique account identifier appears on the platform. Null if not set by the platform.", "example": "acc_123456" }, "order_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "example": "ord_1234567890" }, { "type": "null" } ], "description": "The order ID associated with the dispute. Can be a Chargeflow order identifier or an order identifier from the source.", "example": "ord_1234567890" }, "subscription_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow subscription ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The subscription ID from the source.", "example": "sub_1234567890" }, { "type": "null" } ], "description": "The subscription ID associated with the dispute. Can be a Chargeflow subscription identifier or a subscription identifier from the source.", "example": "66e6ea9ecd94925a9f8060d9" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the transaction was created at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "type": { "type": [ "string", "null" ], "enum": [ "paid", "partially_paid", "refunded", "partially_refunded" ], "description": "The type of the transaction", "example": "paid" }, "amount": { "type": [ "number", "null" ], "minimum": 0, "description": "Transaction total amount after all deductions.", "example": 100 }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "payment_method": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The full name of the person to which the payment method belongs to.", "example": "John Doe" }, "type": { "type": [ "string", "null" ], "enum": [ "card", "wallet" ], "description": "The type of the payment method", "example": "card" }, "last4": { "type": [ "string", "null" ], "pattern": "^\\d{4}$", "minLength": 4, "maxLength": 4, "description": "The last four digits of the card used for the transaction. `card`", "example": "1234" }, "expiry_month": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 12, "description": "The month when the card used for the transaction is expired. `card`", "example": 1 }, "expiry_year": { "type": [ "integer", "null" ], "minimum": 2019, "maximum": 2100, "description": "The year when the card used for the transaction is expired. `card`", "example": 2025 }, "brand": { "type": [ "string", "null" ], "enum": [ "visa", "mastercard", "discover", "amex", "jcb", "unionpay", "diners", "other" ], "description": "The card brand used for the transaction. `card`", "example": "visa" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "The card issuance country - two-letter country code (ISO 3166-1 alpha-2). `card`", "example": "US" }, "wallet": { "type": [ "string", "null" ], "enum": [ "paypal", "klarna", "affirm", "afterpay", "sezzle", "zip", "venmo", "apple", "other" ], "description": "The name of the wallet which used for the transaction. `wallet`", "example": "paypal" }, "checks": { "type": "object", "properties": { "three_d_secure_result": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The 3D secure authentication outcome. `card`", "example": "passed" }, "avs_results": { "type": [ "string", "null" ], "enum": [ "N", "A", "Y", "Z" ], "description": "The address verification system outcome. `card`", "example": "N" }, "address_line1_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The address line1 check result. `card`", "example": "passed" }, "address_zip_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The address zip or postal code check result. `card`", "example": "passed" }, "cvc_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The card verification code result. `card`", "example": "passed" } }, "description": "The checks performed by the network at the time of payment. `card`" }, "wallet_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 128, "description": "The email address of the wallet which used for the transaction. `wallet`", "example": "john.doe@example.com" }, "wallet_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The wallet unique identifier which used for the transaction. `wallet`", "example": "1234567890" } }, "description": "The payment method used for the transaction.", "example": { "type": "card", "name": "John Doe", "last4": "1234", "expiry_month": 1, "expiry_year": 2025, "brand": "visa" } }, "billing_address": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The name of the person associated with the billing address.", "example": "John Doe" }, "line1": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "example": "123 Main St" }, "line2": { "type": [ "string", "null" ], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "example": "Apt 1" }, "city": { "type": [ "string", "null" ], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "example": "San Francisco" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Two-letter country code (ISO 3166-1 alpha-2) associated with the address lines", "example": "US" }, "state": { "type": [ "string", "null" ], "description": "State, county, province, or region associated with the address lines.", "example": "CA" }, "zip_code": { "type": [ "string", "null" ], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "example": "12345" }, "phone": { "type": [ "string", "null" ], "description": "The phone number of the person associated with the billing address.", "example": "1(123)4567890" } }, "description": "The billing address associated with the payment method at the time of the transaction.", "example": { "name": "John Doe", "line1": "123 Main St", "line2": "Apt 1", "city": "Anytown", "state": "NY", "zip_code": "12345", "country": "US", "phone": "+1234567890" } } }, "description": "A transaction represents a money exchange between a buyer and a merchant in return for a physical product, digital product, service, booking, or other goods and offerings." }, { "type": "null" } ], "description": "The unique `Chargeflow` transaction identifier or the data of the transaction.", "example": "66e6ea9ecd94925a9f8060d9" }, "subscription": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The subscription ID associated with the dispute. Can be a Chargeflow subscription identifier or a subscription identifier from the source.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The subscription ID associated with the dispute. Can be a Chargeflow subscription identifier or a subscription identifier from the source.", "example": "66e6ea9ecd94925a9f8060d9" }, "source_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique subscription identifier appears on the source from which the subscription originated.", "example": "source_sub_1234567890" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the subscription belongs.", "example": "66e6ea9ecd94925a9f8060d9" }, "ext_account_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique account identifier appears on the platform. Null if not set by the platform.", "example": "acc_123456" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was created at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was updated at the source in ISO 8601 format.", "example": "2024-02-15T12:00:00Z" }, "start_date": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was started at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "end_date": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was ended at the source in ISO 8601 format.", "example": "2024-08-10T12:00:00Z" }, "cancellation_date": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was requested to be canceled at the source in ISO 8601 format. Returns null if a cancellation is never requested.", "example": "2024-07-10T12:00:00Z" }, "frequency": { "type": [ "string", "null" ], "enum": [ "day", "week", "month", "year" ], "description": "The frequency at which a subscription is billed.", "example": "month" }, "frequency_count": { "type": [ "integer", "null" ], "minimum": 1, "description": "The number of intervals per billing cycle. For example, if frequency = month and frequency_count = 1, the subscription renews every month. If frequency_count = 3, the subscription renews every three months.", "example": 1 }, "cancellation_reason": { "type": [ "string", "null" ], "enum": [ "too_expensive", "low_quality", "unused", "too_complex", "missing_features" ], "description": "The submitted reason for why the subscription has canceled.", "example": "too_expensive" }, "collection_method": { "type": [ "string", "null" ], "enum": [ "automatically", "automatically_with_reminder", "send_invoice" ], "description": "The billing method for the subscription.", "example": "automatically" }, "trial_start": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the trial of the subscription began at the source in ISO 8601 format. Returns null if no trial is offered or if the trial was not utilized.", "example": "2024-02-10T12:00:00Z" }, "trial_end": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the trial of the subscription ended at the source in ISO 8601 format. Returns null if no trial is offered or if the trial was not utilized.", "example": "2024-03-10T12:00:00Z" }, "renews_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription cycle renews at the source in ISO 8601 format. Returns null if the subscription has been canceled.", "example": "2024-03-10T12:00:00Z" }, "plan_name": { "type": [ "string", "null" ], "description": "The name of the plan associated with the subscription, representing the specific offering or service tier the subscriber is enrolled in.", "example": "Pro Plan" }, "pricing_model": { "type": [ "string", "null" ], "enum": [ "fixed_price", "usage_base" ], "description": "The pricing model associated with the subscription.", "example": "fixed_price" }, "status": { "type": [ "string", "null" ], "enum": [ "active", "inactive", "canceled" ], "description": "The current status of the subscription.", "example": "active" } }, "description": "A subscription represents a recurring payment between a buyer and a merchant." }, { "type": "null" } ], "description": "The unique `Chargeflow` subscription identifier or the data of the subscription.", "example": "66e6ea9ecd94925a9f8060d9" }, "order": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "example": "ord_1234567890" } ], "description": "The order ID associated with the dispute. Can be a Chargeflow order identifier or an order identifier from the source.", "example": "ord_1234567890" }, { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "example": "ord_1234567890" }, { "type": "null" } ], "description": "The order ID associated with the dispute. Can be a Chargeflow order identifier or an order identifier from the source.", "example": "ord_1234567890" }, "source_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique order identifier appears on the source from which the order originated.", "example": "order_1234567890" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the order belongs.", "example": "act_1234567890" }, "ext_account_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique account identifier appears on the platform. Null if not set by the platform.", "example": "acc_123456" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the order was created at the source in ISO 8601 format.", "example": "2025-01-27T10:00:00Z" }, "payment_status": { "type": [ "string", "null" ], "enum": [ "paid", "partially_paid", "refunded", "partially_refunded" ], "description": "The financial status of the order", "example": "paid" }, "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The order name or number as appear in your source", "example": "#ORD-12345" }, "type": { "type": [ "string", "null" ], "enum": [ "standard", "pre_order" ], "description": "The type of the order; defaults to standard.", "example": "standard" }, "amount": { "type": [ "number", "null" ], "minimum": 0, "description": "Order total amount after all deductions.", "example": 1000 }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "customer": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The full name of the customer who have made this order.", "example": "John Doe" }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 128, "description": "The email address belong to the customer. Valid format:", "example": "example@mail.com" }, "customer_since": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the customer has made their first order with the merchant in ISO 8601 format.", "example": "2025-01-27T10:00:00Z" }, "order_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "The count of orders made by this customer with the merchant.", "example": 1 }, "phone_number": { "type": [ "string", "null" ], "maxLength": 128, "description": "The phone number belong to the customer. Valid format:", "example": "1(123)4567890" }, "ip_address": { "type": [ "string", "null" ], "maxLength": 128, "description": "The IP address belongs to the customer in the context of the given order. Valid format: IPv4 or IPv6.", "example": "192.168.1.1" }, "verified_email": { "type": [ "boolean", "null" ], "description": "Whether the customer email address was verified by the merchant. If `true`, the customer's email was verified at least once by the merchant.", "example": true } }, "description": "The customer who made this order." }, "products": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The product name as appear on the merchant's product catalog.", "example": "Product Name" }, "id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The product unique identifier. Relevant to link it to tracking number and shipping method.", "example": "123456789" }, "type": { "type": [ "string", "null" ], "enum": [ "physical_good", "digital_good", "service", "other" ], "description": "The type of the product", "example": "physical_good" }, "quantity": { "type": [ "integer", "null" ], "minimum": 1, "description": "The number of items that were purchased.", "example": 1 }, "description": { "type": [ "string", "null" ], "maxLength": 1000, "description": "A short description of the product as communicated to the customer in the merchant's product page.", "example": "Product Description" }, "image_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 1000, "description": "A url of the primary product image associated with the product. Valid format:", "example": "https://myurl.com/image/product/123456789" }, "price": { "type": [ "number", "null" ], "minimum": 0, "description": "The price amount of the given product in the order's currency.", "example": 100 } } }, "description": "An array of the products purchased in this order." }, "shipping_address": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The name of the person associated with the shipping address.", "example": "John Doe" }, "line1": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "example": "123 Main St" }, "line2": { "type": [ "string", "null" ], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "example": "Apt 1" }, "city": { "type": [ "string", "null" ], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "example": "San Francisco" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Two-letter country code (ISO 3166-1 alpha-2) associated with the address lines", "example": "US" }, "state": { "type": [ "string", "null" ], "description": "State, county, province, or region associated with the address lines.", "example": "CA" }, "zip_code": { "type": [ "string", "null" ], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "example": "12345" }, "phone": { "type": [ "string", "null" ], "description": "The phone number of the person associated with the shipping address.", "example": "1(123)4567890" } }, "description": "The shipping address associated with the order." }, "fulfillments": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "product_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The product's unique identifier to which the shipping method and tracking number was applied. Set to null if this was applied to all products in this order.", "example": "123456789" }, "shipped_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the order was shipped in ISO 8601 format.", "example": "2025-01-27T10:00:00Z" }, "shipping_line_title": { "type": [ "string", "null" ], "maxLength": 128, "description": "The shipping line title.", "example": "FedEx" }, "shipping_method_price": { "type": [ "number", "null" ], "minimum": 0, "description": "The shipping method price as paid by the customer in the order's currency.", "example": 100 }, "tracking_number": { "type": [ "string", "null" ], "maxLength": 128, "description": "The tracking number that was provided to track the fulfillment journey.", "example": "123456789" }, "courier": { "type": [ "string", "null" ], "maxLength": 128, "description": "The shipping courier from which the tracking number originated and used to fulfill the order.", "example": "FedEx" } } }, "description": "Details about the order shipping lines and tracking numbers." } }, "description": "An order is a record of a customer's purchase request, detailing the items bought, payment information, fulfillment status, and more." }, { "type": "null" } ], "description": "The unique `Chargeflow` order identifier or the data of the order." } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "invalid_request_error", "description": "The type of error", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "user_not_platform", "eaas_not_enabled" ], "description": "Specific error code", "example": "user_not_platform" }, "message": { "type": "string", "enum": [ "User is not a platform", "EAAS is not enabled for this platform" ], "description": "Human-readable error message", "example": "User is not a platform" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "The request cannot be processed because the user is not a platform or EAAS is not enabled", "example": { "error": { "type": "invalid_request_error", "code": "user_not_platform", "message": "User is not a platform", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "PlatformDisputeCreationBadRequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "authentication_error", "description": "The type of error", "example": "authentication_error" }, "code": { "type": "string", "enum": [ "unauthorized", "invalid_credentials", "missing_credentials" ], "description": "Specific error code", "example": "unauthorized" }, "message": { "type": "string", "enum": [ "Unauthorized access", "Authentication credentials are missing or invalid" ], "description": "Human-readable error message", "example": "Unauthorized access" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Unauthorized - Authentication is required or has failed", "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "Unauthorized access", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "UnauthorizedError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "permission_error", "description": "The type of error", "example": "permission_error" }, "code": { "type": "string", "enum": [ "unauthorized_resource_access" ], "description": "Specific error code", "example": "unauthorized_resource_access" }, "message": { "type": "string", "enum": [ "Unauthorized access to resource" ], "description": "Human-readable error message", "example": "Unauthorized access to resource" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "The account_id does not belong to the authenticated platform", "example": { "error": { "type": "permission_error", "code": "unauthorized_resource_access", "message": "Unauthorized access to resource", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "PlatformDisputeForbiddenError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "api_error", "description": "The type of error", "example": "api_error" }, "code": { "type": "string", "enum": [ "internal_error", "server_error", "account_creation_failed", "account_retrieval_failed", "account_update_failed" ], "description": "Specific error code", "example": "internal_error" }, "message": { "type": "string", "enum": [ "Internal server error", "An unexpected error occurred", "Failed to create account", "Failed to get accounts", "Failed to update account" ], "description": "Human-readable error message", "example": "Internal server error" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Internal Server Error - Something went wrong on our end. Please try again later.", "example": { "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "InternalServerError" } } } } } } } }, "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", "example": "integration.access_error" }, "data": { "type": "object", "properties": { "account_id": { "type": "string", "description": "The unique Chargeflow object identifier of the account.", "example": "acct_1234567890" }, "integration_id": { "type": "string", "description": "The unique Chargeflow object identifier of the integration.", "example": "int_1234567890" }, "error_message": { "type": "string", "description": "The error message describing the access error.", "example": "Access token expired or invalid." } } }, "creationDate": { "type": "string", "format": "date-time", "description": "The creation date of the webhook in ISO8601 format", "example": "2021-01-01T00:00:00Z" }, "webhookId": { "type": "string", "format": "uuid", "default": "2ce92305-2f21-4888-a09f-3256bf7c678e", "description": "The webhook id", "example": "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", "example": "66e6ea9ecd94925a9f8060d9" }, "disputeId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow dispute identifier", "example": "66e6ea9ecd94925a9f8060d9" }, "evidenceId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow evidence identifier", "example": "66e6ea9ecd94925a9f8060d9" }, "fileUrl": { "type": "string", "description": "The URL to the generated evidence file", "example": "https://cdn.chargeflow.io/evidence/ev_abc123456789/v2/evidence.pdf" }, "version": { "type": "number", "description": "The version number of the evidence file", "example": 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", "example": "66e6ea9ecd94925a9f8060d9" }, "disputeId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow dispute identifier", "example": "66e6ea9ecd94925a9f8060d9" }, "evidenceId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow evidence identifier", "example": "66e6ea9ecd94925a9f8060d9" }, "errorCode": { "type": "string", "description": "The error code indicating the type of failure", "example": "EVIDENCE_GENERATION_FAILED" }, "errorMessage": { "type": "string", "description": "A descriptive message explaining the error", "example": "Failed to generate evidence PDF due to missing dispute data" }, "version": { "type": "number", "description": "The version number of the evidence file", "example": 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", "example": "dispute.created" }, "data": { "type": "object", "properties": { "chargeflowDisputeId": { "type": "string", "description": "The Chargeflow dispute id", "example": "66e6ea9ecd94925a9f8060d9" }, "dispute": { "type": "object", "properties": { "processorId": { "type": "string", "description": "The processor dispute id", "example": "PP-D-4012" }, "processor": { "type": "string", "description": "The dispute processor", "example": "paypal" }, "amount": { "type": "object", "properties": { "value": { "type": "number", "minimum": 0, "description": "The amount value", "example": 100 }, "currency": { "type": "string", "maxLength": 10, "description": "The three-letter ISO 4217 currency code represents the currency used for the amount", "example": "USD" } }, "additionalProperties": false }, "status": { "type": "string", "enum": [ "under_review", "lost", "awaiting_response", "refunded", "won", "needs_response", "appealable" ], "description": "The dispute status", "example": "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", "example": "fraud" }, "responseDueDate": { "type": "string", "format": "date-time", "description": "The response due date in ISO8601 format", "example": "2021-01-01T00:00:00Z" } } }, "transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "The transaction id", "example": "123e4567-e89b-12d3-a456-426614174000" }, "creationDate": { "type": "string", "format": "date-time", "description": "The creation date of the webhook in ISO8601 format", "example": "2021-01-01T00:00:00Z" }, "source": { "type": [ "string", "null" ], "description": "The source of the transaction", "example": "stripe" }, "orderId": { "type": "string", "description": "As recieved from the payment processor, if available", "example": "4141404271159" }, "customerEmail": { "type": "string", "format": "email", "description": "The customer email, as recieved from the payment processor, if available", "example": "john@example.com" } } }, "vendorAccountId": { "type": "string", "description": "The vendor account id", "example": "55617" }, "accountId": { "type": "string", "description": "The account id", "example": "67598401g210baf852j1f6dd" } } }, "creationDate": { "type": "string", "format": "date-time", "description": "The creation date of the webhook in ISO8601 format", "example": "2021-01-01T00:00:00Z" }, "webhookId": { "type": "string", "format": "uuid", "default": "e11e21e3-41ec-4c9d-9381-442cb6030ce1", "description": "The webhook id", "example": "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. Generate it in the Developer Hub under Settings." } } } }