{ "openapi": "3.1.0", "info": { "title": "Merchants API", "version": "1.0.0", "description": "The Chargeflow Merchants API enables merchants to manage disputes, upload evidence, and configure webhooks. Use this API to integrate Chargeflow's dispute management capabilities into your systems." }, "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" } ], "servers": [ { "url": "https://api.chargeflow.io", "description": "Production server" } ], "paths": { "/public/2025-04-01/alerts/{alertId}/outcome": { "post": { "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" }, "required": true, "example": "alert_123456789" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "outcome": { "type": "string", "enum": ["refunded", "previously_refunded", "duplicate", "decline", "error"] } }, "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" } } } } } } }, "/public/2025-04-01/alerts/{alertId}": { "get": { "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": "string", "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", "description": "The outcome of the alert; defaults to pending. Outcome can be one of the following: duplicate, not_found, prevented, pending, chargebacked, previously_refunded, error.", "examples": ["pending"] }, "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" } } } } } } }, "/public/2025-04-01/alerts": { "get": { "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" }, "example": "0" }, { "in": "query", "name": "limit", "schema": { "type": "string" }, "example": "10" }, { "in": "query", "name": "created_at_max", "schema": { "type": "string" } }, { "in": "query", "name": "created_at_min", "schema": { "type": "string" } }, { "in": "query", "name": "ids", "schema": { "type": "string" } }, { "in": "query", "name": "type", "schema": { "type": "string" } }, { "in": "query", "name": "status", "schema": { "type": "string" } }, { "in": "query", "name": "reason", "schema": { "type": "string" } }, { "in": "query", "name": "sort", "schema": { "type": "string" } } ], "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": "string", "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", "description": "The outcome of the alert; defaults to pending. Outcome can be one of the following: duplicate, not_found, prevented, pending, chargebacked, previously_refunded, error.", "examples": ["pending"] }, "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 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 } ] } } } } } }, "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" } } } } } } }, "/public/2025-04-01/customer-communication": { "post": { "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" } } } } } } }, "/public/2025-04-01/disputes/{disputeId}/evidence": { "post": { "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" ] } } } } } } }, "/public/2025-04-01/disputes/{disputeId}": { "get": { "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" } } } } } }, "patch": { "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" } } } } } } }, "/public/2025-04-01/disputes/{disputeId}/subscription": { "post": { "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" } } } } } } }, "/public/2025-04-01/disputes": { "get": { "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" } } } } } } }, "/public/2025-04-01/health-check/access-key": { "get": { "tags": ["Health Check"], "summary": "Validate Access Key", "description": "Confirms your API key is valid and authorized to call the Chargeflow API.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/public/2025-04-01/health-check": { "get": { "tags": ["Health Check"], "summary": "Service Health Verification", "description": "Confirms the Chargeflow API is reachable and responding. Use it as a connectivity check before you start integrating.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string", "description": "OK" } } } } } } }, "/public/2025-04-01/webhooks": { "get": { "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"] } } } } } }, "post": { "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"] } } } } } } }, "/public/2025-04-01/webhooks/{id}": { "delete": { "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"] } } } } } } }, "/public/2025-04-01/data-subject/removal": { "post": { "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" } } } } } } }, "/public/2025-04-01/data-subject/removal/{requestId}": { "get": { "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" } } } } } } } }, "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" } } } }, "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": [443603] }, "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", "enum": [ "duplicate", "not_found", "prevented", "pending", "chargebacked", "previously_refunded", "error" ], "description": "The outcome of the alert", "examples": ["pending"] }, "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" } } } }, "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": "string", "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", "description": "The outcome of the alert. Outcome can be one of the following: duplicate, not_found, prevented, pending, chargebacked, previously_refunded, error.", "examples": ["pending"] }, "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" } } } }, "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": [443603] }, "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", "enum": [ "duplicate", "not_found", "prevented", "pending", "chargebacked", "previously_refunded", "error" ], "description": "The outcome of the alert", "examples": ["pending"] }, "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" } } } } }, "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" } } ] } } } }