{ "openapi": "3.1.0", "info": { "title": "Chargeflow API", "version": "2025-04-01", "description": "The Chargeflow API. Merchant endpoints manage disputes, alerts, evidence, and webhooks for your own store; platform (Connect) endpoints manage connected merchant accounts. Each operation carries `x-audience` (merchants, platforms, or both)." }, "servers": [ { "url": "https://api.chargeflow.io", "description": "Production server" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Health Check", "description": "API health check endpoints" }, { "name": "Alerts", "description": "Alerts related endpoints" }, { "name": "Disputes", "description": "Disputes management endpoints" }, { "name": "Customer Communication", "description": "Customer communication endpoints" }, { "name": "Webhooks Management", "description": "Webhook configuration and management" }, { "name": "Webhooks Events", "description": "Webhook event notifications" }, { "name": "Data Subject" }, { "name": "Accounts", "description": "Accounts related endpoints" }, { "name": "Merchants Disputes", "description": "Merchants disputes management endpoints" }, { "name": "Evidence", "description": "Evidence management endpoints" } ], "paths": { "/public/2025-04-01/alerts/{alertId}/outcome": { "post": { "operationId": "updateAlertOutcome", "tags": ["Alerts"], "summary": "Update Alert Outcome", "description": "Reports the final outcome of a pre-chargeback alert back to Chargeflow, which closes the alert with the issuer. Required only in the merchant-managed handling model.", "parameters": [ { "in": "path", "name": "alertId", "schema": { "type": "string", "description": "The unique Chargeflow object identifier of the alert.", "examples": ["alert_123456789"] }, "required": true, "example": "alert_123456789" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "description": "The final outcome of the alert, reported back to Chargeflow. Outcome can be one of the following: refunded, previously_refunded, duplicate, decline, error, transaction_not_found.", "enum": [ "refunded", "previously_refunded", "duplicate", "decline", "error", "transaction_not_found" ], "examples": ["refunded"] } }, "required": ["outcome"] } } } }, "responses": { "202": { "description": "Alert outcome updated successfully" }, "400": { "description": "Bad Request - Alert ID and valid outcome are required", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "invalid_request_error", "description": "The type of error", "examples": ["invalid_request_error"] }, "code": { "type": "string", "enum": ["missing_alert_id", "missing_outcome"], "description": "Specific error code", "examples": ["missing_alert_id"] }, "message": { "type": "string", "enum": ["Alert ID is required", "Outcome is required"], "description": "Human-readable error message", "examples": ["Alert ID is required"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "Required parameters are missing or invalid", "examples": [ { "error": { "type": "invalid_request_error", "code": "missing_alert_id", "message": "Alert ID is required", "request_id": "req_abc123def456" } } ], "x-readme-ref-name": "AlertOutcomeBadRequestError" } } } }, "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", "examples": ["authentication_error"] }, "code": { "type": "string", "enum": ["unauthorized", "invalid_credentials", "missing_credentials"], "description": "Specific error code", "examples": ["unauthorized"] }, "message": { "type": "string", "enum": [ "Unauthorized access", "Authentication credentials are missing or invalid" ], "description": "Human-readable error message", "examples": ["Unauthorized access"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "Unauthorized - Authentication is required or has failed", "examples": [ { "error": { "type": "authentication_error", "code": "unauthorized", "message": "Unauthorized access", "request_id": "req_abc123def456" } } ], "x-readme-ref-name": "UnauthorizedError" } } } }, "403": { "description": "Forbidden - Unauthorized access to alert data", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "permission_error", "description": "The type of error", "examples": ["permission_error"] }, "code": { "type": "string", "enum": ["unauthorized_alert_access"], "description": "Specific error code", "examples": ["unauthorized_alert_access"] }, "message": { "type": "string", "enum": ["Unauthorized access to alert data"], "description": "Human-readable error message", "examples": ["Unauthorized access to alert data"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "The authenticated user does not have permission to update this alert", "examples": [ { "error": { "type": "permission_error", "code": "unauthorized_alert_access", "message": "Unauthorized access to alert data", "request_id": "req_abc123def456" } } ], "x-readme-ref-name": "UpdateAlertOutcomeUnauthorizedError" } } } }, "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", "examples": ["api_error"] }, "code": { "type": "string", "enum": [ "internal_error", "server_error", "account_creation_failed", "account_retrieval_failed", "account_update_failed" ], "description": "Specific error code", "examples": ["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", "examples": ["Internal server error"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["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.", "examples": [ { "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error", "request_id": "req_abc123def456" } } ], "x-readme-ref-name": "InternalServerError" } } } } }, "x-audience": ["merchants"] } }, "/public/2025-04-01/alerts/{alertId}": { "get": { "operationId": "getAlertByID", "tags": ["Alerts"], "summary": "Get Alert By ID", "description": "Retrieves a single pre-chargeback alert by ID, including its status, type, linked transaction, and reason. Available to Chargeflow Alerts customers.", "parameters": [ { "in": "path", "name": "alertId", "description": "The unique Chargeflow object identifier of the alert.", "schema": { "type": "string", "description": "The unique Chargeflow object identifier of the alert.", "examples": ["alert_123456789"] }, "required": true, "example": "alert_123456789" } ], "responses": { "200": { "description": "Alert retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique Chargeflow object identifier of the alert.", "examples": ["alert_123456789"] }, "account_id": { "type": "string", "description": "The unique Chargeflow account identifier to which the alert belongs.", "examples": ["account_987654321"] }, "ext_account_id": { "type": ["string", "null"], "description": "Platforms only - The unique account identifier appears on the platform. Returns null if the platform did not update this attribute when creating a merchant entity.", "examples": ["platform_acc_12345"] }, "transaction": { "anyOf": [ { "type": "string", "description": "The unique Chargeflow identifier of the transaction to which the alert is linked.", "examples": ["txn_abcdef123456"] }, { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow transaction ID associated with the dispute.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The transaction ID from the source.", "examples": ["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.", "examples": ["tx_1234567890"] }, "source_id": { "type": ["string", "null"], "maxLength": 128, "description": "The unique transaction identifier appears on the source from which the transaction originated.", "examples": ["tx_1234567890"] }, "account_id": { "type": ["string", "null"], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the transaction belongs.", "examples": ["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.", "examples": ["acc_123456"] }, "order_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "examples": ["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.", "examples": ["ord_1234567890"] }, "subscription_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow subscription ID associated with the dispute.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The subscription ID from the source.", "examples": ["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.", "examples": ["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.", "examples": ["2024-02-10T12:00:00Z"] }, "type": { "type": ["string", "null"], "enum": ["paid", "partially_paid", "refunded", "partially_refunded"], "description": "The type of the transaction", "examples": ["paid"] }, "amount": { "type": ["number", "null"], "minimum": 0, "description": "Transaction total amount after all deductions.", "examples": [100] }, "currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["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.", "examples": ["John Doe"] }, "type": { "type": ["string", "null"], "enum": ["card", "wallet"], "description": "The type of the payment method", "examples": ["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`", "examples": ["1234"] }, "expiry_month": { "type": ["integer", "null"], "minimum": 1, "maximum": 12, "description": "The month when the card used for the transaction is expired. `card`", "examples": [1] }, "expiry_year": { "type": ["integer", "null"], "minimum": 2019, "maximum": 2100, "description": "The year when the card used for the transaction is expired. `card`", "examples": [2025] }, "brand": { "type": ["string", "null"], "enum": [ "visa", "mastercard", "discover", "amex", "jcb", "unionpay", "diners", "other" ], "description": "The card brand used for the transaction. `card`", "examples": ["visa"] }, "country": { "type": ["string", "null"], "pattern": "^[A-Z]{2}$", "description": "The card issuance country - two-letter country code (ISO 3166-1 alpha-2). `card`", "examples": ["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`", "examples": ["paypal"] }, "checks": { "type": "object", "properties": { "three_d_secure_result": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The 3D secure authentication outcome. `card`", "examples": ["passed"] }, "avs_results": { "type": ["string", "null"], "enum": ["N", "A", "Y", "Z"], "description": "The address verification system outcome. `card`", "examples": ["N"] }, "address_line1_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The address line1 check result. `card`", "examples": ["passed"] }, "address_zip_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The address zip or postal code check result. `card`", "examples": ["passed"] }, "cvc_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The card verification code result. `card`", "examples": ["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`", "examples": ["john.doe@example.com"] }, "wallet_id": { "type": ["string", "null"], "maxLength": 128, "description": "The wallet unique identifier which used for the transaction. `wallet`", "examples": ["1234567890"] } }, "description": "The payment method used for the transaction.", "examples": [ { "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.", "examples": ["John Doe"] }, "line1": { "type": ["string", "null"], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "examples": ["123 Main St"] }, "line2": { "type": ["string", "null"], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "examples": ["Apt 1"] }, "city": { "type": ["string", "null"], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "examples": ["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", "examples": ["US"] }, "state": { "type": ["string", "null"], "description": "State, county, province, or region associated with the address lines.", "examples": ["CA"] }, "zip_code": { "type": ["string", "null"], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "examples": ["12345"] }, "phone": { "type": ["string", "null"], "description": "The phone number of the person associated with the billing address.", "examples": ["1(123)4567890"] } }, "description": "The billing address associated with the payment method at the time of the transaction.", "examples": [ { "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." } ], "description": "The unique Chargeflow identifier of the transaction to which the alert is linked." }, "created_at": { "type": "string", "format": "date-time", "description": "The time at which the alert was created in ISO 8601 format.", "examples": ["2025-07-31T12:34:56Z"] }, "network_transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the transaction to as appear on the network.", "examples": ["net_txn_78910"] }, "created_at": { "type": "string", "format": "date-time", "description": "The time at which the transaction was created at the network in ISO 8601 format.", "examples": ["2025-07-31T12:30:00Z"] }, "amount": { "type": "number", "minimum": 0, "description": "The total amount of the transaction.", "examples": [12500] }, "currency": { "type": "string", "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["USD"] }, "card_brand": { "type": "string", "description": "The card brand used for the transaction", "examples": ["Visa"] }, "bin": { "type": "number", "description": "The first 6 to 8 digits of the card number, identifying the issuing bank and card type.", "examples": [411111] }, "last4": { "type": "string", "description": "The last four digits of the card number, used for reference and display.", "examples": ["1111"] }, "auth_code": { "type": "string", "description": "The unique identifier issued by the issuer bank to confirm approval of a payment transaction.", "examples": ["AUTH1234"] }, "arn": { "type": "string", "description": "The acquirer reference number, a unique identifier assigned to the transaction by the acquiring bank for tracking and settlement purposes.", "examples": ["ARN56789"] } }, "additionalProperties": false, "description": "The unique Chargeflow identifier of the transaction to which the alert is linked." }, "status_date": { "type": "string", "format": "date-time", "description": "The time at which the alert status was updated in ISO 8601 format.", "examples": ["2025-07-31T13:00:00Z"] }, "status": { "type": "string", "description": "The status of the alert. Status can be one of the following: alerted, pending, refund_initiated, prevented.", "examples": ["refund_initiated"] }, "statement_descriptor": { "type": "string", "description": "The descriptor of the merchant to which the alert belongs.", "examples": ["My Merchant Store"] }, "amount": { "type": "number", "minimum": 0, "description": "Alert total amount.", "examples": [12500] }, "currency": { "type": "string", "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["USD"] }, "outcome": { "type": ["string", "null"], "description": "The outcome of the alert, or null until the alert reaches a final outcome. Outcome can be one of the following: refunded, previously_refunded, duplicate, decline, error, transaction_not_found.", "examples": ["refunded"], "enum": [ "refunded", "previously_refunded", "duplicate", "decline", "error", "transaction_not_found", null ] }, "type": { "type": "string", "description": "The type of the alert. Type can be one of the following: fraud_warning, ethoca, cdrn, rdr, other.", "examples": ["fraud_warning"] }, "reason": { "type": "string", "description": "The reason for the alert. Reason can be one of the following: fraud, processing, authorization, service.", "examples": ["fraud"] } }, "additionalProperties": false, "description": "An Alert is a notification of a potential dispute, enabling merchants to proactively address it before it escalates to a chargeback. Merchants can choose to prevent the chargeback by refunding the transaction or await escalation, which may result in a chargeback." } } } }, "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", "examples": ["invalid_request_error"] }, "code": { "type": "string", "enum": ["missing_alert_id"], "description": "Specific error code", "examples": ["missing_alert_id"] }, "message": { "type": "string", "enum": ["Alert ID is required"], "description": "Human-readable error message", "examples": ["Alert ID is required"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "Alert ID parameter is missing or invalid", "examples": [ { "error": { "type": "invalid_request_error", "code": "missing_alert_id", "message": "Alert ID is required", "request_id": "req_abc123def456" } } ], "x-readme-ref-name": "MissingAlertIdError" } } } }, "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", "examples": ["authentication_error"] }, "code": { "type": "string", "enum": ["unauthorized", "invalid_credentials", "missing_credentials"], "description": "Specific error code", "examples": ["unauthorized"] }, "message": { "type": "string", "enum": [ "Unauthorized access", "Authentication credentials are missing or invalid" ], "description": "Human-readable error message", "examples": ["Unauthorized access"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "Unauthorized - Authentication is required or has failed", "examples": [ { "error": { "type": "authentication_error", "code": "unauthorized", "message": "Unauthorized access", "request_id": "req_abc123def456" } } ], "x-readme-ref-name": "UnauthorizedError" } } } }, "403": { "description": "Forbidden - Unauthorized access to alert data", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "permission_error", "description": "The type of error", "examples": ["permission_error"] }, "code": { "type": "string", "enum": ["unauthorized_alert_access", "unauthorized_resource_access"], "description": "Specific error code", "examples": ["unauthorized_alert_access"] }, "message": { "type": "string", "enum": [ "Unauthorized access to alert data", "Unauthorized access to resource" ], "description": "Human-readable error message", "examples": ["Unauthorized access to alert data"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "The authenticated user does not have permission to access this alert", "examples": [ { "error": { "type": "permission_error", "code": "unauthorized_alert_access", "message": "Unauthorized access to alert data", "request_id": "req_abc123def456" } } ], "x-readme-ref-name": "GetAlertByIdUnauthorizedError" } } } }, "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", "examples": ["invalid_request_error"] }, "code": { "type": "string", "enum": ["alert_not_found"], "description": "Specific error code", "examples": ["alert_not_found"] }, "message": { "type": "string", "enum": ["Alert not found"], "description": "Human-readable error message", "examples": ["Alert not found"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "The requested alert does not exist", "examples": [ { "error": { "type": "invalid_request_error", "code": "alert_not_found", "message": "Alert not found", "request_id": "req_abc123def456" } } ], "x-readme-ref-name": "AlertNotFoundError" } } } }, "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", "examples": ["api_error"] }, "code": { "type": "string", "enum": [ "internal_error", "server_error", "account_creation_failed", "account_retrieval_failed", "account_update_failed" ], "description": "Specific error code", "examples": ["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", "examples": ["Internal server error"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["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.", "examples": [ { "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error", "request_id": "req_abc123def456" } } ], "x-readme-ref-name": "InternalServerError" } } } } }, "x-audience": ["merchants"] } }, "/public/2025-04-01/alerts": { "get": { "operationId": "getAlerts", "tags": ["Alerts"], "summary": "Get Alerts", "description": "Retrieves a paginated list of pre-chargeback alerts on your account, with filters by date, type, status, and reason. Available to Chargeflow Alerts customers.", "parameters": [ { "in": "query", "name": "offset", "schema": { "type": "string", "description": "The number of alerts to skip before the returned results. This is a record offset, not a page index: increment it by `limit` to fetch the next page.", "examples": ["0"] }, "example": "0" }, { "in": "query", "name": "limit", "schema": { "type": "string", "description": "The number of alerts to return per request.", "examples": ["10"] }, "example": "10" }, { "in": "query", "name": "created_at_max", "schema": { "type": "string", "description": "Returns only alerts created at or before this time, in ISO 8601 format.", "examples": ["2025-07-31T23:59:59Z"] } }, { "in": "query", "name": "created_at_min", "schema": { "type": "string", "description": "Returns only alerts created at or after this time, in ISO 8601 format.", "examples": ["2025-07-01T00:00:00Z"] } }, { "in": "query", "name": "ids", "schema": { "type": "string", "description": "Returns only the alerts with these Chargeflow alert identifiers.", "examples": ["alert_123456789"] } }, { "in": "query", "name": "type", "schema": { "type": "string", "description": "Returns only alerts of this type. Type can be one of the following: fraud_warning, ethoca, cdrn, rdr, other.", "examples": ["fraud_warning"] } }, { "in": "query", "name": "status", "schema": { "type": "string", "description": "Returns only alerts in this status. Status can be one of the following: alerted, pending, refund_initiated, prevented.", "examples": ["refund_initiated"] } }, { "in": "query", "name": "reason", "schema": { "type": "string", "description": "Returns only alerts with this reason. Reason can be one of the following: fraud, processing, authorization, service.", "examples": ["fraud"] } }, { "in": "query", "name": "sort", "schema": { "type": "string", "description": "The field the returned alerts are sorted by.", "examples": ["created_at"] } } ], "responses": { "200": { "description": "List of alerts retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "alerts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique Chargeflow object identifier of the alert.", "examples": ["alert_123456789"] }, "account_id": { "type": "string", "description": "The unique Chargeflow account identifier to which the alert belongs.", "examples": ["account_987654321"] }, "ext_account_id": { "type": ["string", "null"], "description": "Platforms only - The unique account identifier appears on the platform. Returns null if the platform did not update this attribute when creating a merchant entity.", "examples": ["platform_acc_12345"] }, "transaction": { "anyOf": [ { "type": "string", "description": "The unique Chargeflow identifier of the transaction to which the alert is linked.", "examples": ["txn_abcdef123456"] }, { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow transaction ID associated with the dispute.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The transaction ID from the source.", "examples": ["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.", "examples": ["tx_1234567890"] }, "source_id": { "type": ["string", "null"], "maxLength": 128, "description": "The unique transaction identifier appears on the source from which the transaction originated.", "examples": ["tx_1234567890"] }, "account_id": { "type": ["string", "null"], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the transaction belongs.", "examples": ["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.", "examples": ["acc_123456"] }, "order_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "examples": ["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.", "examples": ["ord_1234567890"] }, "subscription_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow subscription ID associated with the dispute.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The subscription ID from the source.", "examples": ["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.", "examples": ["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.", "examples": ["2024-02-10T12:00:00Z"] }, "type": { "type": ["string", "null"], "enum": [ "paid", "partially_paid", "refunded", "partially_refunded" ], "description": "The type of the transaction", "examples": ["paid"] }, "amount": { "type": ["number", "null"], "minimum": 0, "description": "Transaction total amount after all deductions.", "examples": [100] }, "currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["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.", "examples": ["John Doe"] }, "type": { "type": ["string", "null"], "enum": ["card", "wallet"], "description": "The type of the payment method", "examples": ["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`", "examples": ["1234"] }, "expiry_month": { "type": ["integer", "null"], "minimum": 1, "maximum": 12, "description": "The month when the card used for the transaction is expired. `card`", "examples": [1] }, "expiry_year": { "type": ["integer", "null"], "minimum": 2019, "maximum": 2100, "description": "The year when the card used for the transaction is expired. `card`", "examples": [2025] }, "brand": { "type": ["string", "null"], "enum": [ "visa", "mastercard", "discover", "amex", "jcb", "unionpay", "diners", "other" ], "description": "The card brand used for the transaction. `card`", "examples": ["visa"] }, "country": { "type": ["string", "null"], "pattern": "^[A-Z]{2}$", "description": "The card issuance country - two-letter country code (ISO 3166-1 alpha-2). `card`", "examples": ["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`", "examples": ["paypal"] }, "checks": { "type": "object", "properties": { "three_d_secure_result": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The 3D secure authentication outcome. `card`", "examples": ["passed"] }, "avs_results": { "type": ["string", "null"], "enum": ["N", "A", "Y", "Z"], "description": "The address verification system outcome. `card`", "examples": ["N"] }, "address_line1_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The address line1 check result. `card`", "examples": ["passed"] }, "address_zip_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The address zip or postal code check result. `card`", "examples": ["passed"] }, "cvc_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The card verification code result. `card`", "examples": ["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`", "examples": ["john.doe@example.com"] }, "wallet_id": { "type": ["string", "null"], "maxLength": 128, "description": "The wallet unique identifier which used for the transaction. `wallet`", "examples": ["1234567890"] } }, "description": "The payment method used for the transaction.", "examples": [ { "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.", "examples": ["John Doe"] }, "line1": { "type": ["string", "null"], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "examples": ["123 Main St"] }, "line2": { "type": ["string", "null"], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "examples": ["Apt 1"] }, "city": { "type": ["string", "null"], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "examples": ["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", "examples": ["US"] }, "state": { "type": ["string", "null"], "description": "State, county, province, or region associated with the address lines.", "examples": ["CA"] }, "zip_code": { "type": ["string", "null"], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "examples": ["12345"] }, "phone": { "type": ["string", "null"], "description": "The phone number of the person associated with the billing address.", "examples": ["1(123)4567890"] } }, "description": "The billing address associated with the payment method at the time of the transaction.", "examples": [ { "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." } ], "description": "The unique Chargeflow identifier of the transaction to which the alert is linked." }, "created_at": { "type": "string", "format": "date-time", "description": "The time at which the alert was created in ISO 8601 format.", "examples": ["2025-07-31T12:34:56Z"] }, "network_transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the transaction to as appear on the network.", "examples": ["net_txn_78910"] }, "created_at": { "type": "string", "format": "date-time", "description": "The time at which the transaction was created at the network in ISO 8601 format.", "examples": ["2025-07-31T12:30:00Z"] }, "amount": { "type": "number", "minimum": 0, "description": "The total amount of the transaction.", "examples": [12500] }, "currency": { "type": "string", "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["USD"] }, "card_brand": { "type": "string", "description": "The card brand used for the transaction", "examples": ["Visa"] }, "bin": { "type": "number", "description": "The first 6 to 8 digits of the card number, identifying the issuing bank and card type.", "examples": [411111] }, "last4": { "type": "string", "description": "The last four digits of the card number, used for reference and display.", "examples": ["1111"] }, "auth_code": { "type": "string", "description": "The unique identifier issued by the issuer bank to confirm approval of a payment transaction.", "examples": ["AUTH1234"] }, "arn": { "type": "string", "description": "The acquirer reference number, a unique identifier assigned to the transaction by the acquiring bank for tracking and settlement purposes.", "examples": ["ARN56789"] } }, "additionalProperties": false, "description": "The unique Chargeflow identifier of the transaction to which the alert is linked." }, "status_date": { "type": "string", "format": "date-time", "description": "The time at which the alert status was updated in ISO 8601 format.", "examples": ["2025-07-31T13:00:00Z"] }, "status": { "type": "string", "description": "The status of the alert. Status can be one of the following: alerted, pending, refund_initiated, prevented.", "examples": ["refund_initiated"] }, "statement_descriptor": { "type": "string", "description": "The descriptor of the merchant to which the alert belongs.", "examples": ["My Merchant Store"] }, "amount": { "type": "number", "minimum": 0, "description": "Alert total amount.", "examples": [12500] }, "currency": { "type": "string", "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["USD"] }, "outcome": { "type": ["string", "null"], "description": "The outcome of the alert, or null until the alert reaches a final outcome. Outcome can be one of the following: refunded, previously_refunded, duplicate, decline, error, transaction_not_found.", "examples": ["refunded"], "enum": [ "refunded", "previously_refunded", "duplicate", "decline", "error", "transaction_not_found", null ] }, "type": { "type": "string", "description": "The type of the alert. Type can be one of the following: fraud_warning, ethoca, cdrn, rdr, other.", "examples": ["fraud_warning"] }, "reason": { "type": "string", "description": "The reason for the alert. Reason can be one of the following: fraud, processing, authorization, service.", "examples": ["fraud"] } }, "additionalProperties": false, "description": "An Alert is a notification of a potential dispute, enabling merchants to proactively address it before it escalates to a chargeback. Merchants can choose to prevent the chargeback by refunding the transaction or await escalation, which may result in a chargeback." }, "description": "Array of alert objects returned in the response" }, "pagination": { "type": "object", "properties": { "totalCount": { "type": "integer", "minimum": 0, "description": "Total number of alerts matching the query", "examples": [100] }, "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "The number of alerts skipped before the returned results. This is a record offset, not a page number.", "examples": [0] }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "The number of alerts returned per request", "examples": [25] } }, "description": "Pagination information for the current response", "examples": [ { "totalCount": 100, "offset": 0, "limit": 25 } ] } } } } } }, "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", "examples": ["authentication_error"] }, "code": { "type": "string", "enum": ["unauthorized", "invalid_credentials", "missing_credentials"], "description": "Specific error code", "examples": ["unauthorized"] }, "message": { "type": "string", "enum": [ "Unauthorized access", "Authentication credentials are missing or invalid" ], "description": "Human-readable error message", "examples": ["Unauthorized access"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "Unauthorized - Authentication is required or has failed", "examples": [ { "error": { "type": "authentication_error", "code": "unauthorized", "message": "Unauthorized access", "request_id": "req_abc123def456" } } ], "x-readme-ref-name": "UnauthorizedError" } } } }, "403": { "description": "Forbidden - Unauthorized access to alert data", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "permission_error", "description": "The type of error", "examples": ["permission_error"] }, "code": { "type": "string", "enum": ["unauthorized_alert_access"], "description": "Specific error code", "examples": ["unauthorized_alert_access"] }, "message": { "type": "string", "enum": ["Unauthorized access to alert data"], "description": "Human-readable error message", "examples": ["Unauthorized access to alert data"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "The authenticated user does not have permission to access these alerts", "examples": [ { "error": { "type": "permission_error", "code": "unauthorized_alert_access", "message": "Unauthorized access to alert data", "request_id": "req_abc123def456" } } ], "x-readme-ref-name": "GetAlertsUnauthorizedError" } } } }, "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", "examples": ["api_error"] }, "code": { "type": "string", "enum": [ "internal_error", "server_error", "account_creation_failed", "account_retrieval_failed", "account_update_failed" ], "description": "Specific error code", "examples": ["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", "examples": ["Internal server error"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["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.", "examples": [ { "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error", "request_id": "req_abc123def456" } } ], "x-readme-ref-name": "InternalServerError" } } } } }, "x-audience": ["merchants"] } }, "/public/2025-04-01/customer-communication": { "post": { "operationId": "createCustomerCommunication", "tags": ["Customer Communication"], "summary": "Create Customer Communication", "description": "Creates a customer communication ticket in Chargeflow that can be used to enrich a dispute.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "source_id": { "type": "string", "maxLength": 128, "description": "The unique customer communication ticket identifier appears on the source from which the ticket originated.", "examples": ["ticket_87659876b"] }, "account_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the customer communication ticket belongs. (required for platforms only)", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "disputes": { "type": "array", "items": { "type": "string", "maxLength": 128 }, "minItems": 1, "description": "The unique Chargeflow dispute identifier to which the customer communication ticket belongs; the ticket can be linked to one or more disputes.", "examples": [["6684a99a2664656565656565", "66e6ea9ecd94925a558060d9"]] }, "messages": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": ["email", "chat", "transcript", "form", "sms"], "default": "email", "description": "The type of the message; defaults to email.", "examples": ["email"] }, "sender": { "anyOf": [ { "type": "string", "format": "email", "examples": ["customer.support@example.com"] }, { "type": "string", "enum": ["buyer", "merchant"], "examples": ["buyer"] } ], "description": "The email address or the role of the sender; possible values are either a valid email address or buyer, merchant.", "examples": ["buyer"] }, "date": { "type": "string", "format": "date-time", "description": "The time at which the message was created at the source in ISO 8601 format.", "examples": ["2025-09-10T14:25:36Z"] }, "subject": { "type": "string", "maxLength": 100, "description": "The subject of the message; limited to 100 characters.", "examples": ["Where is my order?"] }, "body_plain_text": { "type": "string", "description": "The message body in a plain text.", "examples": [ "Hi, I placed my order 5 days ago and it still hasn't arrived. Can you please provide an update?" ] } }, "required": ["sender", "date", "body_plain_text"] }, "description": "A list of messages associated with the customer communication ticket." } }, "required": ["source_id", "disputes", "messages"], "description": "Creates a new customer communication ticket in Chargeflow." } } } }, "responses": { "200": { "description": "Customer communication created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Indicates whether the customer communication ticket was created successfully.", "examples": [true] } } } } } }, "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", "examples": ["invalid_request_error"] }, "code": { "type": "string", "enum": [ "invalid_request_body", "missing_account_id", "missing_disputes", "missing_messages", "dispute_not_found" ], "description": "Specific error code", "examples": ["invalid_request_body"] }, "message": { "type": "string", "enum": [ "Invalid request body", "Account ID is required", "At least one dispute is required for customer communication creation", "At least one message is required for customer communication creation", "Dispute not found" ], "description": "Human-readable error message", "examples": ["Invalid request body"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "The request contains invalid parameters or is missing required fields", "examples": [ { "error": { "type": "invalid_request_error", "code": "invalid_request_body", "message": "Invalid request body", "request_id": "req_abc123def456" } } ], "x-readme-ref-name": "CreateCustomerCommunicationBadRequestError" } } } }, "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", "examples": ["authentication_error"] }, "code": { "type": "string", "enum": ["unauthorized", "invalid_credentials", "missing_credentials"], "description": "Specific error code", "examples": ["unauthorized"] }, "message": { "type": "string", "enum": [ "Unauthorized access", "Authentication credentials are missing or invalid" ], "description": "Human-readable error message", "examples": ["Unauthorized access"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "Unauthorized - Authentication is required or has failed", "examples": [ { "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", "examples": ["permission_error"] }, "code": { "type": "string", "enum": [ "forbidden", "invalid_platform_access", "unauthorized_dispute_access" ], "description": "Specific error code", "examples": ["forbidden"] }, "message": { "type": "string", "enum": [ "Forbidden", "Invalid platform access - account_id does not belong to the platform", "Unauthorized access to create customer communication for this dispute" ], "description": "Human-readable error message", "examples": ["Forbidden"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "The authenticated user does not have permission to create a customer communication for this dispute", "examples": [ { "error": { "type": "permission_error", "code": "forbidden", "message": "Forbidden", "request_id": "req_abc123def456" } } ], "x-readme-ref-name": "CreateCustomerCommunicationForbiddenError" } } } }, "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", "examples": ["api_error"] }, "code": { "type": "string", "enum": [ "internal_error", "server_error", "account_creation_failed", "account_retrieval_failed", "account_update_failed" ], "description": "Specific error code", "examples": ["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", "examples": ["Internal server error"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["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.", "examples": [ { "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error", "request_id": "req_abc123def456" } } ], "x-readme-ref-name": "InternalServerError" } } } } }, "x-audience": ["merchants"] } }, "/public/2025-04-01/disputes/{disputeId}/evidence": { "post": { "operationId": "uploadEvidence", "tags": ["Disputes"], "summary": "Upload Evidence", "description": "The Submit Additional Evidence API allows you to upload supporting documents for a dispute, strengthening your chargeback response.", "parameters": [ { "in": "path", "name": "disputeId", "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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "required": true, "example": "66e6ea9ecd94925a9f8060d9" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "oneOf": [ { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "evidenceUploadCategory": { "type": "string", "enum": ["tracking_information", "customer_communication", "invoice"], "description": "The category of the evidence upload", "examples": ["invoice"] } }, "required": ["file", "evidenceUploadCategory"], "additionalProperties": false }, { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "evidenceUploadCategory": { "type": "string", "enum": ["additional_evidence", "additional_notes"], "description": "The category of the evidence upload", "examples": ["additional_evidence"] }, "content": { "type": "string", "description": "The content of the evidence. Only required with `additional_notes` and `additional_evidence` categories", "examples": ["Product picture"] } }, "required": ["file", "evidenceUploadCategory", "content"], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "Evidence uploaded successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string" }, "evidenceId": { "type": "string" } } } } } }, "400": { "description": "Bad Request - Dispute ID, chargeflowId, file size, file data, or invalid request body", "content": { "application/json": { "schema": { "type": "string", "enum": [ "Dispute ID is required", "User chargeflowId is required", "File size exceeds 5MB limit", "File data is required", "Invalid request body" ] } } } }, "403": { "description": "Forbidden - Unauthorized, invalid platform access, or unauthorized access to dispute data", "content": { "application/json": { "schema": { "type": "string", "enum": [ "Unauthorized access to dispute data", "Invalid platform access", "Unauthorized access" ] } } } }, "404": { "description": "Not Found - Dispute or platform/merchant shop not found", "content": { "application/json": { "schema": { "type": "string", "enum": ["Dispute not found", "Platform shop not found / Merchant shop not found"] } } } }, "500": { "description": "Internal Server Error - DB failure or any server failure", "content": { "application/json": { "schema": { "type": "string", "enum": [ "Internal server error", "Dispute has invalid data", "Failed to process request, please try again later" ] } } } } }, "x-audience": ["merchants"] } }, "/public/2025-04-01/disputes/{disputeId}": { "get": { "operationId": "getDisputeByID", "tags": ["Disputes"], "summary": "Get Dispute by ID", "description": "Retrieves a single dispute, optionally expanded with enriched data using the expand parameter.", "parameters": [ { "in": "path", "name": "disputeId", "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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "required": true, "example": "66e6ea9ecd94925a9f8060d9" }, { "in": "query", "name": "expand", "description": "### Available Expansions\n\nUse the `expand` parameter to include additional resource details in the response.\n\n**Available options:**\n\n| Parameter | Description |\n|-----------|-------------|\n| `transaction` | Full payment transaction details including amount, currency, payment method and more |\n| `order` | Complete order details including products, shipping, and fulfillment and more |\n| `subscription` | Complete subscription details including plan, frequency, cancellation reason and more |\n| `customer_communication` | Complete customer communication details including messages, sender, and more |\n\n", "schema": { "type": "array", "items": { "enum": ["transaction", "order", "subscription", "customer_communication"] }, "title": "Expandable Fields", "description": "### Available Expansions\n\nUse the `expand` parameter to include additional resource details in the response.\n\n**Available options:**\n\n| Parameter | Description |\n|-----------|-------------|\n| `transaction` | Full payment transaction details including amount, currency, payment method and more |\n| `order` | Complete order details including products, shipping, and fulfillment and more |\n| `subscription` | Complete subscription details including plan, frequency, cancellation reason and more |\n| `customer_communication` | Complete customer communication details including messages, sender, and more |\n\n", "examples": [["transaction", "order"]] } } ], "responses": { "200": { "description": "Dispute details retrieved 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.", "examples": ["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", "examples": ["stripe"] }, "source_id": { "type": ["string", "null"], "maxLength": 128, "description": "The unique dispute identifier appears on the source (processor) from which the dispute originated.", "examples": ["du_123456789"] }, "account_id": { "type": ["string", "null"], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the dispute belongs.", "examples": ["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.", "examples": ["acc_123456"] }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "The time at which the dispute was created in ISO 8601 format.", "examples": ["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.", "examples": ["fraud"] }, "due_by": { "type": ["string", "null"], "format": "date-time", "description": "The deadline to submit evidence to challenge the dispute in ISO 8601 format.", "examples": ["2024-02-20T12:00:00Z"] }, "amount": { "type": ["number", "null"], "minimum": 0, "description": "Disputed amount. Equal to or less than the disputed transaction amount.", "examples": [100] }, "currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["USD"] }, "status": { "type": ["string", "null"], "enum": ["needs_response", "under_review", "won", "lost"], "description": "The current status of the dispute.", "examples": ["needs_response"] }, "stage": { "type": ["string", "null"], "enum": ["Chargeback", "Inquiry", "Pre_arbitration", "Arbitration"], "description": "The stage of the dispute.", "examples": ["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.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The transaction ID from the source.", "examples": ["tx_1234567890"] } ], "description": "The transaction ID associated with the dispute. Can be a Chargeflow transaction identifier or a transaction identifier from the source.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The transaction ID from the source.", "examples": ["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.", "examples": ["tx_1234567890"] }, "source_id": { "type": ["string", "null"], "maxLength": 128, "description": "The unique transaction identifier appears on the source from which the transaction originated.", "examples": ["tx_1234567890"] }, "account_id": { "type": ["string", "null"], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the transaction belongs.", "examples": ["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.", "examples": ["acc_123456"] }, "order_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "examples": ["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.", "examples": ["ord_1234567890"] }, "subscription_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow subscription ID associated with the dispute.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The subscription ID from the source.", "examples": ["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.", "examples": ["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.", "examples": ["2024-02-10T12:00:00Z"] }, "type": { "type": ["string", "null"], "enum": ["paid", "partially_paid", "refunded", "partially_refunded"], "description": "The type of the transaction", "examples": ["paid"] }, "amount": { "type": ["number", "null"], "minimum": 0, "description": "Transaction total amount after all deductions.", "examples": [100] }, "currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["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.", "examples": ["John Doe"] }, "type": { "type": ["string", "null"], "enum": ["card", "wallet"], "description": "The type of the payment method", "examples": ["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`", "examples": ["1234"] }, "expiry_month": { "type": ["integer", "null"], "minimum": 1, "maximum": 12, "description": "The month when the card used for the transaction is expired. `card`", "examples": [1] }, "expiry_year": { "type": ["integer", "null"], "minimum": 2019, "maximum": 2100, "description": "The year when the card used for the transaction is expired. `card`", "examples": [2025] }, "brand": { "type": ["string", "null"], "enum": [ "visa", "mastercard", "discover", "amex", "jcb", "unionpay", "diners", "other" ], "description": "The card brand used for the transaction. `card`", "examples": ["visa"] }, "country": { "type": ["string", "null"], "pattern": "^[A-Z]{2}$", "description": "The card issuance country - two-letter country code (ISO 3166-1 alpha-2). `card`", "examples": ["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`", "examples": ["paypal"] }, "checks": { "type": "object", "properties": { "three_d_secure_result": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The 3D secure authentication outcome. `card`", "examples": ["passed"] }, "avs_results": { "type": ["string", "null"], "enum": ["N", "A", "Y", "Z"], "description": "The address verification system outcome. `card`", "examples": ["N"] }, "address_line1_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The address line1 check result. `card`", "examples": ["passed"] }, "address_zip_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The address zip or postal code check result. `card`", "examples": ["passed"] }, "cvc_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The card verification code result. `card`", "examples": ["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`", "examples": ["john.doe@example.com"] }, "wallet_id": { "type": ["string", "null"], "maxLength": 128, "description": "The wallet unique identifier which used for the transaction. `wallet`", "examples": ["1234567890"] } }, "description": "The payment method used for the transaction.", "examples": [ { "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.", "examples": ["John Doe"] }, "line1": { "type": ["string", "null"], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "examples": ["123 Main St"] }, "line2": { "type": ["string", "null"], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "examples": ["Apt 1"] }, "city": { "type": ["string", "null"], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "examples": ["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", "examples": ["US"] }, "state": { "type": ["string", "null"], "description": "State, county, province, or region associated with the address lines.", "examples": ["CA"] }, "zip_code": { "type": ["string", "null"], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "examples": ["12345"] }, "phone": { "type": ["string", "null"], "description": "The phone number of the person associated with the billing address.", "examples": ["1(123)4567890"] } }, "description": "The billing address associated with the payment method at the time of the transaction.", "examples": [ { "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.", "examples": ["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.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "source_id": { "type": ["string", "null"], "maxLength": 128, "description": "The unique subscription identifier appears on the source from which the subscription originated.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["2024-07-10T12:00:00Z"] }, "frequency": { "type": ["string", "null"], "enum": ["day", "week", "month", "year"], "description": "The frequency at which a subscription is billed.", "examples": ["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.", "examples": [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.", "examples": ["too_expensive"] }, "collection_method": { "type": ["string", "null"], "enum": [ "automatically", "automatically_with_reminder", "send_invoice" ], "description": "The billing method for the subscription.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["Pro Plan"] }, "pricing_model": { "type": ["string", "null"], "enum": ["fixed_price", "usage_base"], "description": "The pricing model associated with the subscription.", "examples": ["fixed_price"] }, "status": { "type": ["string", "null"], "enum": ["active", "inactive", "canceled"], "description": "The current status of the subscription.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "order": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "examples": ["ord_1234567890"] } ], "description": "The order ID associated with the dispute. Can be a Chargeflow order identifier or an order identifier from the source.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "examples": ["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.", "examples": ["ord_1234567890"] }, "source_id": { "type": ["string", "null"], "maxLength": 128, "description": "The unique order identifier appears on the source from which the order originated.", "examples": ["order_1234567890"] }, "account_id": { "type": ["string", "null"], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the order belongs.", "examples": ["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.", "examples": ["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.", "examples": ["2025-01-27T10:00:00Z"] }, "payment_status": { "type": ["string", "null"], "enum": ["paid", "partially_paid", "refunded", "partially_refunded"], "description": "The financial status of the order", "examples": ["paid"] }, "name": { "type": ["string", "null"], "maxLength": 128, "description": "The order name or number as appear in your source", "examples": ["#ORD-12345"] }, "type": { "type": ["string", "null"], "enum": ["standard", "pre_order"], "description": "The type of the order; defaults to standard.", "examples": ["standard"] }, "amount": { "type": ["number", "null"], "minimum": 0, "description": "Order total amount after all deductions.", "examples": [1000] }, "currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["USD"] }, "customer": { "type": ["object", "null"], "properties": { "name": { "type": ["string", "null"], "maxLength": 128, "description": "The full name of the customer who have made this order.", "examples": ["John Doe"] }, "email": { "type": ["string", "null"], "format": "email", "maxLength": 128, "description": "The email address belong to the customer. Valid format:", "examples": ["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.", "examples": ["2025-01-27T10:00:00Z"] }, "order_count": { "type": ["integer", "null"], "minimum": 0, "description": "The count of orders made by this customer with the merchant.", "examples": [1] }, "phone_number": { "type": ["string", "null"], "maxLength": 128, "description": "The phone number belong to the customer. Valid format:", "examples": ["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.", "examples": ["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.", "examples": [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.", "examples": ["Product Name"] }, "id": { "type": ["string", "null"], "maxLength": 128, "description": "The product unique identifier. Relevant to link it to tracking number and shipping method.", "examples": ["123456789"] }, "type": { "type": ["string", "null"], "enum": ["physical_good", "digital_good", "service", "other"], "description": "The type of the product", "examples": ["physical_good"] }, "quantity": { "type": ["integer", "null"], "minimum": 1, "description": "The number of items that were purchased.", "examples": [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.", "examples": ["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:", "examples": ["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.", "examples": [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.", "examples": ["John Doe"] }, "line1": { "type": ["string", "null"], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "examples": ["123 Main St"] }, "line2": { "type": ["string", "null"], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "examples": ["Apt 1"] }, "city": { "type": ["string", "null"], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "examples": ["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", "examples": ["US"] }, "state": { "type": ["string", "null"], "description": "State, county, province, or region associated with the address lines.", "examples": ["CA"] }, "zip_code": { "type": ["string", "null"], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "examples": ["12345"] }, "phone": { "type": ["string", "null"], "description": "The phone number of the person associated with the shipping address.", "examples": ["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.", "examples": ["123456789"] }, "shipped_at": { "type": ["string", "null"], "format": "date-time", "description": "The time at which the order was shipped in ISO 8601 format.", "examples": ["2025-01-27T10:00:00Z"] }, "shipping_line_title": { "type": ["string", "null"], "maxLength": 128, "description": "The shipping line title.", "examples": ["FedEx"] }, "shipping_method_price": { "type": ["number", "null"], "minimum": 0, "description": "The shipping method price as paid by the customer in the order's currency.", "examples": [100] }, "tracking_number": { "type": ["string", "null"], "maxLength": 128, "description": "The tracking number that was provided to track the fulfillment journey.", "examples": ["123456789"] }, "courier": { "type": ["string", "null"], "maxLength": 128, "description": "The shipping courier from which the tracking number originated and used to fulfill the order.", "examples": ["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", "examples": ["invalid_request_error"] }, "code": { "type": "string", "enum": ["missing_dispute_id", "missing_chargeflow_id"], "description": "Specific error code", "examples": ["missing_dispute_id"] }, "message": { "type": "string", "enum": ["Dispute ID is required", "User chargeflowId is required"], "description": "Human-readable error message", "examples": ["Dispute ID is required"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "Required parameters are missing from the request", "examples": [ { "error": { "type": "invalid_request_error", "code": "missing_dispute_id", "message": "Dispute ID is required", "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", "examples": ["authentication_error"] }, "code": { "type": "string", "enum": ["unauthorized", "invalid_credentials", "missing_credentials"], "description": "Specific error code", "examples": ["unauthorized"] }, "message": { "type": "string", "enum": [ "Unauthorized access", "Authentication credentials are missing or invalid" ], "description": "Human-readable error message", "examples": ["Unauthorized access"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "Unauthorized - Authentication is required or has failed", "examples": [ { "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", "examples": ["permission_error"] }, "code": { "type": "string", "enum": [ "unauthorized_dispute_access", "invalid_platform_access", "forbidden" ], "description": "Specific error code", "examples": ["unauthorized_dispute_access"] }, "message": { "type": "string", "enum": [ "Unauthorized access to dispute data", "Invalid platform access", "Unauthorized access" ], "description": "Human-readable error message", "examples": ["Unauthorized access to dispute data"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "User does not have permission to access this dispute", "examples": [ { "error": { "type": "permission_error", "code": "unauthorized_dispute_access", "message": "Unauthorized access to dispute data", "request_id": "req_abc123def456" } } ] } } } }, "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", "examples": ["invalid_request_error"] }, "code": { "type": "string", "enum": ["dispute_not_found", "shop_not_found"], "description": "Specific error code", "examples": ["dispute_not_found"] }, "message": { "type": "string", "enum": [ "Dispute not found", "Platform shop not found / Merchant shop not found" ], "description": "Human-readable error message", "examples": ["Dispute not found"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "The requested dispute or associated shop does not exist", "examples": [ { "error": { "type": "invalid_request_error", "code": "dispute_not_found", "message": "Dispute 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", "examples": ["api_error"] }, "code": { "type": "string", "enum": [ "internal_error", "server_error", "account_creation_failed", "account_retrieval_failed", "account_update_failed" ], "description": "Specific error code", "examples": ["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", "examples": ["Internal server error"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["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.", "examples": [ { "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error", "request_id": "req_abc123def456" } } ], "x-readme-ref-name": "InternalServerError" } } } } }, "x-audience": ["merchants"] }, "patch": { "operationId": "enrichDispute", "tags": ["Disputes"], "summary": "Enrich Dispute", "description": "Enriches a dispute with additional data (transaction, order, subscription, and more) to improve your chances of winning. Array properties are overwritten in full, so send every item you want to keep.", "parameters": [ { "in": "path", "name": "disputeId", "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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "required": true, "example": "66e6ea9ecd94925a9f8060d9" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction": { "type": "object", "properties": { "source_id": { "type": ["string", "null"], "maxLength": 128, "description": "The unique transaction identifier appears on the source from which the transaction originated.", "examples": ["tx_1234567890"] }, "order_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "examples": ["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.", "examples": ["ord_1234567890"] }, "subscription_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow subscription ID associated with the dispute.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The subscription ID from the source.", "examples": ["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.", "examples": ["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.", "examples": ["2024-02-10T12:00:00Z"] }, "type": { "type": ["string", "null"], "enum": ["paid", "partially_paid", "refunded", "partially_refunded"], "description": "The type of the transaction", "examples": ["paid"] }, "amount": { "type": ["number", "null"], "minimum": 0, "description": "Transaction total amount after all deductions.", "examples": [100] }, "currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["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.", "examples": ["John Doe"] }, "type": { "type": ["string", "null"], "enum": ["card", "wallet"], "description": "The type of the payment method", "examples": ["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`", "examples": ["1234"] }, "expiry_month": { "type": ["integer", "null"], "minimum": 1, "maximum": 12, "description": "The month when the card used for the transaction is expired. `card`", "examples": [1] }, "expiry_year": { "type": ["integer", "null"], "minimum": 2019, "maximum": 2100, "description": "The year when the card used for the transaction is expired. `card`", "examples": [2025] }, "brand": { "type": ["string", "null"], "enum": [ "visa", "mastercard", "discover", "amex", "jcb", "unionpay", "diners", "other" ], "description": "The card brand used for the transaction. `card`", "examples": ["visa"] }, "country": { "type": ["string", "null"], "pattern": "^[A-Z]{2}$", "description": "The card issuance country - two-letter country code (ISO 3166-1 alpha-2). `card`", "examples": ["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`", "examples": ["paypal"] }, "checks": { "type": "object", "properties": { "three_d_secure_result": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The 3D secure authentication outcome. `card`", "examples": ["passed"] }, "avs_results": { "type": ["string", "null"], "enum": ["N", "A", "Y", "Z"], "description": "The address verification system outcome. `card`", "examples": ["N"] }, "address_line1_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The address line1 check result. `card`", "examples": ["passed"] }, "address_zip_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The address zip or postal code check result. `card`", "examples": ["passed"] }, "cvc_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The card verification code result. `card`", "examples": ["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`", "examples": ["john.doe@example.com"] }, "wallet_id": { "type": ["string", "null"], "maxLength": 128, "description": "The wallet unique identifier which used for the transaction. `wallet`", "examples": ["1234567890"] } }, "description": "The payment method used for the transaction.", "examples": [ { "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.", "examples": ["John Doe"] }, "line1": { "type": ["string", "null"], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "examples": ["123 Main St"] }, "line2": { "type": ["string", "null"], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "examples": ["Apt 1"] }, "city": { "type": ["string", "null"], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "examples": ["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", "examples": ["US"] }, "state": { "type": ["string", "null"], "description": "State, county, province, or region associated with the address lines.", "examples": ["CA"] }, "zip_code": { "type": ["string", "null"], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "examples": ["12345"] }, "phone": { "type": ["string", "null"], "description": "The phone number of the person associated with the billing address.", "examples": ["1(123)4567890"] } }, "description": "The billing address associated with the payment method at the time of the transaction.", "examples": [ { "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." }, "order": { "type": "object", "properties": { "source_id": { "type": ["string", "null"], "maxLength": 128, "description": "The unique order identifier appears on the source from which the order originated.", "examples": ["order_1234567890"] }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "The time at which the order was created at the source in ISO 8601 format.", "examples": ["2025-01-27T10:00:00Z"] }, "payment_status": { "type": ["string", "null"], "enum": ["paid", "partially_paid", "refunded", "partially_refunded"], "description": "The financial status of the order", "examples": ["paid"] }, "name": { "type": ["string", "null"], "maxLength": 128, "description": "The order name or number as appear in your source", "examples": ["#ORD-12345"] }, "type": { "type": ["string", "null"], "enum": ["standard", "pre_order"], "description": "The type of the order; defaults to standard.", "examples": ["standard"] }, "amount": { "type": ["number", "null"], "minimum": 0, "description": "Order total amount after all deductions.", "examples": [1000] }, "currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["USD"] }, "customer": { "type": ["object", "null"], "properties": { "name": { "type": ["string", "null"], "maxLength": 128, "description": "The full name of the customer who have made this order.", "examples": ["John Doe"] }, "email": { "type": ["string", "null"], "format": "email", "maxLength": 128, "description": "The email address belong to the customer. Valid format:", "examples": ["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.", "examples": ["2025-01-27T10:00:00Z"] }, "order_count": { "type": ["integer", "null"], "minimum": 0, "description": "The count of orders made by this customer with the merchant.", "examples": [1] }, "phone_number": { "type": ["string", "null"], "maxLength": 128, "description": "The phone number belong to the customer. Valid format:", "examples": ["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.", "examples": ["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.", "examples": [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.", "examples": ["Product Name"] }, "id": { "type": ["string", "null"], "maxLength": 128, "description": "The product unique identifier. Relevant to link it to tracking number and shipping method.", "examples": ["123456789"] }, "type": { "type": ["string", "null"], "enum": ["physical_good", "digital_good", "service", "other"], "description": "The type of the product", "examples": ["physical_good"] }, "quantity": { "type": ["integer", "null"], "minimum": 1, "description": "The number of items that were purchased.", "examples": [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.", "examples": ["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:", "examples": ["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.", "examples": [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.", "examples": ["John Doe"] }, "line1": { "type": ["string", "null"], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "examples": ["123 Main St"] }, "line2": { "type": ["string", "null"], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "examples": ["Apt 1"] }, "city": { "type": ["string", "null"], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "examples": ["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", "examples": ["US"] }, "state": { "type": ["string", "null"], "description": "State, county, province, or region associated with the address lines.", "examples": ["CA"] }, "zip_code": { "type": ["string", "null"], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "examples": ["12345"] }, "phone": { "type": ["string", "null"], "description": "The phone number of the person associated with the shipping address.", "examples": ["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.", "examples": ["123456789"] }, "shipped_at": { "type": ["string", "null"], "format": "date-time", "description": "The time at which the order was shipped in ISO 8601 format.", "examples": ["2025-01-27T10:00:00Z"] }, "shipping_line_title": { "type": ["string", "null"], "maxLength": 128, "description": "The shipping line title.", "examples": ["FedEx"] }, "shipping_method_price": { "type": ["number", "null"], "minimum": 0, "description": "The shipping method price as paid by the customer in the order's currency.", "examples": [100] }, "tracking_number": { "type": ["string", "null"], "maxLength": 128, "description": "The tracking number that was provided to track the fulfillment journey.", "examples": ["123456789"] }, "courier": { "type": ["string", "null"], "maxLength": 128, "description": "The shipping courier from which the tracking number originated and used to fulfill the order.", "examples": ["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." } } }, "example": { "transaction": { "source_id": "tx_1234567890", "created_at": "2024-02-10T12:00:00Z", "type": "paid", "amount": 100, "currency": "USD", "payment_method": { "type": "card", "name": "John Doe", "last4": "1234", "expiry_month": 1, "expiry_year": 2025, "brand": "visa" } } } } } }, "responses": { "200": { "description": "Dispute updated 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.", "examples": ["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", null, "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", "examples": ["stripe"] }, "source_id": { "type": ["string", "null"], "maxLength": 128, "description": "The unique dispute identifier appears on the source (processor) from which the dispute originated.", "examples": ["du_123456789"] }, "account_id": { "type": ["string", "null"], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the dispute belongs.", "examples": ["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.", "examples": ["acc_123456"] }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "The time at which the dispute was created in ISO 8601 format.", "examples": ["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.", "examples": ["fraud"] }, "due_by": { "type": ["string", "null"], "format": "date-time", "description": "The deadline to submit evidence to challenge the dispute in ISO 8601 format.", "examples": ["2024-02-20T12:00:00Z"] }, "amount": { "type": ["number", "null"], "minimum": 0, "description": "Disputed amount. Equal to or less than the disputed transaction amount.", "examples": [100] }, "currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["USD"] }, "status": { "type": ["string", "null"], "enum": ["needs_response", "under_review", "won", "lost"], "description": "The current status of the dispute.", "examples": ["needs_response"] }, "stage": { "type": ["string", "null"], "enum": ["Chargeback", "Inquiry", "Pre_arbitration", "Arbitration"], "description": "The stage of the dispute.", "examples": ["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.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The transaction ID from the source.", "examples": ["tx_1234567890"] } ], "description": "The transaction ID associated with the dispute. Can be a Chargeflow transaction identifier or a transaction identifier from the source.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The transaction ID from the source.", "examples": ["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.", "examples": ["tx_1234567890"] }, "source_id": { "type": ["string", "null"], "maxLength": 128, "description": "The unique transaction identifier appears on the source from which the transaction originated.", "examples": ["tx_1234567890"] }, "account_id": { "type": ["string", "null"], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the transaction belongs.", "examples": ["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.", "examples": ["acc_123456"] }, "order_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "examples": ["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.", "examples": ["ord_1234567890"] }, "subscription_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow subscription ID associated with the dispute.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The subscription ID from the source.", "examples": ["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.", "examples": ["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.", "examples": ["2024-02-10T12:00:00Z"] }, "type": { "type": ["string", "null"], "enum": ["paid", "partially_paid", "refunded", "partially_refunded"], "description": "The type of the transaction", "examples": ["paid"] }, "amount": { "type": ["number", "null"], "minimum": 0, "description": "Transaction total amount after all deductions.", "examples": [100] }, "currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["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.", "examples": ["John Doe"] }, "type": { "type": ["string", "null"], "enum": ["card", "wallet"], "description": "The type of the payment method", "examples": ["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`", "examples": ["1234"] }, "expiry_month": { "type": ["integer", "null"], "minimum": 1, "maximum": 12, "description": "The month when the card used for the transaction is expired. `card`", "examples": [1] }, "expiry_year": { "type": ["integer", "null"], "minimum": 2019, "maximum": 2100, "description": "The year when the card used for the transaction is expired. `card`", "examples": [2025] }, "brand": { "type": ["string", "null"], "enum": [ "visa", "mastercard", "discover", "amex", "jcb", "unionpay", "diners", "other" ], "description": "The card brand used for the transaction. `card`", "examples": ["visa"] }, "country": { "type": ["string", "null"], "pattern": "^[A-Z]{2}$", "description": "The card issuance country - two-letter country code (ISO 3166-1 alpha-2). `card`", "examples": ["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`", "examples": ["paypal"] }, "checks": { "type": "object", "properties": { "three_d_secure_result": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The 3D secure authentication outcome. `card`", "examples": ["passed"] }, "avs_results": { "type": ["string", "null"], "enum": ["N", "A", "Y", "Z"], "description": "The address verification system outcome. `card`", "examples": ["N"] }, "address_line1_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The address line1 check result. `card`", "examples": ["passed"] }, "address_zip_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The address zip or postal code check result. `card`", "examples": ["passed"] }, "cvc_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The card verification code result. `card`", "examples": ["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`", "examples": ["john.doe@example.com"] }, "wallet_id": { "type": ["string", "null"], "maxLength": 128, "description": "The wallet unique identifier which used for the transaction. `wallet`", "examples": ["1234567890"] } }, "description": "The payment method used for the transaction.", "examples": [ { "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.", "examples": ["John Doe"] }, "line1": { "type": ["string", "null"], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "examples": ["123 Main St"] }, "line2": { "type": ["string", "null"], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "examples": ["Apt 1"] }, "city": { "type": ["string", "null"], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "examples": ["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", "examples": ["US"] }, "state": { "type": ["string", "null"], "description": "State, county, province, or region associated with the address lines.", "examples": ["CA"] }, "zip_code": { "type": ["string", "null"], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "examples": ["12345"] }, "phone": { "type": ["string", "null"], "description": "The phone number of the person associated with the billing address.", "examples": ["1(123)4567890"] } }, "description": "The billing address associated with the payment method at the time of the transaction.", "examples": [ { "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.", "examples": ["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.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "source_id": { "type": ["string", "null"], "maxLength": 128, "description": "The unique subscription identifier appears on the source from which the subscription originated.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["2024-07-10T12:00:00Z"] }, "frequency": { "type": ["string", "null"], "enum": ["day", "week", "month", "year"], "description": "The frequency at which a subscription is billed.", "examples": ["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.", "examples": [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.", "examples": ["too_expensive"] }, "collection_method": { "type": ["string", "null"], "enum": [ "automatically", "automatically_with_reminder", "send_invoice" ], "description": "The billing method for the subscription.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["Pro Plan"] }, "pricing_model": { "type": ["string", "null"], "enum": ["fixed_price", "usage_base"], "description": "The pricing model associated with the subscription.", "examples": ["fixed_price"] }, "status": { "type": ["string", "null"], "enum": ["active", "inactive", "canceled"], "description": "The current status of the subscription.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "order": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "examples": ["ord_1234567890"] } ], "description": "The order ID associated with the dispute. Can be a Chargeflow order identifier or an order identifier from the source.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "examples": ["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.", "examples": ["ord_1234567890"] }, "source_id": { "type": ["string", "null"], "maxLength": 128, "description": "The unique order identifier appears on the source from which the order originated.", "examples": ["order_1234567890"] }, "account_id": { "type": ["string", "null"], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the order belongs.", "examples": ["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.", "examples": ["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.", "examples": ["2025-01-27T10:00:00Z"] }, "payment_status": { "type": ["string", "null"], "enum": ["paid", "partially_paid", "refunded", "partially_refunded"], "description": "The financial status of the order", "examples": ["paid"] }, "name": { "type": ["string", "null"], "maxLength": 128, "description": "The order name or number as appear in your source", "examples": ["#ORD-12345"] }, "type": { "type": ["string", "null"], "enum": ["standard", "pre_order"], "description": "The type of the order; defaults to standard.", "examples": ["standard"] }, "amount": { "type": ["number", "null"], "minimum": 0, "description": "Order total amount after all deductions.", "examples": [1000] }, "currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["USD"] }, "customer": { "type": ["object", "null"], "properties": { "name": { "type": ["string", "null"], "maxLength": 128, "description": "The full name of the customer who have made this order.", "examples": ["John Doe"] }, "email": { "type": ["string", "null"], "format": "email", "maxLength": 128, "description": "The email address belong to the customer. Valid format:", "examples": ["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.", "examples": ["2025-01-27T10:00:00Z"] }, "order_count": { "type": ["integer", "null"], "minimum": 0, "description": "The count of orders made by this customer with the merchant.", "examples": [1] }, "phone_number": { "type": ["string", "null"], "maxLength": 128, "description": "The phone number belong to the customer. Valid format:", "examples": ["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.", "examples": ["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.", "examples": [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.", "examples": ["Product Name"] }, "id": { "type": ["string", "null"], "maxLength": 128, "description": "The product unique identifier. Relevant to link it to tracking number and shipping method.", "examples": ["123456789"] }, "type": { "type": ["string", "null"], "enum": ["physical_good", "digital_good", "service", "other"], "description": "The type of the product", "examples": ["physical_good"] }, "quantity": { "type": ["integer", "null"], "minimum": 1, "description": "The number of items that were purchased.", "examples": [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.", "examples": ["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:", "examples": ["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.", "examples": [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.", "examples": ["John Doe"] }, "line1": { "type": ["string", "null"], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "examples": ["123 Main St"] }, "line2": { "type": ["string", "null"], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "examples": ["Apt 1"] }, "city": { "type": ["string", "null"], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "examples": ["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", "examples": ["US"] }, "state": { "type": ["string", "null"], "description": "State, county, province, or region associated with the address lines.", "examples": ["CA"] }, "zip_code": { "type": ["string", "null"], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "examples": ["12345"] }, "phone": { "type": ["string", "null"], "description": "The phone number of the person associated with the shipping address.", "examples": ["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.", "examples": ["123456789"] }, "shipped_at": { "type": ["string", "null"], "format": "date-time", "description": "The time at which the order was shipped in ISO 8601 format.", "examples": ["2025-01-27T10:00:00Z"] }, "shipping_line_title": { "type": ["string", "null"], "maxLength": 128, "description": "The shipping line title.", "examples": ["FedEx"] }, "shipping_method_price": { "type": ["number", "null"], "minimum": 0, "description": "The shipping method price as paid by the customer in the order's currency.", "examples": [100] }, "tracking_number": { "type": ["string", "null"], "maxLength": 128, "description": "The tracking number that was provided to track the fulfillment journey.", "examples": ["123456789"] }, "courier": { "type": ["string", "null"], "maxLength": 128, "description": "The shipping courier from which the tracking number originated and used to fulfill the order.", "examples": ["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", "examples": ["invalid_request_error"] }, "code": { "type": "string", "enum": ["missing_dispute_id", "invalid_request_body"], "description": "Specific error code", "examples": ["missing_dispute_id"] }, "message": { "type": "string", "enum": ["Dispute ID is required", "Invalid request body"], "description": "Human-readable error message", "examples": ["Dispute ID is required"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "The request is missing required parameters or contains invalid data", "examples": [ { "error": { "type": "invalid_request_error", "code": "missing_dispute_id", "message": "Dispute ID is required", "request_id": "req_abc123def456" } } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDisputeForbiddenError" } } } }, "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", "examples": ["invalid_request_error"] }, "code": { "type": "string", "enum": ["dispute_not_found"], "description": "Specific error code", "examples": ["dispute_not_found"] }, "message": { "type": "string", "enum": ["Dispute not found"], "description": "Human-readable error message", "examples": ["Dispute not found"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "The requested dispute does not exist", "examples": [ { "error": { "type": "invalid_request_error", "code": "dispute_not_found", "message": "Dispute not found", "request_id": "req_abc123def456" } } ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "x-audience": ["merchants"] } }, "/public/2025-04-01/disputes/{disputeId}/subscription": { "post": { "operationId": "createSubscription", "tags": ["Disputes"], "summary": "Create Subscription", "description": "Creates a subscription in Chargeflow that can be used to enrich a dispute.", "parameters": [ { "in": "path", "name": "disputeId", "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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "required": true, "example": "66e6ea9ecd94925a9f8060d9" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "source_id": { "type": "string", "maxLength": 128, "description": "The unique subscription identifier appears on the source from which the subscription originated.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "created_at": { "type": "string", "format": "date-time", "description": "The time at which the subscription was created at the source in ISO 8601 format.", "examples": ["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.", "examples": ["2024-02-10T12:00:00Z"] }, "frequency": { "type": "string", "enum": ["day", "week", "month", "year"], "description": "The frequency at which a subscription is billed.", "examples": ["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.", "examples": [1] }, "collection_method": { "type": "string", "enum": ["automatically", "automatically_with_reminder", "send_invoice"], "default": "automatically", "description": "The billing method for the subscription.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["Pro Plan"] }, "pricing_model": { "type": "string", "enum": ["fixed_price", "usage_base"], "default": "fixed_price", "description": "The pricing model associated with the subscription.", "examples": ["fixed_price"] }, "status": { "type": "string", "enum": ["active", "inactive", "canceled"], "default": "active", "description": "The current status of the subscription.", "examples": ["active"] } }, "required": [ "source_id", "created_at", "start_date", "frequency", "frequency_count" ], "description": "Creates a new Chargeflow subscription." } } } }, "responses": { "200": { "description": "Subscription created successfully", "content": { "application/json": { "schema": { "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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "source_id": { "type": ["string", "null"], "maxLength": 128, "description": "The unique subscription identifier appears on the source from which the subscription originated.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["2024-07-10T12:00:00Z"] }, "frequency": { "type": ["string", "null"], "enum": ["day", "week", "month", "year"], "description": "The frequency at which a subscription is billed.", "examples": ["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.", "examples": [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.", "examples": ["too_expensive"] }, "collection_method": { "type": ["string", "null"], "enum": ["automatically", "automatically_with_reminder", "send_invoice"], "description": "The billing method for the subscription.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["Pro Plan"] }, "pricing_model": { "type": ["string", "null"], "enum": ["fixed_price", "usage_base"], "description": "The pricing model associated with the subscription.", "examples": ["fixed_price"] }, "status": { "type": ["string", "null"], "enum": ["active", "inactive", "canceled"], "description": "The current status of the subscription.", "examples": ["active"] } }, "description": "The subscription object." } } } }, "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", "examples": ["invalid_request_error"] }, "code": { "type": "string", "enum": ["missing_dispute_id"], "description": "Specific error code", "examples": ["missing_dispute_id"] }, "message": { "type": "string", "enum": ["Dispute ID is required"], "description": "Human-readable error message", "examples": ["Dispute ID is required"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "Dispute ID parameter is missing or invalid", "examples": [ { "error": { "type": "invalid_request_error", "code": "missing_dispute_id", "message": "Dispute ID is required", "request_id": "req_abc123def456" } } ], "x-readme-ref-name": "MissingDisputeIdError" } } } }, "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", "examples": ["authentication_error"] }, "code": { "type": "string", "enum": ["unauthorized", "invalid_credentials", "missing_credentials"], "description": "Specific error code", "examples": ["unauthorized"] }, "message": { "type": "string", "enum": [ "Unauthorized access", "Authentication credentials are missing or invalid" ], "description": "Human-readable error message", "examples": ["Unauthorized access"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "Unauthorized - Authentication is required or has failed", "examples": [ { "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", "examples": ["permission_error"] }, "code": { "type": "string", "enum": ["forbidden", "invalid_platform_access", "account_not_found"], "description": "Specific error code", "examples": ["forbidden"] }, "message": { "type": "string", "enum": [ "Forbidden", "Invalid platform access - account_id does not belong to the platform", "Account not found" ], "description": "Human-readable error message", "examples": ["Forbidden"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "The authenticated user does not have permission to create a subscription for this dispute", "examples": [ { "error": { "type": "permission_error", "code": "forbidden", "message": "Forbidden", "request_id": "req_abc123def456" } } ], "x-readme-ref-name": "CreateSubscriptionForbiddenError" } } } }, "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", "examples": ["api_error"] }, "code": { "type": "string", "enum": [ "internal_error", "server_error", "account_creation_failed", "account_retrieval_failed", "account_update_failed" ], "description": "Specific error code", "examples": ["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", "examples": ["Internal server error"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["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.", "examples": [ { "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error", "request_id": "req_abc123def456" } } ], "x-readme-ref-name": "InternalServerError" } } } } }, "x-audience": ["merchants"] } }, "/public/2025-04-01/disputes": { "get": { "operationId": "getDisputes", "tags": ["Disputes"], "summary": "Get Disputes", "description": "Retrieves a list of disputes based on the provided pagination parameters", "parameters": [ { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0, "default": 0, "description": "The page number of the current response", "examples": [0] }, "example": "0" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "The number of disputes per page", "examples": [25] }, "example": "10" } ], "responses": { "200": { "description": "List of disputes retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "disputes": { "type": "array", "items": { "type": ["object", "null"], "properties": { "id": { "type": ["string", "null"], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow object identifier of the dispute.", "examples": ["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", "examples": ["stripe"] }, "source_id": { "type": ["string", "null"], "maxLength": 128, "description": "The unique dispute identifier appears on the source (processor) from which the dispute originated.", "examples": ["du_123456789"] }, "account_id": { "type": ["string", "null"], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the dispute belongs.", "examples": ["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.", "examples": ["acc_123456"] }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "The time at which the dispute was created in ISO 8601 format.", "examples": ["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.", "examples": ["fraud"] }, "due_by": { "type": ["string", "null"], "format": "date-time", "description": "The deadline to submit evidence to challenge the dispute in ISO 8601 format.", "examples": ["2024-02-20T12:00:00Z"] }, "amount": { "type": ["number", "null"], "minimum": 0, "description": "Disputed amount. Equal to or less than the disputed transaction amount.", "examples": [100] }, "currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["USD"] }, "status": { "type": ["string", "null"], "enum": ["needs_response", "under_review", "won", "lost"], "description": "The current status of the dispute.", "examples": ["needs_response"] }, "stage": { "type": ["string", "null"], "enum": ["Chargeback", "Inquiry", "Pre_arbitration", "Arbitration"], "description": "The stage of the dispute.", "examples": ["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.", "examples": ["2025-01-27T10:00:00Z"] }, "transaction": { "type": ["string", "null"], "maxLength": 128, "description": "The transaction ID associated with the dispute. Can be a Chargeflow transaction identifier or a transaction identifier from the source.", "examples": ["tx_1234567890"] }, "subscription": { "type": ["string", "null"], "maxLength": 128, "description": "The subscription ID associated with the dispute. Can be a Chargeflow subscription identifier or a subscription identifier from the source.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "order": { "type": ["string", "null"], "maxLength": 128, "description": "The order ID associated with the dispute. Can be a Chargeflow order identifier or an order identifier from the source.", "examples": ["ord_1234567890"] }, "customerCommunication": { "type": ["string", "null"], "maxLength": 128, "description": "The customer communication ID associated with the dispute. Can be a Chargeflow customer communication identifier or a customer communication identifier from the source.", "examples": ["66e6ea9ecd94925a9f8060d9"] } } }, "description": "Array of dispute objects returned in the response" }, "pagination": { "type": "object", "properties": { "totalCount": { "type": "integer", "minimum": 0, "description": "Total number of disputes available in the database", "examples": [100] }, "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "The page number of the current response", "examples": [0] }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "The number of disputes per page", "examples": [25] }, "totalPages": { "type": "integer", "minimum": 0, "description": "Total number of pages available in the database", "examples": [54] } }, "description": "Pagination information for the current response", "examples": [ { "totalCount": 100, "offset": 0, "limit": 25, "totalPages": 54 } ] } }, "default": { "disputes": [], "pagination": { "totalCount": 0, "offset": 0, "limit": 25, "totalPages": 0 } } } } } }, "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", "examples": ["authentication_error"] }, "code": { "type": "string", "enum": ["unauthorized", "invalid_credentials", "missing_credentials"], "description": "Specific error code", "examples": ["unauthorized"] }, "message": { "type": "string", "enum": [ "Unauthorized access", "Authentication credentials are missing or invalid" ], "description": "Human-readable error message", "examples": ["Unauthorized access"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "Unauthorized - Authentication is required or has failed", "examples": [ { "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", "examples": ["permission_error"] }, "code": { "type": "string", "enum": ["unauthorized_shop_access"], "description": "Specific error code", "examples": ["unauthorized_shop_access"] }, "message": { "type": "string", "enum": ["Unauthorized access to shop data"], "description": "Human-readable error message", "examples": ["Unauthorized access to shop data"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "User does not have access to the requested shop data", "examples": [ { "error": { "type": "permission_error", "code": "unauthorized_shop_access", "message": "Unauthorized access to shop data", "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", "examples": ["api_error"] }, "code": { "type": "string", "enum": [ "internal_error", "server_error", "account_creation_failed", "account_retrieval_failed", "account_update_failed" ], "description": "Specific error code", "examples": ["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", "examples": ["Internal server error"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["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.", "examples": [ { "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error", "request_id": "req_abc123def456" } } ], "x-readme-ref-name": "InternalServerError" } } } } }, "x-audience": ["merchants"] } }, "/public/2025-04-01/health-check/access-key": { "get": { "operationId": "validateAccessKey", "tags": ["Health Check"], "summary": "Validate Access Key", "description": "Confirms your API Access Key is valid and active. A 403 means the key is missing, invalid, or revoked.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string" } } } }, "403": { "description": "Forbidden: the `x-api-key` header is missing, or the key is invalid or revoked. The API does not return `401`; authentication failures return this status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "examples": ["Forbidden"] } } } } } } }, "x-audience": ["merchants"] } }, "/public/2025-04-01/health-check": { "get": { "operationId": "serviceHealthVerification", "tags": ["Health Check"], "summary": "Service Health Verification", "description": "Confirms the Chargeflow API is reachable and responding. Requires no authentication and returns 200 even without an x-api-key header, so it reports service availability only. To check credentials, call the access-key health check.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string", "description": "OK" } } } } }, "security": [], "x-audience": ["merchants"] } }, "/public/2025-04-01/webhooks": { "get": { "operationId": "getWebhooks", "tags": ["Webhooks Management"], "summary": "Get Webhooks", "description": "The Get All Webhooks API allows you to retrieve all webhook registrations for a specific chargeflowId.", "responses": { "200": { "description": "Webhooks retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "event": { "type": "string" }, "url": { "type": "string" } } } } } } } } }, "500": { "description": "Internal Server Error - DB failure or any server failure", "content": { "application/json": { "schema": { "type": "string", "enum": ["Internal server error"] } } } } }, "x-audience": ["merchants"] }, "post": { "operationId": "createWebhook", "tags": ["Webhooks Management"], "summary": "Create Webhook", "description": "The Create Webhook API allows you to register a webhook for a specific event type and URL target.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "enum": [ "webhook.test", "dispute.created", "evidence.ready", "evidence.error", "alerts.created", "alerts.updated", "alerts.transaction.linked", "*" ], "description": "The event type to listen for" }, "url": { "type": "string", "format": "uri", "description": "The URL to send the webhook to" } }, "required": ["event", "url"] } } } }, "responses": { "200": { "description": "Webhook created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" } } } } } }, "400": { "description": "Bad Request - Missing API Key or webhook already exists", "content": { "application/json": { "schema": { "type": "string", "enum": ["Missing API Key", "Webhook registration already exists"] } } } }, "404": { "description": "Not Found - API Key not found or request_cf_id not equal to keyChargeflowId", "content": { "application/json": { "schema": { "type": "string", "enum": ["API Key not found", "API key not found"] } } } }, "500": { "description": "Internal Server Error - DB failure or any server failure", "content": { "application/json": { "schema": { "type": "string", "enum": ["Internal server error", "Failed to create webhook registration"] } } } } }, "x-audience": ["merchants"] } }, "/public/2025-04-01/webhooks/{id}": { "delete": { "operationId": "deleteWebhook", "tags": ["Webhooks Management"], "summary": "Delete Webhook", "description": "The Delete Webhook API allows you to delete a webhook registration by providing the webhook ID.", "parameters": [ { "in": "path", "name": "id", "description": "The Webhook id to delete", "schema": { "type": "string", "description": "The Webhook id to delete", "examples": ["*%23http%3A%2F%2Ftest.com%2Fwebhook"] }, "required": true, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "responses": { "200": { "description": "Webhook deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } } } } }, "404": { "description": "Not Found - Webhook registration not found", "content": { "application/json": { "schema": { "type": "string", "enum": ["Webhook registration not found"] } } } }, "500": { "description": "Internal Server Error - DB failure or any server failure", "content": { "application/json": { "schema": { "type": "string", "enum": ["Failed to delete webhook registration", "Internal server error"] } } } } }, "x-audience": ["merchants"] } }, "/public/2025-04-01/data-subject/removal": { "post": { "operationId": "createDataSubjectRemovalRequest", "tags": ["Data Subject"], "summary": "Create Data Subject Removal Request", "description": "Creates a GDPR data subject removal request for the specified email address.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "The email address of the data subject to be removed.", "examples": ["user@example.com"] }, "account_id": { "type": "string", "description": "The Chargeflow account ID. Required for platform API keys, ignored for merchant API keys.", "examples": ["66e6ea9ecd94925a9f8060d9"] } }, "required": ["email"], "additionalProperties": false } } } }, "responses": { "202": { "description": "Removal request accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "The unique identifier of the removal request.", "examples": ["req_abc123"] }, "status": { "type": "string", "description": "The current status of the removal request.", "examples": ["acknowledged"] }, "chargeflow_id": { "type": "string", "description": "The Chargeflow account ID associated with this request.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "created_at": { "type": "string", "description": "The time the request was created in ISO 8601 format.", "examples": ["2025-04-01T12:00:00Z"] } }, "required": ["request_id", "status", "chargeflow_id"], "description": "A data subject removal request." } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequestError" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenError" } } } }, "409": { "description": "Conflict - Duplicate removal request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "invalid_request_error", "description": "The type of error", "examples": ["invalid_request_error"] }, "code": { "type": "string", "enum": ["duplicate_request"], "description": "Specific error code", "examples": ["duplicate_request"] }, "message": { "type": "string", "enum": ["A removal request for this email already exists"], "description": "Human-readable error message", "examples": ["A removal request for this email already exists"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "A removal request for this email and account already exists", "examples": [ { "error": { "type": "invalid_request_error", "code": "duplicate_request", "message": "A removal request for this email already exists", "request_id": "req_abc123def456" } } ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "x-audience": ["merchants"] } }, "/public/2025-04-01/data-subject/removal/{requestId}": { "get": { "operationId": "getRemovalRequestStatus", "tags": ["Data Subject"], "summary": "Get Removal Request Status", "description": "Retrieves the status of a data subject removal request.", "parameters": [ { "in": "path", "name": "requestId", "description": "The unique identifier of the removal request.", "schema": { "type": "string", "description": "The unique identifier of the removal request.", "examples": ["req_abc123"] }, "required": true, "example": "req_abc123" }, { "in": "query", "name": "account_id", "description": "The Chargeflow account ID. Required for platform API keys.", "schema": { "type": "string", "description": "The Chargeflow account ID. Required for platform API keys.", "examples": ["66e6ea9ecd94925a9f8060d9"] } } ], "responses": { "200": { "description": "Removal request status retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "description": "The unique identifier of the removal request.", "examples": ["req_abc123"] }, "status": { "type": "string", "description": "The current status of the removal request.", "examples": ["acknowledged"] }, "chargeflow_id": { "type": "string", "description": "The Chargeflow account ID associated with this request.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "created_at": { "type": "string", "description": "The time the request was created in ISO 8601 format.", "examples": ["2025-04-01T12:00:00Z"] } }, "required": ["request_id", "status", "chargeflow_id"], "description": "A data subject removal request." } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/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", "examples": ["invalid_request_error"] }, "code": { "type": "string", "enum": ["removal_request_not_found"], "description": "Specific error code", "examples": ["removal_request_not_found"] }, "message": { "type": "string", "enum": ["Removal request not found"], "description": "Human-readable error message", "examples": ["Removal request not found"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "The specified removal request does not exist", "examples": [ { "error": { "type": "invalid_request_error", "code": "removal_request_not_found", "message": "Removal request not found", "request_id": "req_abc123def456" } } ] } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalServerError" } } } } }, "x-audience": ["merchants"] } }, "/public/2025-04-01/accounts": { "post": { "operationId": "createAccount", "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.", "examples": ["Example Merchants Ltd."] }, "business_name": { "type": "string", "maxLength": 10000, "description": "The account name, which represents the business name of the account.", "examples": ["Example Merchants Ltd."] }, "business_url": { "type": "string", "format": "uri", "maxLength": 10000, "description": "The public URL of the business website.", "examples": ["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.", "examples": ["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.", "examples": ["platform_987654321"] }, "status": { "type": "string", "enum": ["active", "inactive"], "default": "active", "description": "The status of the account; defaults to active.", "examples": ["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.", "examples": ["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.", "examples": ["platform_987654321"] }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "The time at which the account was created in ISO 8601 format.", "examples": ["2024-02-10T12:00:00Z"] }, "owner_name": { "type": ["string", "null"], "maxLength": 10000, "description": "The account owner's name.", "examples": ["Example Merchants Ltd."] }, "business_name": { "type": ["string", "null"], "maxLength": 10000, "description": "The account name, which represents the Business name.", "examples": ["Example Merchants Ltd."] }, "business_url": { "type": ["string", "null"], "format": "uri", "maxLength": 10000, "description": "The public URL of the company website.", "examples": ["https://example.com"] }, "email": { "type": ["string", "null"], "format": "email", "maxLength": 128, "description": "The account owner's email address, used to log in and contact.", "examples": ["merchant@example.com"] }, "status": { "type": ["string", "null"], "enum": ["active", "inactive"], "description": "The status of the account; defaults to active.", "examples": ["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", "examples": ["invalid_request_error"] }, "code": { "type": "string", "enum": ["invalid_parameter", "missing_parameter", "invalid_format"], "description": "Specific error code", "examples": ["invalid_parameter"] }, "message": { "type": "string", "enum": ["Bad Request", "Invalid request parameters"], "description": "Human-readable error message", "examples": ["Bad Request"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "Bad Request - The request contains invalid parameters or is malformed", "examples": [ { "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", "examples": ["authentication_error"] }, "code": { "type": "string", "enum": ["unauthorized", "invalid_credentials", "missing_credentials"], "description": "Specific error code", "examples": ["unauthorized"] }, "message": { "type": "string", "enum": [ "Unauthorized access", "Authentication credentials are missing or invalid" ], "description": "Human-readable error message", "examples": ["Unauthorized access"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "Unauthorized - Authentication is required or has failed", "examples": [ { "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", "examples": ["permission_error"] }, "code": { "type": "string", "enum": ["forbidden", "insufficient_permissions"], "description": "Specific error code", "examples": ["forbidden"] }, "message": { "type": "string", "enum": [ "Forbidden", "You do not have permission to access this resource" ], "description": "Human-readable error message", "examples": ["Forbidden"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["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", "examples": [ { "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", "examples": ["invalid_request_error"] }, "code": { "type": "string", "enum": ["account_not_found", "platform_not_found"], "description": "Specific error code", "examples": ["account_not_found"] }, "message": { "type": "string", "enum": ["Account not found", "Platform not found"], "description": "Human-readable error message", "examples": ["Account not found"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "The requested account or platform does not exist", "examples": [ { "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", "examples": ["api_error"] }, "code": { "type": "string", "enum": [ "internal_error", "server_error", "account_creation_failed", "account_retrieval_failed", "account_update_failed" ], "description": "Specific error code", "examples": ["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", "examples": ["Internal server error"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["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.", "examples": [ { "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error", "request_id": "req_abc123def456" } } ], "x-readme-ref-name": "InternalServerError" } } } } }, "x-audience": ["platforms"] } }, "/public/2025-04-01/accounts/{accountId}": { "get": { "operationId": "getAccountByID", "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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "required": true, "example": "66e6ea9ecd94925a9f8060d9" } ], "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.", "examples": ["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.", "examples": ["platform_987654321"] }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "The time at which the account was created in ISO 8601 format.", "examples": ["2024-02-10T12:00:00Z"] }, "owner_name": { "type": ["string", "null"], "maxLength": 10000, "description": "The account owner's name.", "examples": ["Example Merchants Ltd."] }, "business_name": { "type": ["string", "null"], "maxLength": 10000, "description": "The account name, which represents the Business name.", "examples": ["Example Merchants Ltd."] }, "business_url": { "type": ["string", "null"], "format": "uri", "maxLength": 10000, "description": "The public URL of the company website.", "examples": ["https://example.com"] }, "email": { "type": ["string", "null"], "format": "email", "maxLength": 128, "description": "The account owner's email address, used to log in and contact.", "examples": ["merchant@example.com"] }, "status": { "type": ["string", "null"], "enum": ["active", "inactive"], "description": "The status of the account; defaults to active.", "examples": ["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", "examples": ["invalid_request_error"] }, "code": { "type": "string", "enum": ["invalid_parameter", "missing_account_id"], "description": "Specific error code", "examples": ["invalid_parameter"] }, "message": { "type": "string", "enum": ["Bad Request", "Account ID is required"], "description": "Human-readable error message", "examples": ["Bad Request"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "Invalid or missing account ID parameter", "examples": [ { "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", "examples": ["authentication_error"] }, "code": { "type": "string", "enum": ["unauthorized", "invalid_credentials", "missing_credentials"], "description": "Specific error code", "examples": ["unauthorized"] }, "message": { "type": "string", "enum": [ "Unauthorized access", "Authentication credentials are missing or invalid" ], "description": "Human-readable error message", "examples": ["Unauthorized access"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "Unauthorized - Authentication is required or has failed", "examples": [ { "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", "examples": ["permission_error"] }, "code": { "type": "string", "enum": ["forbidden", "insufficient_permissions"], "description": "Specific error code", "examples": ["forbidden"] }, "message": { "type": "string", "enum": [ "Forbidden", "You do not have permission to access this resource" ], "description": "Human-readable error message", "examples": ["Forbidden"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["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", "examples": [ { "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", "examples": ["invalid_request_error"] }, "code": { "type": "string", "enum": ["account_not_found"], "description": "Specific error code", "examples": ["account_not_found"] }, "message": { "type": "string", "enum": ["Account not found"], "description": "Human-readable error message", "examples": ["Account not found"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "The requested account does not exist", "examples": [ { "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", "examples": ["api_error"] }, "code": { "type": "string", "enum": [ "internal_error", "server_error", "account_creation_failed", "account_retrieval_failed", "account_update_failed" ], "description": "Specific error code", "examples": ["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", "examples": ["Internal server error"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["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.", "examples": [ { "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error", "request_id": "req_abc123def456" } } ], "x-readme-ref-name": "InternalServerError" } } } } }, "x-audience": ["platforms"] } }, "/public/2025-04-01/evidence": { "post": { "operationId": "generateEvidence", "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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["fraud"] }, "due_by": { "type": "string", "format": "date-time", "description": "The deadline to submit evidence to challenge the dispute in ISO 8601 format.", "examples": ["2024-02-20T12:00:00Z"] }, "amount": { "type": "number", "minimum": 0, "description": "Disputed amount. Equal to or less than the disputed transaction amount.", "examples": [100] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["USD"] }, "status": { "type": "string", "enum": ["needs_response", "under_review", "won", "lost"], "description": "The current status of the dispute.", "examples": ["needs_response"] }, "stage": { "type": "string", "enum": ["Chargeback", "Inquiry", "Pre_arbitration", "Arbitration"], "default": "Chargeback", "description": "The stage of the dispute. Default is chargeback.", "examples": ["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.", "examples": ["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.", "examples": ["2024-02-10T12:00:00Z"] }, "type": { "type": "string", "enum": [ "paid", "partially_paid", "refunded", "partially_refunded" ], "description": "The type of the transaction", "examples": ["paid"] }, "amount": { "type": "number", "minimum": 0, "description": "Transaction total amount after all deductions.", "examples": [100] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["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.", "examples": ["John Doe"] }, "type": { "type": ["string", "null"], "enum": ["card", "wallet"], "description": "The type of the payment method", "examples": ["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`", "examples": ["1234"] }, "expiry_month": { "type": ["integer", "null"], "minimum": 1, "maximum": 12, "description": "The month when the card used for the transaction is expired. `card`", "examples": [1] }, "expiry_year": { "type": ["integer", "null"], "minimum": 2019, "maximum": 2100, "description": "The year when the card used for the transaction is expired. `card`", "examples": [2025] }, "brand": { "type": ["string", "null"], "enum": [ "visa", "mastercard", "discover", "amex", "jcb", "unionpay", "diners", "other" ], "description": "The card brand used for the transaction. `card`", "examples": ["visa"] }, "country": { "type": ["string", "null"], "pattern": "^[A-Z]{2}$", "description": "The card issuance country - two-letter country code (ISO 3166-1 alpha-2). `card`", "examples": ["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`", "examples": ["paypal"] }, "checks": { "type": "object", "properties": { "three_d_secure_result": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The 3D secure authentication outcome. `card`", "examples": ["passed"] }, "avs_results": { "type": ["string", "null"], "enum": ["N", "A", "Y", "Z"], "description": "The address verification system outcome. `card`", "examples": ["N"] }, "address_line1_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The address line1 check result. `card`", "examples": ["passed"] }, "address_zip_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The address zip or postal code check result. `card`", "examples": ["passed"] }, "cvc_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The card verification code result. `card`", "examples": ["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`", "examples": ["john.doe@example.com"] }, "wallet_id": { "type": ["string", "null"], "maxLength": 128, "description": "The wallet unique identifier which used for the transaction. `wallet`", "examples": ["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.", "examples": ["John Doe"] }, "line1": { "type": ["string", "null"], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "examples": ["123 Main St"] }, "line2": { "type": ["string", "null"], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "examples": ["Apt 1"] }, "city": { "type": ["string", "null"], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "examples": ["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", "examples": ["US"] }, "state": { "type": ["string", "null"], "description": "State, county, province, or region associated with the address lines.", "examples": ["CA"] }, "zip_code": { "type": ["string", "null"], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "examples": ["12345"] }, "phone": { "type": ["string", "null"], "description": "The phone number of the person associated with the billing address.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "examples": ["ord_1234567890"] } ], "description": "The unique Chargeflow identifier of the order to which the transaction is linked.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "created_at": { "type": "string", "format": "date-time", "description": "The time at which the subscription was created at the source in ISO 8601 format.", "examples": ["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.", "examples": ["2024-02-10T12:00:00Z"] }, "frequency": { "type": "string", "enum": ["day", "week", "month", "year"], "description": "The frequency at which a subscription is billed.", "examples": ["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.", "examples": [1] }, "collection_method": { "type": "string", "enum": [ "automatically", "automatically_with_reminder", "send_invoice" ], "default": "automatically", "description": "The billing method for the subscription.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["Pro Plan"] }, "pricing_model": { "type": "string", "enum": ["fixed_price", "usage_base"], "default": "fixed_price", "description": "The pricing model associated with the subscription.", "examples": ["fixed_price"] }, "status": { "type": "string", "enum": ["active", "inactive", "canceled"], "default": "active", "description": "The current status of the subscription.", "examples": ["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.", "examples": ["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.", "examples": ["2024-02-10T12:00:00Z"] }, "payment_status": { "type": "string", "enum": [ "paid", "partially_paid", "refunded", "partially_refunded" ], "description": "The financial status of the order", "examples": ["paid"] }, "amount": { "type": "number", "minimum": 0, "description": "Order total amount after all deductions.", "examples": [1000] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["USD"] }, "name": { "type": "string", "maxLength": 128, "description": "The order name or number as appear in your source", "examples": ["#ORD-12345"] }, "type": { "type": "string", "enum": ["standard", "pre_order"], "default": "standard", "description": "The type of the order; defaults to standard.", "examples": ["standard"] }, "customer": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 128, "description": "The full name of the customer who have made this order.", "examples": ["John Doe"] }, "email": { "type": "string", "format": "email", "maxLength": 128, "description": "The email address belong to the customer. Valid format:", "examples": ["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.", "examples": ["2025-01-27T10:00:00Z"] }, "order_count": { "type": "integer", "minimum": 0, "description": "The count of orders made by this customer with the merchant.", "examples": [1] }, "phone_number": { "type": "string", "maxLength": 128, "description": "The phone number belong to the customer. Valid format:", "examples": ["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.", "examples": ["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.", "examples": [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.", "examples": ["Product Name"] }, "id": { "type": "string", "maxLength": 128, "description": "The product unique identifier. Relevant to link it to tracking number and shipping method.", "examples": ["123456789"] }, "type": { "type": "string", "enum": [ "physical_good", "digital_good", "service", "other" ], "description": "The type of the product", "examples": ["physical_good"] }, "quantity": { "type": "integer", "minimum": 1, "description": "The number of items that were purchased.", "examples": [1] }, "description": { "type": "string", "maxLength": 1000, "description": "A short description of the product as communicated to the customer in the merchant's product page.", "examples": ["Product Description"] }, "image_url": { "type": "string", "format": "uri", "maxLength": 1000, "description": "A url of the primary product image associated with the product. Valid format:", "examples": ["https://myurl.com/image/product/123456789"] }, "price": { "type": "number", "minimum": 0, "description": "The price amount of the given product in the order's currency.", "examples": [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.", "examples": ["John Doe"] }, "line1": { "type": ["string", "null"], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "examples": ["123 Main St"] }, "line2": { "type": ["string", "null"], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "examples": ["Apt 1"] }, "city": { "type": ["string", "null"], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "examples": ["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", "examples": ["US"] }, "state": { "type": ["string", "null"], "description": "State, county, province, or region associated with the address lines.", "examples": ["CA"] }, "zip_code": { "type": ["string", "null"], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "examples": ["12345"] }, "phone": { "type": ["string", "null"], "description": "The phone number of the person associated with the shipping address.", "examples": ["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.", "examples": ["123456789"] }, "shipped_at": { "type": ["string", "null"], "format": "date-time", "description": "The time at which the order was shipped in ISO 8601 format.", "examples": ["2025-01-27T10:00:00Z"] }, "shipping_line_title": { "type": ["string", "null"], "maxLength": 128, "description": "The shipping line title.", "examples": ["FedEx"] }, "shipping_method_price": { "type": ["number", "null"], "minimum": 0, "description": "The shipping method price as paid by the customer in the order's currency.", "examples": [100] }, "tracking_number": { "type": ["string", "null"], "maxLength": 128, "description": "The tracking number that was provided to track the fulfillment journey.", "examples": ["123456789"] }, "courier": { "type": ["string", "null"], "maxLength": 128, "description": "The shipping courier from which the tracking number originated and used to fulfill the order.", "examples": ["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.", "examples": ["ev_abc123456789"] }, "account_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the evidence belongs.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "ext_account_id": { "type": "string", "maxLength": 1000, "description": "The unique account identifier appears on the platform.", "examples": ["ext_acct_54321"] }, "dispute": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow dispute identifier to which the evidence associated with.", "examples": ["dp_112233445"] }, "created_at": { "type": "string", "format": "date-time", "description": "The time at which the evidence was created at Chargeflow in ISO 8601 format.", "examples": ["2025-07-29T14:35:00Z"] }, "status": { "type": "string", "enum": ["in_progress", "completed", "error"], "description": "The status of the evidence generation.", "examples": ["in_progress"] }, "file_url": { "type": "string", "format": "uri", "description": "A downloadable link to the generated evidence in a PDF format.", "examples": [ "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.", "examples": [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" } }, "x-audience": ["platforms"] } }, "/public/2025-04-01/evidence/{evidenceId}": { "get": { "operationId": "getEvidenceByID", "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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "required": true, "example": "ev_abc123456789" }, { "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", "examples": [["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.", "examples": ["ev_abc123456789"] }, "account_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the evidence belongs.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "ext_account_id": { "type": "string", "maxLength": 1000, "description": "The unique account identifier appears on the platform.", "examples": ["ext_acct_54321"] }, "dispute": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow object identifier of the dispute.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "object", "properties": { "id": { "type": ["string", "null"], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow object identifier of the dispute.", "examples": ["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", "examples": ["stripe"] }, "source_id": { "type": ["string", "null"], "maxLength": 128, "description": "The unique dispute identifier appears on the source (processor) from which the dispute originated.", "examples": ["du_123456789"] }, "account_id": { "type": ["string", "null"], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the dispute belongs.", "examples": ["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.", "examples": ["acc_123456"] }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "The time at which the dispute was created in ISO 8601 format.", "examples": ["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.", "examples": ["fraud"] }, "due_by": { "type": ["string", "null"], "format": "date-time", "description": "The deadline to submit evidence to challenge the dispute in ISO 8601 format.", "examples": ["2024-02-20T12:00:00Z"] }, "amount": { "type": ["number", "null"], "minimum": 0, "description": "Disputed amount. Equal to or less than the disputed transaction amount.", "examples": [100] }, "currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["USD"] }, "status": { "type": ["string", "null"], "enum": ["needs_response", "under_review", "won", "lost"], "description": "The current status of the dispute.", "examples": ["needs_response"] }, "stage": { "type": ["string", "null"], "enum": ["Chargeback", "Inquiry", "Pre_arbitration", "Arbitration"], "description": "The stage of the dispute.", "examples": ["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.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The transaction ID from the source.", "examples": ["tx_1234567890"] } ], "description": "The transaction ID associated with the dispute. Can be a Chargeflow transaction identifier or a transaction identifier from the source.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The transaction ID from the source.", "examples": ["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.", "examples": ["tx_1234567890"] }, "source_id": { "type": ["string", "null"], "maxLength": 128, "description": "The unique transaction identifier appears on the source from which the transaction originated.", "examples": ["tx_1234567890"] }, "account_id": { "type": ["string", "null"], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the transaction belongs.", "examples": ["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.", "examples": ["acc_123456"] }, "order_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "examples": ["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.", "examples": ["ord_1234567890"] }, "subscription_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow subscription ID associated with the dispute.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The subscription ID from the source.", "examples": ["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.", "examples": ["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.", "examples": ["2024-02-10T12:00:00Z"] }, "type": { "type": ["string", "null"], "enum": [ "paid", "partially_paid", "refunded", "partially_refunded" ], "description": "The type of the transaction", "examples": ["paid"] }, "amount": { "type": ["number", "null"], "minimum": 0, "description": "Transaction total amount after all deductions.", "examples": [100] }, "currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["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.", "examples": ["John Doe"] }, "type": { "type": ["string", "null"], "enum": ["card", "wallet"], "description": "The type of the payment method", "examples": ["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`", "examples": ["1234"] }, "expiry_month": { "type": ["integer", "null"], "minimum": 1, "maximum": 12, "description": "The month when the card used for the transaction is expired. `card`", "examples": [1] }, "expiry_year": { "type": ["integer", "null"], "minimum": 2019, "maximum": 2100, "description": "The year when the card used for the transaction is expired. `card`", "examples": [2025] }, "brand": { "type": ["string", "null"], "enum": [ "visa", "mastercard", "discover", "amex", "jcb", "unionpay", "diners", "other" ], "description": "The card brand used for the transaction. `card`", "examples": ["visa"] }, "country": { "type": ["string", "null"], "pattern": "^[A-Z]{2}$", "description": "The card issuance country - two-letter country code (ISO 3166-1 alpha-2). `card`", "examples": ["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`", "examples": ["paypal"] }, "checks": { "type": "object", "properties": { "three_d_secure_result": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The 3D secure authentication outcome. `card`", "examples": ["passed"] }, "avs_results": { "type": ["string", "null"], "enum": ["N", "A", "Y", "Z"], "description": "The address verification system outcome. `card`", "examples": ["N"] }, "address_line1_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The address line1 check result. `card`", "examples": ["passed"] }, "address_zip_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The address zip or postal code check result. `card`", "examples": ["passed"] }, "cvc_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The card verification code result. `card`", "examples": ["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`", "examples": ["john.doe@example.com"] }, "wallet_id": { "type": ["string", "null"], "maxLength": 128, "description": "The wallet unique identifier which used for the transaction. `wallet`", "examples": ["1234567890"] } }, "description": "The payment method used for the transaction.", "examples": [ { "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.", "examples": ["John Doe"] }, "line1": { "type": ["string", "null"], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "examples": ["123 Main St"] }, "line2": { "type": ["string", "null"], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "examples": ["Apt 1"] }, "city": { "type": ["string", "null"], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "examples": ["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", "examples": ["US"] }, "state": { "type": ["string", "null"], "description": "State, county, province, or region associated with the address lines.", "examples": ["CA"] }, "zip_code": { "type": ["string", "null"], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "examples": ["12345"] }, "phone": { "type": ["string", "null"], "description": "The phone number of the person associated with the billing address.", "examples": ["1(123)4567890"] } }, "description": "The billing address associated with the payment method at the time of the transaction.", "examples": [ { "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.", "examples": ["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.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "source_id": { "type": ["string", "null"], "maxLength": 128, "description": "The unique subscription identifier appears on the source from which the subscription originated.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["2024-07-10T12:00:00Z"] }, "frequency": { "type": ["string", "null"], "enum": ["day", "week", "month", "year"], "description": "The frequency at which a subscription is billed.", "examples": ["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.", "examples": [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.", "examples": ["too_expensive"] }, "collection_method": { "type": ["string", "null"], "enum": [ "automatically", "automatically_with_reminder", "send_invoice" ], "description": "The billing method for the subscription.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["Pro Plan"] }, "pricing_model": { "type": ["string", "null"], "enum": ["fixed_price", "usage_base"], "description": "The pricing model associated with the subscription.", "examples": ["fixed_price"] }, "status": { "type": ["string", "null"], "enum": ["active", "inactive", "canceled"], "description": "The current status of the subscription.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "order": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "examples": ["ord_1234567890"] } ], "description": "The order ID associated with the dispute. Can be a Chargeflow order identifier or an order identifier from the source.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "examples": ["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.", "examples": ["ord_1234567890"] }, "source_id": { "type": ["string", "null"], "maxLength": 128, "description": "The unique order identifier appears on the source from which the order originated.", "examples": ["order_1234567890"] }, "account_id": { "type": ["string", "null"], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the order belongs.", "examples": ["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.", "examples": ["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.", "examples": ["2025-01-27T10:00:00Z"] }, "payment_status": { "type": ["string", "null"], "enum": [ "paid", "partially_paid", "refunded", "partially_refunded" ], "description": "The financial status of the order", "examples": ["paid"] }, "name": { "type": ["string", "null"], "maxLength": 128, "description": "The order name or number as appear in your source", "examples": ["#ORD-12345"] }, "type": { "type": ["string", "null"], "enum": ["standard", "pre_order"], "description": "The type of the order; defaults to standard.", "examples": ["standard"] }, "amount": { "type": ["number", "null"], "minimum": 0, "description": "Order total amount after all deductions.", "examples": [1000] }, "currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["USD"] }, "customer": { "type": ["object", "null"], "properties": { "name": { "type": ["string", "null"], "maxLength": 128, "description": "The full name of the customer who have made this order.", "examples": ["John Doe"] }, "email": { "type": ["string", "null"], "format": "email", "maxLength": 128, "description": "The email address belong to the customer. Valid format:", "examples": ["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.", "examples": ["2025-01-27T10:00:00Z"] }, "order_count": { "type": ["integer", "null"], "minimum": 0, "description": "The count of orders made by this customer with the merchant.", "examples": [1] }, "phone_number": { "type": ["string", "null"], "maxLength": 128, "description": "The phone number belong to the customer. Valid format:", "examples": ["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.", "examples": ["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.", "examples": [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.", "examples": ["Product Name"] }, "id": { "type": ["string", "null"], "maxLength": 128, "description": "The product unique identifier. Relevant to link it to tracking number and shipping method.", "examples": ["123456789"] }, "type": { "type": ["string", "null"], "enum": [ "physical_good", "digital_good", "service", "other" ], "description": "The type of the product", "examples": ["physical_good"] }, "quantity": { "type": ["integer", "null"], "minimum": 1, "description": "The number of items that were purchased.", "examples": [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.", "examples": ["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:", "examples": [ "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.", "examples": [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.", "examples": ["John Doe"] }, "line1": { "type": ["string", "null"], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "examples": ["123 Main St"] }, "line2": { "type": ["string", "null"], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "examples": ["Apt 1"] }, "city": { "type": ["string", "null"], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "examples": ["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", "examples": ["US"] }, "state": { "type": ["string", "null"], "description": "State, county, province, or region associated with the address lines.", "examples": ["CA"] }, "zip_code": { "type": ["string", "null"], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "examples": ["12345"] }, "phone": { "type": ["string", "null"], "description": "The phone number of the person associated with the shipping address.", "examples": ["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.", "examples": ["123456789"] }, "shipped_at": { "type": ["string", "null"], "format": "date-time", "description": "The time at which the order was shipped in ISO 8601 format.", "examples": ["2025-01-27T10:00:00Z"] }, "shipping_line_title": { "type": ["string", "null"], "maxLength": 128, "description": "The shipping line title.", "examples": ["FedEx"] }, "shipping_method_price": { "type": ["number", "null"], "minimum": 0, "description": "The shipping method price as paid by the customer in the order's currency.", "examples": [100] }, "tracking_number": { "type": ["string", "null"], "maxLength": 128, "description": "The tracking number that was provided to track the fulfillment journey.", "examples": ["123456789"] }, "courier": { "type": ["string", "null"], "maxLength": 128, "description": "The shipping courier from which the tracking number originated and used to fulfill the order.", "examples": ["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.", "examples": ["2025-07-29T14:35:00Z"] }, "status": { "type": "string", "enum": ["in_progress", "completed", "error"], "description": "The status of the evidence generation.", "examples": ["in_progress"] }, "file_url": { "type": "string", "format": "uri", "description": "A downloadable link to the generated evidence in a PDF format.", "examples": [ "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.", "examples": [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" } }, "x-audience": ["platforms"] } }, "/public/2025-04-01/platform/disputes": { "post": { "operationId": "createDispute", "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.", "examples": ["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)", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "created_at": { "type": "string", "format": "date-time", "description": "The time at which the dispute was created at the processor in ISO 8601 format.", "examples": ["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.", "examples": ["fraud"] }, "due_by": { "type": "string", "format": "date-time", "description": "The deadline to submit evidence to challenge the dispute in ISO 8601 format.", "examples": ["2024-02-20T12:00:00Z"] }, "amount": { "type": "number", "minimum": 0, "description": "Disputed amount. Equal to or less than the disputed transaction amount.", "examples": [100] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["USD"] }, "status": { "type": "string", "enum": ["needs_response", "under_review", "won", "lost"], "description": "The current status of the dispute.", "examples": ["needs_response"] }, "stage": { "type": "string", "enum": ["Chargeback", "Inquiry", "Pre_arbitration", "Arbitration"], "default": "Chargeback", "description": "The stage of the dispute. Default is chargeback.", "examples": ["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.", "examples": ["tx_1234567890"] }, "account_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the transaction belongs.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "created_at": { "type": "string", "format": "date-time", "description": "The time at which the transaction was created at the source in ISO 8601 format.", "examples": ["2024-02-10T12:00:00Z"] }, "type": { "type": "string", "enum": ["paid", "partially_paid", "refunded", "partially_refunded"], "description": "The type of the transaction", "examples": ["paid"] }, "amount": { "type": "number", "minimum": 0, "description": "Transaction total amount after all deductions.", "examples": [100] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["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.", "examples": ["John Doe"] }, "type": { "type": ["string", "null"], "enum": ["card", "wallet"], "description": "The type of the payment method", "examples": ["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`", "examples": ["1234"] }, "expiry_month": { "type": ["integer", "null"], "minimum": 1, "maximum": 12, "description": "The month when the card used for the transaction is expired. `card`", "examples": [1] }, "expiry_year": { "type": ["integer", "null"], "minimum": 2019, "maximum": 2100, "description": "The year when the card used for the transaction is expired. `card`", "examples": [2025] }, "brand": { "type": ["string", "null"], "enum": [ "visa", "mastercard", "discover", "amex", "jcb", "unionpay", "diners", "other" ], "description": "The card brand used for the transaction. `card`", "examples": ["visa"] }, "country": { "type": ["string", "null"], "pattern": "^[A-Z]{2}$", "description": "The card issuance country - two-letter country code (ISO 3166-1 alpha-2). `card`", "examples": ["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`", "examples": ["paypal"] }, "checks": { "type": "object", "properties": { "three_d_secure_result": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The 3D secure authentication outcome. `card`", "examples": ["passed"] }, "avs_results": { "type": ["string", "null"], "enum": ["N", "A", "Y", "Z"], "description": "The address verification system outcome. `card`", "examples": ["N"] }, "address_line1_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The address line1 check result. `card`", "examples": ["passed"] }, "address_zip_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The address zip or postal code check result. `card`", "examples": ["passed"] }, "cvc_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The card verification code result. `card`", "examples": ["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`", "examples": ["john.doe@example.com"] }, "wallet_id": { "type": ["string", "null"], "maxLength": 128, "description": "The wallet unique identifier which used for the transaction. `wallet`", "examples": ["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.", "examples": ["John Doe"] }, "line1": { "type": ["string", "null"], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "examples": ["123 Main St"] }, "line2": { "type": ["string", "null"], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "examples": ["Apt 1"] }, "city": { "type": ["string", "null"], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "examples": ["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", "examples": ["US"] }, "state": { "type": ["string", "null"], "description": "State, county, province, or region associated with the address lines.", "examples": ["CA"] }, "zip_code": { "type": ["string", "null"], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "examples": ["12345"] }, "phone": { "type": ["string", "null"], "description": "The phone number of the person associated with the billing address.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "examples": ["ord_1234567890"] } ], "description": "The unique Chargeflow identifier of the order to which the transaction is linked.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "created_at": { "type": "string", "format": "date-time", "description": "The time at which the subscription was created at the source in ISO 8601 format.", "examples": ["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.", "examples": ["2024-02-10T12:00:00Z"] }, "frequency": { "type": "string", "enum": ["day", "week", "month", "year"], "description": "The frequency at which a subscription is billed.", "examples": ["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.", "examples": [1] }, "collection_method": { "type": "string", "enum": ["automatically", "automatically_with_reminder", "send_invoice"], "default": "automatically", "description": "The billing method for the subscription.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["Pro Plan"] }, "pricing_model": { "type": "string", "enum": ["fixed_price", "usage_base"], "default": "fixed_price", "description": "The pricing model associated with the subscription.", "examples": ["fixed_price"] }, "status": { "type": "string", "enum": ["active", "inactive", "canceled"], "default": "active", "description": "The current status of the subscription.", "examples": ["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.", "examples": ["order_1234567890"] }, "account_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the order belongs.", "examples": ["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.", "examples": ["2024-02-10T12:00:00Z"] }, "payment_status": { "type": "string", "enum": ["paid", "partially_paid", "refunded", "partially_refunded"], "description": "The financial status of the order", "examples": ["paid"] }, "amount": { "type": "number", "minimum": 0, "description": "Order total amount after all deductions.", "examples": [1000] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["USD"] }, "name": { "type": "string", "maxLength": 128, "description": "The order name or number as appear in your source", "examples": ["#ORD-12345"] }, "type": { "type": "string", "enum": ["standard", "pre_order"], "default": "standard", "description": "The type of the order; defaults to standard.", "examples": ["standard"] }, "customer": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 128, "description": "The full name of the customer who have made this order.", "examples": ["John Doe"] }, "email": { "type": "string", "format": "email", "maxLength": 128, "description": "The email address belong to the customer. Valid format:", "examples": ["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.", "examples": ["2025-01-27T10:00:00Z"] }, "order_count": { "type": "integer", "minimum": 0, "description": "The count of orders made by this customer with the merchant.", "examples": [1] }, "phone_number": { "type": "string", "maxLength": 128, "description": "The phone number belong to the customer. Valid format:", "examples": ["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.", "examples": ["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.", "examples": [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.", "examples": ["Product Name"] }, "id": { "type": "string", "maxLength": 128, "description": "The product unique identifier. Relevant to link it to tracking number and shipping method.", "examples": ["123456789"] }, "type": { "type": "string", "enum": ["physical_good", "digital_good", "service", "other"], "description": "The type of the product", "examples": ["physical_good"] }, "quantity": { "type": "integer", "minimum": 1, "description": "The number of items that were purchased.", "examples": [1] }, "description": { "type": "string", "maxLength": 1000, "description": "A short description of the product as communicated to the customer in the merchant's product page.", "examples": ["Product Description"] }, "image_url": { "type": "string", "format": "uri", "maxLength": 1000, "description": "A url of the primary product image associated with the product. Valid format:", "examples": ["https://myurl.com/image/product/123456789"] }, "price": { "type": "number", "minimum": 0, "description": "The price amount of the given product in the order's currency.", "examples": [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.", "examples": ["John Doe"] }, "line1": { "type": ["string", "null"], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "examples": ["123 Main St"] }, "line2": { "type": ["string", "null"], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "examples": ["Apt 1"] }, "city": { "type": ["string", "null"], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "examples": ["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", "examples": ["US"] }, "state": { "type": ["string", "null"], "description": "State, county, province, or region associated with the address lines.", "examples": ["CA"] }, "zip_code": { "type": ["string", "null"], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "examples": ["12345"] }, "phone": { "type": ["string", "null"], "description": "The phone number of the person associated with the shipping address.", "examples": ["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.", "examples": ["123456789"] }, "shipped_at": { "type": ["string", "null"], "format": "date-time", "description": "The time at which the order was shipped in ISO 8601 format.", "examples": ["2025-01-27T10:00:00Z"] }, "shipping_line_title": { "type": ["string", "null"], "maxLength": 128, "description": "The shipping line title.", "examples": ["FedEx"] }, "shipping_method_price": { "type": ["number", "null"], "minimum": 0, "description": "The shipping method price as paid by the customer in the order's currency.", "examples": [100] }, "tracking_number": { "type": ["string", "null"], "maxLength": 128, "description": "The tracking number that was provided to track the fulfillment journey.", "examples": ["123456789"] }, "courier": { "type": ["string", "null"], "maxLength": 128, "description": "The shipping courier from which the tracking number originated and used to fulfill the order.", "examples": ["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.", "examples": ["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", "examples": ["stripe"] }, "source_id": { "type": ["string", "null"], "maxLength": 128, "description": "The unique dispute identifier appears on the source (processor) from which the dispute originated.", "examples": ["du_123456789"] }, "account_id": { "type": ["string", "null"], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the dispute belongs.", "examples": ["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.", "examples": ["acc_123456"] }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "The time at which the dispute was created in ISO 8601 format.", "examples": ["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.", "examples": ["fraud"] }, "due_by": { "type": ["string", "null"], "format": "date-time", "description": "The deadline to submit evidence to challenge the dispute in ISO 8601 format.", "examples": ["2024-02-20T12:00:00Z"] }, "amount": { "type": ["number", "null"], "minimum": 0, "description": "Disputed amount. Equal to or less than the disputed transaction amount.", "examples": [100] }, "currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["USD"] }, "status": { "type": ["string", "null"], "enum": ["needs_response", "under_review", "won", "lost"], "description": "The current status of the dispute.", "examples": ["needs_response"] }, "stage": { "type": ["string", "null"], "enum": ["Chargeback", "Inquiry", "Pre_arbitration", "Arbitration"], "description": "The stage of the dispute.", "examples": ["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.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The transaction ID from the source.", "examples": ["tx_1234567890"] } ], "description": "The transaction ID associated with the dispute. Can be a Chargeflow transaction identifier or a transaction identifier from the source.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The transaction ID from the source.", "examples": ["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.", "examples": ["tx_1234567890"] }, "source_id": { "type": ["string", "null"], "maxLength": 128, "description": "The unique transaction identifier appears on the source from which the transaction originated.", "examples": ["tx_1234567890"] }, "account_id": { "type": ["string", "null"], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the transaction belongs.", "examples": ["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.", "examples": ["acc_123456"] }, "order_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "examples": ["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.", "examples": ["ord_1234567890"] }, "subscription_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow subscription ID associated with the dispute.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The subscription ID from the source.", "examples": ["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.", "examples": ["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.", "examples": ["2024-02-10T12:00:00Z"] }, "type": { "type": ["string", "null"], "enum": ["paid", "partially_paid", "refunded", "partially_refunded"], "description": "The type of the transaction", "examples": ["paid"] }, "amount": { "type": ["number", "null"], "minimum": 0, "description": "Transaction total amount after all deductions.", "examples": [100] }, "currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["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.", "examples": ["John Doe"] }, "type": { "type": ["string", "null"], "enum": ["card", "wallet"], "description": "The type of the payment method", "examples": ["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`", "examples": ["1234"] }, "expiry_month": { "type": ["integer", "null"], "minimum": 1, "maximum": 12, "description": "The month when the card used for the transaction is expired. `card`", "examples": [1] }, "expiry_year": { "type": ["integer", "null"], "minimum": 2019, "maximum": 2100, "description": "The year when the card used for the transaction is expired. `card`", "examples": [2025] }, "brand": { "type": ["string", "null"], "enum": [ "visa", "mastercard", "discover", "amex", "jcb", "unionpay", "diners", "other" ], "description": "The card brand used for the transaction. `card`", "examples": ["visa"] }, "country": { "type": ["string", "null"], "pattern": "^[A-Z]{2}$", "description": "The card issuance country - two-letter country code (ISO 3166-1 alpha-2). `card`", "examples": ["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`", "examples": ["paypal"] }, "checks": { "type": "object", "properties": { "three_d_secure_result": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The 3D secure authentication outcome. `card`", "examples": ["passed"] }, "avs_results": { "type": ["string", "null"], "enum": ["N", "A", "Y", "Z"], "description": "The address verification system outcome. `card`", "examples": ["N"] }, "address_line1_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The address line1 check result. `card`", "examples": ["passed"] }, "address_zip_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The address zip or postal code check result. `card`", "examples": ["passed"] }, "cvc_check": { "type": ["string", "null"], "enum": ["passed", "failed", "null"], "description": "The card verification code result. `card`", "examples": ["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`", "examples": ["john.doe@example.com"] }, "wallet_id": { "type": ["string", "null"], "maxLength": 128, "description": "The wallet unique identifier which used for the transaction. `wallet`", "examples": ["1234567890"] } }, "description": "The payment method used for the transaction.", "examples": [ { "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.", "examples": ["John Doe"] }, "line1": { "type": ["string", "null"], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "examples": ["123 Main St"] }, "line2": { "type": ["string", "null"], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "examples": ["Apt 1"] }, "city": { "type": ["string", "null"], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "examples": ["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", "examples": ["US"] }, "state": { "type": ["string", "null"], "description": "State, county, province, or region associated with the address lines.", "examples": ["CA"] }, "zip_code": { "type": ["string", "null"], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "examples": ["12345"] }, "phone": { "type": ["string", "null"], "description": "The phone number of the person associated with the billing address.", "examples": ["1(123)4567890"] } }, "description": "The billing address associated with the payment method at the time of the transaction.", "examples": [ { "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.", "examples": ["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.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "source_id": { "type": ["string", "null"], "maxLength": 128, "description": "The unique subscription identifier appears on the source from which the subscription originated.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["2024-07-10T12:00:00Z"] }, "frequency": { "type": ["string", "null"], "enum": ["day", "week", "month", "year"], "description": "The frequency at which a subscription is billed.", "examples": ["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.", "examples": [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.", "examples": ["too_expensive"] }, "collection_method": { "type": ["string", "null"], "enum": [ "automatically", "automatically_with_reminder", "send_invoice" ], "description": "The billing method for the subscription.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["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.", "examples": ["Pro Plan"] }, "pricing_model": { "type": ["string", "null"], "enum": ["fixed_price", "usage_base"], "description": "The pricing model associated with the subscription.", "examples": ["fixed_price"] }, "status": { "type": ["string", "null"], "enum": ["active", "inactive", "canceled"], "description": "The current status of the subscription.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "order": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "examples": ["ord_1234567890"] } ], "description": "The order ID associated with the dispute. Can be a Chargeflow order identifier or an order identifier from the source.", "examples": ["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.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "examples": ["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.", "examples": ["ord_1234567890"] }, "source_id": { "type": ["string", "null"], "maxLength": 128, "description": "The unique order identifier appears on the source from which the order originated.", "examples": ["order_1234567890"] }, "account_id": { "type": ["string", "null"], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the order belongs.", "examples": ["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.", "examples": ["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.", "examples": ["2025-01-27T10:00:00Z"] }, "payment_status": { "type": ["string", "null"], "enum": ["paid", "partially_paid", "refunded", "partially_refunded"], "description": "The financial status of the order", "examples": ["paid"] }, "name": { "type": ["string", "null"], "maxLength": 128, "description": "The order name or number as appear in your source", "examples": ["#ORD-12345"] }, "type": { "type": ["string", "null"], "enum": ["standard", "pre_order"], "description": "The type of the order; defaults to standard.", "examples": ["standard"] }, "amount": { "type": ["number", "null"], "minimum": 0, "description": "Order total amount after all deductions.", "examples": [1000] }, "currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["USD"] }, "customer": { "type": ["object", "null"], "properties": { "name": { "type": ["string", "null"], "maxLength": 128, "description": "The full name of the customer who have made this order.", "examples": ["John Doe"] }, "email": { "type": ["string", "null"], "format": "email", "maxLength": 128, "description": "The email address belong to the customer. Valid format:", "examples": ["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.", "examples": ["2025-01-27T10:00:00Z"] }, "order_count": { "type": ["integer", "null"], "minimum": 0, "description": "The count of orders made by this customer with the merchant.", "examples": [1] }, "phone_number": { "type": ["string", "null"], "maxLength": 128, "description": "The phone number belong to the customer. Valid format:", "examples": ["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.", "examples": ["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.", "examples": [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.", "examples": ["Product Name"] }, "id": { "type": ["string", "null"], "maxLength": 128, "description": "The product unique identifier. Relevant to link it to tracking number and shipping method.", "examples": ["123456789"] }, "type": { "type": ["string", "null"], "enum": ["physical_good", "digital_good", "service", "other"], "description": "The type of the product", "examples": ["physical_good"] }, "quantity": { "type": ["integer", "null"], "minimum": 1, "description": "The number of items that were purchased.", "examples": [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.", "examples": ["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:", "examples": ["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.", "examples": [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.", "examples": ["John Doe"] }, "line1": { "type": ["string", "null"], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "examples": ["123 Main St"] }, "line2": { "type": ["string", "null"], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "examples": ["Apt 1"] }, "city": { "type": ["string", "null"], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "examples": ["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", "examples": ["US"] }, "state": { "type": ["string", "null"], "description": "State, county, province, or region associated with the address lines.", "examples": ["CA"] }, "zip_code": { "type": ["string", "null"], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "examples": ["12345"] }, "phone": { "type": ["string", "null"], "description": "The phone number of the person associated with the shipping address.", "examples": ["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.", "examples": ["123456789"] }, "shipped_at": { "type": ["string", "null"], "format": "date-time", "description": "The time at which the order was shipped in ISO 8601 format.", "examples": ["2025-01-27T10:00:00Z"] }, "shipping_line_title": { "type": ["string", "null"], "maxLength": 128, "description": "The shipping line title.", "examples": ["FedEx"] }, "shipping_method_price": { "type": ["number", "null"], "minimum": 0, "description": "The shipping method price as paid by the customer in the order's currency.", "examples": [100] }, "tracking_number": { "type": ["string", "null"], "maxLength": 128, "description": "The tracking number that was provided to track the fulfillment journey.", "examples": ["123456789"] }, "courier": { "type": ["string", "null"], "maxLength": 128, "description": "The shipping courier from which the tracking number originated and used to fulfill the order.", "examples": ["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", "examples": ["invalid_request_error"] }, "code": { "type": "string", "enum": ["user_not_platform", "eaas_not_enabled"], "description": "Specific error code", "examples": ["user_not_platform"] }, "message": { "type": "string", "enum": [ "User is not a platform", "EAAS is not enabled for this platform" ], "description": "Human-readable error message", "examples": ["User is not a platform"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["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", "examples": [ { "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", "examples": ["authentication_error"] }, "code": { "type": "string", "enum": ["unauthorized", "invalid_credentials", "missing_credentials"], "description": "Specific error code", "examples": ["unauthorized"] }, "message": { "type": "string", "enum": [ "Unauthorized access", "Authentication credentials are missing or invalid" ], "description": "Human-readable error message", "examples": ["Unauthorized access"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "Unauthorized - Authentication is required or has failed", "examples": [ { "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", "examples": ["permission_error"] }, "code": { "type": "string", "enum": ["unauthorized_resource_access"], "description": "Specific error code", "examples": ["unauthorized_resource_access"] }, "message": { "type": "string", "enum": ["Unauthorized access to resource"], "description": "Human-readable error message", "examples": ["Unauthorized access to resource"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "The account_id does not belong to the authenticated platform", "examples": [ { "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", "examples": ["api_error"] }, "code": { "type": "string", "enum": [ "internal_error", "server_error", "account_creation_failed", "account_retrieval_failed", "account_update_failed" ], "description": "Specific error code", "examples": ["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", "examples": ["Internal server error"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["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.", "examples": [ { "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error", "request_id": "req_abc123def456" } } ], "x-readme-ref-name": "InternalServerError" } } } } }, "x-audience": ["platforms"] } } }, "webhooks": { "dispute.created": { "post": { "summary": "Dispute Created Event", "tags": ["Webhooks Events"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The webhook type", "examples": ["dispute.created"] }, "data": { "type": "object", "properties": { "id": { "type": ["string", "null"], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow object identifier of the dispute.", "examples": ["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", null, "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", "examples": ["stripe"] }, "source_id": { "type": ["string", "null"], "maxLength": 128, "description": "The unique dispute identifier appears on the source (processor) from which the dispute originated.", "examples": ["du_123456789"] }, "account_id": { "type": ["string", "null"], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the dispute belongs.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "created_at": { "type": ["string", "null"], "format": "date-time", "description": "The time at which the dispute was created in ISO 8601 format.", "examples": ["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.", "examples": ["fraud"] }, "due_by": { "type": ["string", "null"], "format": "date-time", "description": "The deadline to submit evidence to challenge the dispute in ISO 8601 format.", "examples": ["2024-02-20T12:00:00Z"] }, "amount": { "type": ["number", "null"], "minimum": 0, "description": "Disputed amount. Equal to or less than the disputed transaction amount.", "examples": [100] }, "currency": { "type": ["string", "null"], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "examples": ["USD"] }, "status": { "type": ["string", "null"], "enum": ["needs_response", "under_review", "won", "lost"], "description": "The current status of the dispute.", "examples": ["needs_response"] }, "stage": { "type": ["string", "null"], "enum": ["Chargeback", "Inquiry", "Pre_arbitration", "Arbitration"], "description": "The stage of the dispute.", "examples": ["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.", "examples": ["2025-01-27T10:00:00Z"] }, "transaction": { "type": ["string", "null"], "maxLength": 128, "description": "The transaction ID associated with the dispute. Can be a Chargeflow transaction identifier or a transaction identifier from the source.", "examples": ["tx_1234567890"] }, "subscription": { "type": ["string", "null"], "maxLength": 128, "description": "The subscription ID associated with the dispute. Can be a Chargeflow subscription identifier or a subscription identifier from the source.", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "order": { "type": ["string", "null"], "maxLength": 128, "description": "The order ID associated with the dispute. Can be a Chargeflow order identifier or an order identifier from the source.", "examples": ["ord_1234567890"] }, "customerCommunication": { "type": ["string", "null"], "maxLength": 128, "description": "The customer communication ID associated with the dispute. Can be a Chargeflow customer communication identifier or a customer communication identifier from the source.", "examples": ["66e6ea9ecd94925a9f8060d9"] } } }, "creationDate": { "type": "string", "format": "date-time", "description": "The creation date of the webhook in ISO8601 format", "examples": ["2021-01-01T00:00:00Z"] }, "webhookId": { "type": "string", "format": "uuid", "default": "0b5868f0-9cd9-4e02-b241-7e5eb7f184be", "description": "The webhook id", "examples": ["123e4567-e89b-12d3-a456-426614174000"] } } } } } }, "responses": { "200": { "description": "OK" } }, "x-audience": ["merchants"] } }, "alerts.created": { "post": { "summary": "Alerts Created Event", "description": "Fires when a new pre-chargeback alert is created for your account. The payload carries the alert ID and key metadata.", "tags": ["Webhooks Events"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the alert", "examples": ["687448f9dad73b4c91ba9e2b"] }, "account_id": { "type": "string", "description": "The account identifier associated with the alert", "examples": ["66c58917f37db4bc8d455caa"] }, "ext_account_id": { "type": ["string", "null"], "description": "The external account identifier", "examples": [null] }, "transaction": { "type": "null", "description": "The transaction object associated with the alert", "examples": [null] }, "created_at": { "type": "string", "description": "The date when the alert was created", "examples": ["2025-07-13T19:29:29.000Z"] }, "network_transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "The network transaction identifier", "examples": ["465167618285922"] }, "created_at": { "type": "string", "description": "The date when the network transaction was created", "examples": ["2025-06-16T00:00:00.000Z"] }, "card_brand": { "type": "string", "description": "The card brand used in the transaction", "examples": ["visa"] }, "amount": { "type": "number", "description": "The amount of the network transaction", "examples": [171.59] }, "currency": { "type": "string", "description": "The currency of the network transaction", "examples": ["USD"] }, "bin": { "type": "number", "description": "The Bank Identification Number", "examples": [424242] }, "last4": { "type": "number", "description": "The last four digits of the card", "examples": [720] }, "auth_code": { "type": "string", "description": "The authorization code from the transaction", "examples": ["016259"] }, "arn": { "type": "string", "description": "The Acquirer Reference Number", "examples": ["24000775168100002149105"] } }, "required": [ "id", "created_at", "card_brand", "amount", "currency", "bin", "last4", "auth_code", "arn" ], "description": "Network transaction details" }, "status_date": { "type": "string", "description": "The date when the status was last updated", "examples": ["2025-07-13T19:29:30.209Z"] }, "status": { "type": "string", "enum": ["alerted", "pending", "refund_initiated", "prevented"], "description": "The current status of the alert", "examples": ["pending"] }, "statement_descriptor": { "type": "string", "description": "The statement descriptor for the transaction", "examples": ["ELEMENTOR.COM"] }, "amount": { "type": "number", "description": "The amount associated with the alert", "examples": [171.59] }, "currency": { "type": "string", "description": "The currency of the alert amount", "examples": ["USD"] }, "outcome": { "type": ["string", "null"], "enum": [ "refunded", "previously_refunded", "duplicate", "decline", "error", "transaction_not_found", null ], "description": "The outcome of the alert, or null until the alert reaches a final outcome. Outcome can be one of the following: refunded, previously_refunded, duplicate, decline, error, transaction_not_found.", "examples": ["refunded"] }, "type": { "type": "string", "enum": ["ethoca", "cdrn", "rdr", "fraud_warning", "other"], "description": "The type of alert", "examples": ["fraud_warning"] }, "reason": { "type": "string", "enum": ["service", "fraud", "processing", "authorization"], "description": "The reason for the alert", "examples": ["fraud"] } }, "required": [ "id", "account_id", "ext_account_id", "created_at", "network_transaction", "status_date", "status", "statement_descriptor", "amount", "currency", "outcome", "type", "reason" ] } } } }, "responses": { "200": { "description": "OK" } }, "x-audience": ["merchants"] } }, "alerts.transaction.linked": { "post": { "summary": "Alert Transaction Linked Event", "description": "Fires when Chargeflow matches a pre-chargeback alert to a transaction in your payment processor. The payload carries the alert ID and the matched transaction ID.", "tags": ["Webhooks Events"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the alert", "examples": ["alert_123456789"] }, "account_id": { "type": "string", "description": "The account identifier associated with the alert", "examples": ["account_987654321"] }, "ext_account_id": { "type": "string", "description": "The external account identifier from the platform", "examples": ["platform_acc_12345"] }, "transaction_id": { "type": "string", "description": "The transaction identifier associated with the alert", "examples": ["txn_abcdef123456"] }, "created_at": { "type": "string", "description": "The date when the alert was created", "examples": ["2025-07-31T12:34:56Z"] }, "network_transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "The network transaction identifier", "examples": ["net_txn_78910"] }, "created_at": { "type": "string", "description": "The date when the network transaction was created", "examples": ["2025-07-31T12:30:00Z"] }, "amount": { "type": "number", "description": "The amount of the network transaction", "examples": [12500] }, "currency": { "type": "string", "description": "The currency of the network transaction amount", "examples": ["USD"] }, "card_brand": { "type": "string", "description": "The card brand used in the transaction", "examples": ["Visa"] }, "bin": { "type": "number", "description": "The first 6 digits of the card", "examples": [411111] }, "last4": { "type": "string", "description": "The last four digits of the card used in the transaction", "examples": ["1111"] }, "auth_code": { "type": "string", "description": "The authorization code from the transaction", "examples": ["AUTH1234"] }, "arn": { "type": "string", "description": "The Acquirer Reference Number", "examples": ["ARN56789"] } }, "description": "Network transaction details associated with the alert" }, "status_date": { "type": "string", "description": "The date when the status was last updated", "examples": ["2025-07-31T13:00:00Z"] }, "status": { "type": "string", "description": "The current status of the alert. Status can be one of the following: alerted, pending, refund_initiated, prevented.", "examples": ["alerted"] }, "statement_descriptor": { "type": "string", "description": "The statement descriptor for the transaction.", "examples": ["My Merchant Store"] }, "amount": { "type": "number", "description": "The amount associated with the alert", "examples": [12500] }, "currency": { "type": "string", "description": "The currency of the alert amount", "examples": ["USD"] }, "outcome": { "type": ["string", "null"], "description": "The outcome of the alert, or null until the alert reaches a final outcome. Outcome can be one of the following: refunded, previously_refunded, duplicate, decline, error, transaction_not_found.", "examples": ["refunded"], "enum": [ "refunded", "previously_refunded", "duplicate", "decline", "error", "transaction_not_found", null ] }, "type": { "type": "string", "description": "The type of alert. Type can be one of the following: fraud_warning, ethoca, cdrn, rdr, other.", "examples": ["fraud_warning"] }, "reason": { "type": "string", "description": "The reason for the alert. Reason can be one of the following: fraud, processing, authorization, service.", "examples": ["fraud"] }, "transactionId": { "type": "string", "description": "The id of the transaction you want to update alert with", "examples": ["txn_abcdef123456"] } }, "required": ["id", "account_id"], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK" } }, "x-audience": ["merchants"] } }, "alerts.updated": { "post": { "summary": "Alerts Outcome Updated Event", "description": "Fires when the outcome of a pre-chargeback alert changes. The payload carries the alert ID, the new outcome, and supporting metadata.", "tags": ["Webhooks Events"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the alert", "examples": ["687448f9dad73b4c91ba9e2b"] }, "account_id": { "type": "string", "description": "The account identifier associated with the alert", "examples": ["66c58917f37db4bc8d455caa"] }, "ext_account_id": { "type": ["string", "null"], "description": "The external account identifier", "examples": [null] }, "transaction": { "type": "null", "description": "The transaction object associated with the alert", "examples": [null] }, "created_at": { "type": "string", "description": "The date when the alert was created", "examples": ["2025-07-13T19:29:29.000Z"] }, "network_transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "The network transaction identifier", "examples": ["465167618285922"] }, "created_at": { "type": "string", "description": "The date when the network transaction was created", "examples": ["2025-06-16T00:00:00.000Z"] }, "card_brand": { "type": "string", "description": "The card brand used in the transaction", "examples": ["visa"] }, "amount": { "type": "number", "description": "The amount of the network transaction", "examples": [171.59] }, "currency": { "type": "string", "description": "The currency of the network transaction", "examples": ["USD"] }, "bin": { "type": "number", "description": "The Bank Identification Number", "examples": [424242] }, "last4": { "type": "number", "description": "The last four digits of the card", "examples": [720] }, "auth_code": { "type": "string", "description": "The authorization code from the transaction", "examples": ["016259"] }, "arn": { "type": "string", "description": "The Acquirer Reference Number", "examples": ["24000775168100002149105"] } }, "required": [ "id", "created_at", "card_brand", "amount", "currency", "bin", "last4", "auth_code", "arn" ], "description": "Network transaction details" }, "status_date": { "type": "string", "description": "The date when the status was last updated", "examples": ["2025-07-13T19:29:30.209Z"] }, "status": { "type": "string", "enum": ["alerted", "pending", "refund_initiated", "prevented"], "description": "The current status of the alert", "examples": ["pending"] }, "statement_descriptor": { "type": "string", "description": "The statement descriptor for the transaction", "examples": ["ELEMENTOR.COM"] }, "amount": { "type": "number", "description": "The amount associated with the alert", "examples": [171.59] }, "currency": { "type": "string", "description": "The currency of the alert amount", "examples": ["USD"] }, "outcome": { "type": ["string", "null"], "enum": [ "refunded", "previously_refunded", "duplicate", "decline", "error", "transaction_not_found", null ], "description": "The outcome of the alert, or null until the alert reaches a final outcome. Outcome can be one of the following: refunded, previously_refunded, duplicate, decline, error, transaction_not_found.", "examples": ["refunded"] }, "type": { "type": "string", "enum": ["ethoca", "cdrn", "rdr", "fraud_warning", "other"], "description": "The type of alert", "examples": ["fraud_warning"] }, "reason": { "type": "string", "enum": ["service", "fraud", "processing", "authorization"], "description": "The reason for the alert", "examples": ["fraud"] } }, "required": [ "id", "account_id", "ext_account_id", "created_at", "network_transaction", "status_date", "status", "statement_descriptor", "amount", "currency", "outcome", "type", "reason" ] } } } }, "responses": { "200": { "description": "OK" } }, "x-audience": ["merchants"] } }, "integration.access.error": { "post": { "summary": "Integration Access Error Event", "tags": ["Webhooks Events"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The webhook type", "examples": ["integration.access_error"] }, "data": { "type": "object", "properties": { "account_id": { "type": "string", "description": "The unique Chargeflow object identifier of the account.", "examples": ["acct_1234567890"] }, "integration_id": { "type": "string", "description": "The unique Chargeflow object identifier of the integration.", "examples": ["int_1234567890"] }, "error_message": { "type": "string", "description": "The error message describing the access error.", "examples": ["Access token expired or invalid."] } } }, "creationDate": { "type": "string", "format": "date-time", "description": "The creation date of the webhook in ISO8601 format", "examples": ["2021-01-01T00:00:00Z"] }, "webhookId": { "type": "string", "format": "uuid", "default": "2ce92305-2f21-4888-a09f-3256bf7c678e", "description": "The webhook id", "examples": ["123e4567-e89b-12d3-a456-426614174000"] } } } } } }, "responses": { "200": { "description": "OK" } }, "x-audience": ["platforms"] } }, "evidence.ready": { "post": { "summary": "Evidence Ready Event", "tags": ["Webhooks Events"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow object identifier", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "disputeId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow dispute identifier", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "evidenceId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow evidence identifier", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "fileUrl": { "type": "string", "description": "The URL to the generated evidence file", "examples": [ "https://cdn.chargeflow.io/evidence/ev_abc123456789/v2/evidence.pdf" ] }, "version": { "type": "number", "description": "The version number of the evidence file", "examples": [1] }, "createdAt": { "type": "string", "default": "2026-05-07T16:25:29.880Z", "description": "The timestamp when the evidence was generated" } }, "required": ["accountId", "disputeId", "evidenceId", "fileUrl", "version"] } } } }, "responses": { "200": { "description": "OK" } }, "x-audience": ["platforms"] } }, "evidence.error": { "post": { "summary": "Evidence Error Event", "tags": ["Webhooks Events"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow object identifier", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "disputeId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow dispute identifier", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "evidenceId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow evidence identifier", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "errorCode": { "type": "string", "description": "The error code indicating the type of failure", "examples": ["EVIDENCE_GENERATION_FAILED"] }, "errorMessage": { "type": "string", "description": "A descriptive message explaining the error", "examples": ["Failed to generate evidence PDF due to missing dispute data"] }, "version": { "type": "number", "description": "The version number of the evidence file", "examples": [1] }, "createdAt": { "type": "string", "default": "2026-05-07T16:25:29.880Z", "description": "The timestamp when the error occurred" } }, "required": [ "accountId", "disputeId", "evidenceId", "errorCode", "errorMessage", "version" ] } } } }, "responses": { "200": { "description": "OK" } }, "x-audience": ["platforms"] } }, "platforms/dispute.created": { "post": { "summary": "Dispute Created Event", "tags": ["Webhooks Events"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The webhook type", "examples": ["dispute.created"] }, "data": { "type": "object", "properties": { "chargeflowDisputeId": { "type": "string", "description": "The Chargeflow dispute id", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "dispute": { "type": "object", "properties": { "processorId": { "type": "string", "description": "The processor dispute id", "examples": ["PP-D-4012"] }, "processor": { "type": "string", "description": "The dispute processor", "examples": ["paypal"] }, "amount": { "type": "object", "properties": { "value": { "type": "number", "minimum": 0, "description": "The amount value", "examples": [100] }, "currency": { "type": "string", "maxLength": 10, "description": "The three-letter ISO 4217 currency code represents the currency used for the amount", "examples": ["USD"] } }, "additionalProperties": false }, "status": { "type": "string", "enum": [ "under_review", "lost", "awaiting_response", "refunded", "won", "needs_response", "appealable" ], "description": "The dispute status", "examples": ["won"] }, "reason": { "type": "string", "enum": [ "bank_cannot_process", "check_returned", "credit_not_processed", "customer_initiated", "debit_not_authorized", "duplicate", "general", "incorrect_account_details", "insufficient_funds", "product_not_received", "product_unacceptable", "not_received", "not_as_described", "subscription_canceled", "canceled", "duplicate_charge", "payment_by_other_means", "unrecognized", "incorrect_amount", "fraud", "canceled_recurring_billing", "other", "problem_with_remittance", "unauthorized" ], "description": "The processor dispute reason", "examples": ["fraud"] }, "responseDueDate": { "type": "string", "format": "date-time", "description": "The response due date in ISO8601 format", "examples": ["2021-01-01T00:00:00Z"] } } }, "transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "The transaction id", "examples": ["123e4567-e89b-12d3-a456-426614174000"] }, "creationDate": { "type": "string", "format": "date-time", "description": "The creation date of the webhook in ISO8601 format", "examples": ["2021-01-01T00:00:00Z"] }, "source": { "type": ["string", "null"], "description": "The source of the transaction", "examples": ["stripe"] }, "orderId": { "type": "string", "description": "As recieved from the payment processor, if available", "examples": ["4141404271159"] }, "customerEmail": { "type": "string", "format": "email", "description": "The customer email, as recieved from the payment processor, if available", "examples": ["john@example.com"] } } }, "vendorAccountId": { "type": "string", "description": "The vendor account id", "examples": ["55617"] }, "accountId": { "type": "string", "description": "The account id", "examples": ["67598401g210baf852j1f6dd"] } } }, "creationDate": { "type": "string", "format": "date-time", "description": "The creation date of the webhook in ISO8601 format", "examples": ["2021-01-01T00:00:00Z"] }, "webhookId": { "type": "string", "format": "uuid", "default": "e11e21e3-41ec-4c9d-9381-442cb6030ce1", "description": "The webhook id", "examples": ["123e4567-e89b-12d3-a456-426614174000"] } } } } } }, "responses": { "200": { "description": "OK" } }, "x-audience": ["platforms"] } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Your Chargeflow API key, sent on every request. Generate one in the [Chargeflow App](https://app.chargeflow.io/settings#developers), or see [API keys](/docs/reference/api-fundamentals/test-credentials)." } }, "schemas": { "BadRequestError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "invalid_request_error", "description": "The type of error", "examples": ["invalid_request_error"] }, "code": { "type": "string", "enum": ["invalid_parameter", "missing_parameter", "invalid_format"], "description": "Specific error code", "examples": ["invalid_parameter"] }, "message": { "type": "string", "enum": ["Bad Request", "Invalid request parameters"], "description": "Human-readable error message", "examples": ["Bad Request"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "Bad Request - The request contains invalid parameters or is malformed", "examples": [ { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Bad Request", "request_id": "req_abc123def456" } } ] }, "DisputeOrderLinkingForbiddenError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "permission_error", "description": "The type of error", "examples": ["permission_error"] }, "code": { "type": "string", "enum": [ "unauthorized_dispute_access", "invalid_platform_access", "shop_not_active", "dispute_not_active" ], "description": "Specific error code", "examples": ["unauthorized_dispute_access"] }, "message": { "type": "string", "enum": [ "Unauthorized access to dispute data", "Invalid platform access", "Unauthorized access", "Shop is not active", "Dispute is not active - dispute considered active if the status is not \"needs_response\" or \"warning_needs_response\"" ], "description": "Human-readable error message", "examples": ["Unauthorized access to dispute data"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "User does not have permission or the dispute/shop is not in an active state", "examples": [ { "error": { "type": "permission_error", "code": "unauthorized_dispute_access", "message": "Unauthorized access to dispute data", "request_id": "req_abc123def456" } } ] }, "ForbiddenError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "permission_error", "description": "The type of error", "examples": ["permission_error"] }, "code": { "type": "string", "enum": ["forbidden", "insufficient_permissions"], "description": "Specific error code", "examples": ["forbidden"] }, "message": { "type": "string", "enum": ["Forbidden", "You do not have permission to access this resource"], "description": "Human-readable error message", "examples": ["Forbidden"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["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", "examples": [ { "error": { "type": "permission_error", "code": "forbidden", "message": "Forbidden", "request_id": "req_abc123def456" } } ] }, "InternalServerError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "api_error", "description": "The type of error", "examples": ["api_error"] }, "code": { "type": "string", "enum": [ "internal_error", "server_error", "account_creation_failed", "account_retrieval_failed", "account_update_failed" ], "description": "Specific error code", "examples": ["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", "examples": ["Internal server error"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["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.", "examples": [ { "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error", "request_id": "req_abc123def456" } } ] }, "UnauthorizedError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "authentication_error", "description": "The type of error", "examples": ["authentication_error"] }, "code": { "type": "string", "enum": ["unauthorized", "invalid_credentials", "missing_credentials"], "description": "Specific error code", "examples": ["unauthorized"] }, "message": { "type": "string", "enum": [ "Unauthorized access", "Authentication credentials are missing or invalid" ], "description": "Human-readable error message", "examples": ["Unauthorized access"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "Unauthorized - Authentication is required or has failed", "examples": [ { "error": { "type": "authentication_error", "code": "unauthorized", "message": "Unauthorized access", "request_id": "req_abc123def456" } } ] }, "UpdateDisputeForbiddenError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "permission_error", "description": "The type of error", "examples": ["permission_error"] }, "code": { "type": "string", "enum": ["unauthorized_dispute_access", "unauthorized_resource_access"], "description": "Specific error code", "examples": ["unauthorized_dispute_access"] }, "message": { "type": "string", "enum": ["Unauthorized access to dispute data", "Unauthorized access to resource"], "description": "Human-readable error message", "examples": ["Unauthorized access to dispute data"] }, "request_id": { "type": "string", "description": "Request identifier for debugging", "examples": ["req_abc123def456"] } }, "required": ["type", "code", "message"], "description": "Error details" } }, "required": ["error"], "description": "User does not have permission to update this dispute or the dispute does not belong to the user's platform", "examples": [ { "error": { "type": "permission_error", "code": "unauthorized_dispute_access", "message": "Unauthorized access to dispute data", "request_id": "req_abc123def456" } } ] } } } }