{ "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": "Subscription", "description": "Subscription 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": "Transaction" }, { "name": "User Event Log" }, { "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": "The **Update Alert Outcome** endpoint allows merchants and platforms who manage refunds themselves to notify Chargeflow of the final outcome for a given alert. Updating the outcome ensures Chargeflow can report back to the alert provider (Verifi & Ethoca) and prevent escalation to a chargeback.\n\nThis endpoint is only required if you are using the **Merchant-Managed Handling** integration model. In this case, it is crucial to report back the outcomes of **CDRN** and **Ethoca** alerts. If such cases are resolved by issuing refunds but the outcomes are not reported, they may still escalate into chargebacks.\n\n## **Important Notes**\n\n- You are only required to update outcomes for alerts of type `cdrn` and `ethoca`. Updating these outcomes is **mandatory** in Merchant-Managed Handling.\n- `tc40` alerts are automatically marked as `\"acknowledged\"` and do not require an update.\n- `rdr` alerts are automatically refunded and therefore do not require an outcome update.\n- Outcomes may only be updated for alerts with a **non-final outcome** (`null` or `pending`). You can check the current outcome using the **Get Alert by Id** (`GET /alerts/{id}`) endpoint.\n- Once submitted, the outcome is final and cannot be changed. Any duplicate submission for the same alert will result in an error.\n- You can only update outcomes for alerts associated with your own Chargeflow account.\n\n## **Allowed Outcome Values**\n\n| Outcome | Description |\n|---------|-------------|\n| `refunded` | The transaction was refunded successfully. |\n| `transaction_not_found` | No matching transaction could be found to process a refund. |\n| `previously_refunded` | The transaction was already refunded before the alert. |\n| `duplicate` | The alert was identified as a duplicate of a previous alert. |\n| `decline` | The refund request was declined, no refund was issued. |\n| `error` | A general error occurred (e.g., insufficient funds, invalid card, other). |", "parameters": [ { "in": "path", "name": "alertId", "schema": { "type": "string" }, "required": true } ], "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", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "missing_alert_id", "missing_outcome" ], "description": "Specific error code", "example": "missing_alert_id" }, "message": { "type": "string", "enum": [ "Alert ID is required", "Outcome is required" ], "description": "Human-readable error message", "example": "Alert ID is required" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Required parameters are missing or invalid", "example": { "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", "example": "authentication_error" }, "code": { "type": "string", "enum": [ "unauthorized", "invalid_credentials", "missing_credentials" ], "description": "Specific error code", "example": "unauthorized" }, "message": { "type": "string", "enum": [ "Unauthorized access", "Authentication credentials are missing or invalid" ], "description": "Human-readable error message", "example": "Unauthorized access" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Unauthorized - Authentication is required or has failed", "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "Unauthorized access", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "UnauthorizedError" } } } }, "403": { "description": "Forbidden - 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", "example": "permission_error" }, "code": { "type": "string", "enum": [ "unauthorized_alert_access" ], "description": "Specific error code", "example": "unauthorized_alert_access" }, "message": { "type": "string", "enum": [ "Unauthorized access to alert data" ], "description": "Human-readable error message", "example": "Unauthorized access to alert data" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "The authenticated user does not have permission to update this alert", "example": { "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", "example": "api_error" }, "code": { "type": "string", "enum": [ "internal_error", "server_error", "account_creation_failed", "account_retrieval_failed", "account_update_failed" ], "description": "Specific error code", "example": "internal_error" }, "message": { "type": "string", "enum": [ "Internal server error", "An unexpected error occurred", "Failed to create account", "Failed to get accounts", "Failed to update account" ], "description": "Human-readable error message", "example": "Internal server error" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Internal Server Error - Something went wrong on our end. Please try again later.", "example": { "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "InternalServerError" } } } } } } }, "/public/2025-04-01/alerts/{alertId}": { "get": { "tags": [ "Alerts" ], "summary": "Get Alert By ID", "description": "The **Get Alert by ID** endpoint is available exclusively for Chargeflow Alerts customers. It allows you to retrieve detailed information about a specific pre-chargeback alert using its unique identifier. When you call this endpoint, you'll receive the full alert object, including its status, type, linked transaction, reason, and any other available metadata.\n\nUse this endpoint when you already have an alert ID (e.g. from the list endpoint or webhook) and need to access its complete record.", "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.", "example": "alert_123456789" }, "required": true } ], "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.", "example": "alert_123456789" }, "account_id": { "type": "string", "description": "The unique Chargeflow account identifier to which the alert belongs.", "example": "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.", "example": "platform_acc_12345" }, "transaction": { "anyOf": [ { "type": "string", "description": "The unique Chargeflow identifier of the transaction to which the alert is linked.", "example": "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.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The transaction ID from the source.", "example": "tx_1234567890" }, { "type": "null" } ], "description": "The transaction ID associated with the dispute. Can be a Chargeflow transaction identifier or a transaction identifier from the source.", "example": "tx_1234567890" }, "source_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique transaction identifier appears on the source from which the transaction originated.", "example": "tx_1234567890" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the transaction belongs.", "example": "66e6ea9ecd94925a9f8060d8" }, "ext_account_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique account identifier appears on the platform. Null if not set by the platform.", "example": "acc_123456" }, "order_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "example": "ord_1234567890" }, { "type": "null" } ], "description": "The order ID associated with the dispute. Can be a Chargeflow order identifier or an order identifier from the source.", "example": "ord_1234567890" }, "subscription_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow subscription ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The subscription ID from the source.", "example": "sub_1234567890" }, { "type": "null" } ], "description": "The subscription ID associated with the dispute. Can be a Chargeflow subscription identifier or a subscription identifier from the source.", "example": "66e6ea9ecd94925a9f8060d9" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the transaction was created at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "type": { "type": [ "string", "null" ], "enum": [ "paid", "partially_paid", "refunded", "partially_refunded" ], "description": "The type of the transaction", "example": "paid" }, "amount": { "type": [ "number", "null" ], "minimum": 0, "description": "Transaction total amount after all deductions.", "example": 100 }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "payment_method": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The full name of the person to which the payment method belongs to.", "example": "John Doe" }, "type": { "type": [ "string", "null" ], "enum": [ "card", "wallet" ], "description": "The type of the payment method", "example": "card" }, "last4": { "type": [ "string", "null" ], "pattern": "^\\d{4}$", "minLength": 4, "maxLength": 4, "description": "The last four digits of the card used for the transaction. `card`", "example": "1234" }, "expiry_month": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 12, "description": "The month when the card used for the transaction is expired. `card`", "example": 1 }, "expiry_year": { "type": [ "integer", "null" ], "minimum": 2019, "maximum": 2100, "description": "The year when the card used for the transaction is expired. `card`", "example": 2025 }, "brand": { "type": [ "string", "null" ], "enum": [ "visa", "mastercard", "discover", "amex", "jcb", "unionpay", "diners", "other" ], "description": "The card brand used for the transaction. `card`", "example": "visa" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "The card issuance country - two-letter country code (ISO 3166-1 alpha-2). `card`", "example": "US" }, "wallet": { "type": [ "string", "null" ], "enum": [ "paypal", "klarna", "affirm", "afterpay", "sezzle", "zip", "venmo", "apple", "other" ], "description": "The name of the wallet which used for the transaction. `wallet`", "example": "paypal" }, "checks": { "type": "object", "properties": { "three_d_secure_result": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The 3D secure authentication outcome. `card`", "example": "passed" }, "avs_results": { "type": [ "string", "null" ], "enum": [ "N", "A", "Y", "Z" ], "description": "The address verification system outcome. `card`", "example": "N" }, "address_line1_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The address line1 check result. `card`", "example": "passed" }, "address_zip_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The address zip or postal code check result. `card`", "example": "passed" }, "cvc_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The card verification code result. `card`", "example": "passed" } }, "description": "The checks performed by the network at the time of payment. `card`" }, "wallet_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 128, "description": "The email address of the wallet which used for the transaction. `wallet`", "example": "john.doe@example.com" }, "wallet_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The wallet unique identifier which used for the transaction. `wallet`", "example": "1234567890" } }, "description": "The payment method used for the transaction.", "example": { "type": "card", "name": "John Doe", "last4": "1234", "expiry_month": 1, "expiry_year": 2025, "brand": "visa" } }, "billing_address": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The name of the person associated with the billing address.", "example": "John Doe" }, "line1": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "example": "123 Main St" }, "line2": { "type": [ "string", "null" ], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "example": "Apt 1" }, "city": { "type": [ "string", "null" ], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "example": "San Francisco" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Two-letter country code (ISO 3166-1 alpha-2) associated with the address lines", "example": "US" }, "state": { "type": [ "string", "null" ], "description": "State, county, province, or region associated with the address lines.", "example": "CA" }, "zip_code": { "type": [ "string", "null" ], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "example": "12345" }, "phone": { "type": [ "string", "null" ], "description": "The phone number of the person associated with the billing address.", "example": "1(123)4567890" } }, "description": "The billing address associated with the payment method at the time of the transaction.", "example": { "name": "John Doe", "line1": "123 Main St", "line2": "Apt 1", "city": "Anytown", "state": "NY", "zip_code": "12345", "country": "US", "phone": "+1234567890" } } }, "description": "A transaction represents a money exchange between a buyer and a merchant in return for a physical product, digital product, service, booking, or other goods and offerings." } ], "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.", "example": "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.", "example": "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.", "example": "2025-07-31T12:30:00Z" }, "amount": { "type": "number", "minimum": 0, "description": "The total amount of the transaction.", "example": 12500 }, "currency": { "type": "string", "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "card_brand": { "type": "string", "description": "The card brand used for the transaction", "example": "Visa" }, "bin": { "type": "string", "description": "The first 6 to 8 digits of the card number, identifying the issuing bank and card type.", "example": "411111" }, "last4": { "type": "string", "description": "The last four digits of the card number, used for reference and display.", "example": "1111" }, "auth_code": { "type": "string", "description": "The unique identifier issued by the issuer bank to confirm approval of a payment transaction.", "example": "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.", "example": "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.", "example": "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.", "example": "refund_initiated" }, "statement_descriptor": { "type": "string", "description": "The descriptor of the merchant to which the alert belongs.", "example": "My Merchant Store" }, "amount": { "type": "number", "minimum": 0, "description": "Alert total amount.", "example": 12500 }, "currency": { "type": "string", "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "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.", "example": "pending" }, "type": { "type": "string", "description": "The type of the alert. Type can be one of the following: fraud_warning, ethoca, cdrn, rdr, other.", "example": "fraud_warning" }, "reason": { "type": "string", "description": "The reason for the alert. Reason can be one of the following: fraud, processing, authorization, service.", "example": "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", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "missing_alert_id" ], "description": "Specific error code", "example": "missing_alert_id" }, "message": { "type": "string", "enum": [ "Alert ID is required" ], "description": "Human-readable error message", "example": "Alert ID is required" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Alert ID parameter is missing or invalid", "example": { "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", "example": "authentication_error" }, "code": { "type": "string", "enum": [ "unauthorized", "invalid_credentials", "missing_credentials" ], "description": "Specific error code", "example": "unauthorized" }, "message": { "type": "string", "enum": [ "Unauthorized access", "Authentication credentials are missing or invalid" ], "description": "Human-readable error message", "example": "Unauthorized access" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Unauthorized - Authentication is required or has failed", "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "Unauthorized access", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "UnauthorizedError" } } } }, "403": { "description": "Forbidden - 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", "example": "permission_error" }, "code": { "type": "string", "enum": [ "unauthorized_alert_access", "unauthorized_resource_access" ], "description": "Specific error code", "example": "unauthorized_alert_access" }, "message": { "type": "string", "enum": [ "Unauthorized access to alert data", "Unauthorized access to resource" ], "description": "Human-readable error message", "example": "Unauthorized access to alert data" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "The authenticated user does not have permission to access this alert", "example": { "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", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "alert_not_found" ], "description": "Specific error code", "example": "alert_not_found" }, "message": { "type": "string", "enum": [ "Alert not found" ], "description": "Human-readable error message", "example": "Alert not found" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "The requested alert does not exist", "example": { "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", "example": "api_error" }, "code": { "type": "string", "enum": [ "internal_error", "server_error", "account_creation_failed", "account_retrieval_failed", "account_update_failed" ], "description": "Specific error code", "example": "internal_error" }, "message": { "type": "string", "enum": [ "Internal server error", "An unexpected error occurred", "Failed to create account", "Failed to get accounts", "Failed to update account" ], "description": "Human-readable error message", "example": "Internal server error" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Internal Server Error - Something went wrong on our end. Please try again later.", "example": { "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "InternalServerError" } } } } } } }, "/public/2025-04-01/alerts": { "get": { "tags": [ "Alerts" ], "summary": "Get Alerts", "description": "The **Get Alerts** endpoint is available exclusively for Chargeflow Alerts customers. It provides real-time visibility into potential chargeback events before they escalate into full disputes.\n\nWhen you call this endpoint, you'll receive all pre-chargeback alerts associated with your account, including their status, type, linked transaction, and other relevant details.\n\nMerchants can use this endpoint to:\n* **Proactively respond** to disputes before they become chargebacks.\n* **Automate refund or cancellation flows** to minimize financial loss and avoid chargeback fees.\n* **Monitor risk trends** across transactions to identify recurring fraud or operational issues.\n\nThe endpoint returns a **paginated list of alerts**. You can apply filters (by date, type, status, or reason) and use sorting functionality to refine the results.", "parameters": [ { "in": "query", "name": "offset", "schema": { "type": "string" } }, { "in": "query", "name": "limit", "schema": { "type": "string" } }, { "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.", "example": "alert_123456789" }, "account_id": { "type": "string", "description": "The unique Chargeflow account identifier to which the alert belongs.", "example": "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.", "example": "platform_acc_12345" }, "transaction": { "anyOf": [ { "type": "string", "description": "The unique Chargeflow identifier of the transaction to which the alert is linked.", "example": "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.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The transaction ID from the source.", "example": "tx_1234567890" }, { "type": "null" } ], "description": "The transaction ID associated with the dispute. Can be a Chargeflow transaction identifier or a transaction identifier from the source.", "example": "tx_1234567890" }, "source_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique transaction identifier appears on the source from which the transaction originated.", "example": "tx_1234567890" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the transaction belongs.", "example": "66e6ea9ecd94925a9f8060d8" }, "ext_account_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique account identifier appears on the platform. Null if not set by the platform.", "example": "acc_123456" }, "order_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "example": "ord_1234567890" }, { "type": "null" } ], "description": "The order ID associated with the dispute. Can be a Chargeflow order identifier or an order identifier from the source.", "example": "ord_1234567890" }, "subscription_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow subscription ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The subscription ID from the source.", "example": "sub_1234567890" }, { "type": "null" } ], "description": "The subscription ID associated with the dispute. Can be a Chargeflow subscription identifier or a subscription identifier from the source.", "example": "66e6ea9ecd94925a9f8060d9" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the transaction was created at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "type": { "type": [ "string", "null" ], "enum": [ "paid", "partially_paid", "refunded", "partially_refunded" ], "description": "The type of the transaction", "example": "paid" }, "amount": { "type": [ "number", "null" ], "minimum": 0, "description": "Transaction total amount after all deductions.", "example": 100 }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "payment_method": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The full name of the person to which the payment method belongs to.", "example": "John Doe" }, "type": { "type": [ "string", "null" ], "enum": [ "card", "wallet" ], "description": "The type of the payment method", "example": "card" }, "last4": { "type": [ "string", "null" ], "pattern": "^\\d{4}$", "minLength": 4, "maxLength": 4, "description": "The last four digits of the card used for the transaction. `card`", "example": "1234" }, "expiry_month": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 12, "description": "The month when the card used for the transaction is expired. `card`", "example": 1 }, "expiry_year": { "type": [ "integer", "null" ], "minimum": 2019, "maximum": 2100, "description": "The year when the card used for the transaction is expired. `card`", "example": 2025 }, "brand": { "type": [ "string", "null" ], "enum": [ "visa", "mastercard", "discover", "amex", "jcb", "unionpay", "diners", "other" ], "description": "The card brand used for the transaction. `card`", "example": "visa" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "The card issuance country - two-letter country code (ISO 3166-1 alpha-2). `card`", "example": "US" }, "wallet": { "type": [ "string", "null" ], "enum": [ "paypal", "klarna", "affirm", "afterpay", "sezzle", "zip", "venmo", "apple", "other" ], "description": "The name of the wallet which used for the transaction. `wallet`", "example": "paypal" }, "checks": { "type": "object", "properties": { "three_d_secure_result": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The 3D secure authentication outcome. `card`", "example": "passed" }, "avs_results": { "type": [ "string", "null" ], "enum": [ "N", "A", "Y", "Z" ], "description": "The address verification system outcome. `card`", "example": "N" }, "address_line1_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The address line1 check result. `card`", "example": "passed" }, "address_zip_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The address zip or postal code check result. `card`", "example": "passed" }, "cvc_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The card verification code result. `card`", "example": "passed" } }, "description": "The checks performed by the network at the time of payment. `card`" }, "wallet_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 128, "description": "The email address of the wallet which used for the transaction. `wallet`", "example": "john.doe@example.com" }, "wallet_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The wallet unique identifier which used for the transaction. `wallet`", "example": "1234567890" } }, "description": "The payment method used for the transaction.", "example": { "type": "card", "name": "John Doe", "last4": "1234", "expiry_month": 1, "expiry_year": 2025, "brand": "visa" } }, "billing_address": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The name of the person associated with the billing address.", "example": "John Doe" }, "line1": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "example": "123 Main St" }, "line2": { "type": [ "string", "null" ], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "example": "Apt 1" }, "city": { "type": [ "string", "null" ], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "example": "San Francisco" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Two-letter country code (ISO 3166-1 alpha-2) associated with the address lines", "example": "US" }, "state": { "type": [ "string", "null" ], "description": "State, county, province, or region associated with the address lines.", "example": "CA" }, "zip_code": { "type": [ "string", "null" ], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "example": "12345" }, "phone": { "type": [ "string", "null" ], "description": "The phone number of the person associated with the billing address.", "example": "1(123)4567890" } }, "description": "The billing address associated with the payment method at the time of the transaction.", "example": { "name": "John Doe", "line1": "123 Main St", "line2": "Apt 1", "city": "Anytown", "state": "NY", "zip_code": "12345", "country": "US", "phone": "+1234567890" } } }, "description": "A transaction represents a money exchange between a buyer and a merchant in return for a physical product, digital product, service, booking, or other goods and offerings." } ], "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.", "example": "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.", "example": "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.", "example": "2025-07-31T12:30:00Z" }, "amount": { "type": "number", "minimum": 0, "description": "The total amount of the transaction.", "example": 12500 }, "currency": { "type": "string", "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "card_brand": { "type": "string", "description": "The card brand used for the transaction", "example": "Visa" }, "bin": { "type": "string", "description": "The first 6 to 8 digits of the card number, identifying the issuing bank and card type.", "example": "411111" }, "last4": { "type": "string", "description": "The last four digits of the card number, used for reference and display.", "example": "1111" }, "auth_code": { "type": "string", "description": "The unique identifier issued by the issuer bank to confirm approval of a payment transaction.", "example": "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.", "example": "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.", "example": "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.", "example": "refund_initiated" }, "statement_descriptor": { "type": "string", "description": "The descriptor of the merchant to which the alert belongs.", "example": "My Merchant Store" }, "amount": { "type": "number", "minimum": 0, "description": "Alert total amount.", "example": 12500 }, "currency": { "type": "string", "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "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.", "example": "pending" }, "type": { "type": "string", "description": "The type of the alert. Type can be one of the following: fraud_warning, ethoca, cdrn, rdr, other.", "example": "fraud_warning" }, "reason": { "type": "string", "description": "The reason for the alert. Reason can be one of the following: fraud, processing, authorization, service.", "example": "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", "example": 100 }, "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "The page number of the current response", "example": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "The number of disputes per page", "example": 25 }, "totalPages": { "type": "integer", "minimum": 0, "description": "Total number of pages available in the database", "example": 54 } }, "description": "Pagination information for the current response", "example": { "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", "example": "authentication_error" }, "code": { "type": "string", "enum": [ "unauthorized", "invalid_credentials", "missing_credentials" ], "description": "Specific error code", "example": "unauthorized" }, "message": { "type": "string", "enum": [ "Unauthorized access", "Authentication credentials are missing or invalid" ], "description": "Human-readable error message", "example": "Unauthorized access" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Unauthorized - Authentication is required or has failed", "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "Unauthorized access", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "UnauthorizedError" } } } }, "403": { "description": "Forbidden - 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", "example": "permission_error" }, "code": { "type": "string", "enum": [ "unauthorized_alert_access" ], "description": "Specific error code", "example": "unauthorized_alert_access" }, "message": { "type": "string", "enum": [ "Unauthorized access to alert data" ], "description": "Human-readable error message", "example": "Unauthorized access to alert data" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "The authenticated user does not have permission to access these alerts", "example": { "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", "example": "api_error" }, "code": { "type": "string", "enum": [ "internal_error", "server_error", "account_creation_failed", "account_retrieval_failed", "account_update_failed" ], "description": "Specific error code", "example": "internal_error" }, "message": { "type": "string", "enum": [ "Internal server error", "An unexpected error occurred", "Failed to create account", "Failed to get accounts", "Failed to update account" ], "description": "Human-readable error message", "example": "Internal server error" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Internal Server Error - Something went wrong on our end. Please try again later.", "example": { "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "InternalServerError" } } } } } } }, "/public/2025-04-01/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.", "example": "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)", "example": "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.", "example": [ "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.", "example": "email" }, "sender": { "anyOf": [ { "type": "string", "format": "email", "example": "customer.support@example.com" }, { "type": "string", "enum": [ "buyer", "merchant" ], "example": "buyer" } ], "description": "The email address or the role of the sender; possible values are either a valid email address or buyer, merchant.", "example": "buyer" }, "date": { "type": "string", "format": "date-time", "description": "The time at which the message was created at the source in ISO 8601 format.", "example": "2025-09-10T14:25:36Z" }, "subject": { "type": "string", "maxLength": 100, "description": "The subject of the message; limited to 100 characters.", "example": "Where is my order?" }, "body_plain_text": { "type": "string", "description": "The message body in a plain text.", "example": "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.", "example": 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", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_request_body", "missing_account_id", "missing_disputes", "missing_messages", "dispute_not_found" ], "description": "Specific error code", "example": "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", "example": "Invalid request body" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "The request contains invalid parameters or is missing required fields", "example": { "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", "example": "authentication_error" }, "code": { "type": "string", "enum": [ "unauthorized", "invalid_credentials", "missing_credentials" ], "description": "Specific error code", "example": "unauthorized" }, "message": { "type": "string", "enum": [ "Unauthorized access", "Authentication credentials are missing or invalid" ], "description": "Human-readable error message", "example": "Unauthorized access" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Unauthorized - Authentication is required or has failed", "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "Unauthorized access", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "UnauthorizedError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "permission_error", "description": "The type of error", "example": "permission_error" }, "code": { "type": "string", "enum": [ "forbidden", "invalid_platform_access", "unauthorized_dispute_access" ], "description": "Specific error code", "example": "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", "example": "Forbidden" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "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", "example": { "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", "example": "api_error" }, "code": { "type": "string", "enum": [ "internal_error", "server_error", "account_creation_failed", "account_retrieval_failed", "account_update_failed" ], "description": "Specific error code", "example": "internal_error" }, "message": { "type": "string", "enum": [ "Internal server error", "An unexpected error occurred", "Failed to create account", "Failed to get accounts", "Failed to update account" ], "description": "Human-readable error message", "example": "Internal server error" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Internal Server Error - Something went wrong on our end. Please try again later.", "example": { "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "InternalServerError" } } } } } } }, "/public/2025-04-01/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.", "example": "66e6ea9ecd94925a9f8060d9" }, "required": true } ], "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", "example": "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", "example": "additional_evidence" }, "content": { "type": "string", "description": "The content of the evidence. Only required with `additional_notes` and `additional_evidence` categories", "example": "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": "Retrieve a single dispute details with the option to `expand` it with enriched data using the `expand` request 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.", "example": "66e6ea9ecd94925a9f8060d9" }, "required": true }, { "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", "example": [ "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.", "example": "66e6ea9ecd94925a9f8060d9" }, "source": { "type": [ "string", "null" ], "enum": [ "paypal", "shopify", "maverick", "businessTrack", "cpanel", "globalPayments", "merlink", "braintree", "klarna", "square", "afterpay", "oceanpayment", "payarc", "firstview", "nexio", "elevate", "stripe", "goatPayments", "woopay", "nuvei", "safecharge", "zenPayments", "select", "checkout", "deposyt", "affirm", "adyen", "asana", "import", "import/induced", "samcart", "easyPayDirect", "paysafe", "bravapay", "micamp", "approvely", "platpay", "clover", "airwallex", "worldpay", "sezzle", "luqra", "paymentTech", "paymentsAI", "mamopay", "emsdata", "paymentsHub", "publicApi", "nmi", "wepay", "zippay", "paymentInsider", "trxServices", "merchantic", "wooPayments", "wooCommerce", "swipeSimple", "gmail", "zohoPayments", "recharge", "trustpay", "wixPayments", "venmo", "skrill", "blogicSystems", "useePay", "thinkific", "revolut", "kajabi", "tiktok", "authorizeNet", "nabankco", "finix", "zendesk", "gorgias", "cloudbeds", "swipearas", "amazonPay", "incheck", "platform", "ebanx", "kurvpay" ], "description": "The source of the dispute. name of the PSP", "example": "stripe" }, "source_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique dispute identifier appears on the source (processor) from which the dispute originated.", "example": "du_123456789" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the dispute belongs.", "example": "66e6ea9ecd94925a9f8060d9" }, "ext_account_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique account identifier appears on the platform. Null if not set by the platform.", "example": "acc_123456" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the dispute was created in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "reason": { "type": [ "string", "null" ], "enum": [ "fraud", "not_received", "not_as_described", "canceled_recurring_billing", "duplicate_charge", "credit_not_processed", "other" ], "description": "The reason the cardholder has disputed the transaction.", "example": "fraud" }, "due_by": { "type": [ "string", "null" ], "format": "date-time", "description": "The deadline to submit evidence to challenge the dispute in ISO 8601 format.", "example": "2024-02-20T12:00:00Z" }, "amount": { "type": [ "number", "null" ], "minimum": 0, "description": "Disputed amount. Equal to or less than the disputed transaction amount.", "example": 100 }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "status": { "type": [ "string", "null" ], "enum": [ "needs_response", "under_review", "won", "lost" ], "description": "The current status of the dispute.", "example": "needs_response" }, "stage": { "type": [ "string", "null" ], "enum": [ "Chargeback", "Inquiry", "Pre_arbitration", "Arbitration" ], "description": "The stage of the dispute.", "example": "Chargeback" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the dispute has been closed and resolved in ISO 8601 format. Returns null if the dispute is not yet closed.", "example": "2025-01-27T10:00:00Z" }, "transaction": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow transaction ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The transaction ID from the source.", "example": "tx_1234567890" } ], "description": "The transaction ID associated with the dispute. Can be a Chargeflow transaction identifier or a transaction identifier from the source.", "example": "tx_1234567890" }, { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow transaction ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The transaction ID from the source.", "example": "tx_1234567890" }, { "type": "null" } ], "description": "The transaction ID associated with the dispute. Can be a Chargeflow transaction identifier or a transaction identifier from the source.", "example": "tx_1234567890" }, "source_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique transaction identifier appears on the source from which the transaction originated.", "example": "tx_1234567890" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the transaction belongs.", "example": "66e6ea9ecd94925a9f8060d8" }, "ext_account_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique account identifier appears on the platform. Null if not set by the platform.", "example": "acc_123456" }, "order_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "example": "ord_1234567890" }, { "type": "null" } ], "description": "The order ID associated with the dispute. Can be a Chargeflow order identifier or an order identifier from the source.", "example": "ord_1234567890" }, "subscription_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow subscription ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The subscription ID from the source.", "example": "sub_1234567890" }, { "type": "null" } ], "description": "The subscription ID associated with the dispute. Can be a Chargeflow subscription identifier or a subscription identifier from the source.", "example": "66e6ea9ecd94925a9f8060d9" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the transaction was created at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "type": { "type": [ "string", "null" ], "enum": [ "paid", "partially_paid", "refunded", "partially_refunded" ], "description": "The type of the transaction", "example": "paid" }, "amount": { "type": [ "number", "null" ], "minimum": 0, "description": "Transaction total amount after all deductions.", "example": 100 }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "payment_method": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The full name of the person to which the payment method belongs to.", "example": "John Doe" }, "type": { "type": [ "string", "null" ], "enum": [ "card", "wallet" ], "description": "The type of the payment method", "example": "card" }, "last4": { "type": [ "string", "null" ], "pattern": "^\\d{4}$", "minLength": 4, "maxLength": 4, "description": "The last four digits of the card used for the transaction. `card`", "example": "1234" }, "expiry_month": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 12, "description": "The month when the card used for the transaction is expired. `card`", "example": 1 }, "expiry_year": { "type": [ "integer", "null" ], "minimum": 2019, "maximum": 2100, "description": "The year when the card used for the transaction is expired. `card`", "example": 2025 }, "brand": { "type": [ "string", "null" ], "enum": [ "visa", "mastercard", "discover", "amex", "jcb", "unionpay", "diners", "other" ], "description": "The card brand used for the transaction. `card`", "example": "visa" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "The card issuance country - two-letter country code (ISO 3166-1 alpha-2). `card`", "example": "US" }, "wallet": { "type": [ "string", "null" ], "enum": [ "paypal", "klarna", "affirm", "afterpay", "sezzle", "zip", "venmo", "apple", "other" ], "description": "The name of the wallet which used for the transaction. `wallet`", "example": "paypal" }, "checks": { "type": "object", "properties": { "three_d_secure_result": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The 3D secure authentication outcome. `card`", "example": "passed" }, "avs_results": { "type": [ "string", "null" ], "enum": [ "N", "A", "Y", "Z" ], "description": "The address verification system outcome. `card`", "example": "N" }, "address_line1_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The address line1 check result. `card`", "example": "passed" }, "address_zip_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The address zip or postal code check result. `card`", "example": "passed" }, "cvc_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The card verification code result. `card`", "example": "passed" } }, "description": "The checks performed by the network at the time of payment. `card`" }, "wallet_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 128, "description": "The email address of the wallet which used for the transaction. `wallet`", "example": "john.doe@example.com" }, "wallet_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The wallet unique identifier which used for the transaction. `wallet`", "example": "1234567890" } }, "description": "The payment method used for the transaction.", "example": { "type": "card", "name": "John Doe", "last4": "1234", "expiry_month": 1, "expiry_year": 2025, "brand": "visa" } }, "billing_address": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The name of the person associated with the billing address.", "example": "John Doe" }, "line1": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "example": "123 Main St" }, "line2": { "type": [ "string", "null" ], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "example": "Apt 1" }, "city": { "type": [ "string", "null" ], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "example": "San Francisco" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Two-letter country code (ISO 3166-1 alpha-2) associated with the address lines", "example": "US" }, "state": { "type": [ "string", "null" ], "description": "State, county, province, or region associated with the address lines.", "example": "CA" }, "zip_code": { "type": [ "string", "null" ], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "example": "12345" }, "phone": { "type": [ "string", "null" ], "description": "The phone number of the person associated with the billing address.", "example": "1(123)4567890" } }, "description": "The billing address associated with the payment method at the time of the transaction.", "example": { "name": "John Doe", "line1": "123 Main St", "line2": "Apt 1", "city": "Anytown", "state": "NY", "zip_code": "12345", "country": "US", "phone": "+1234567890" } } }, "description": "A transaction represents a money exchange between a buyer and a merchant in return for a physical product, digital product, service, booking, or other goods and offerings." }, { "type": "null" } ], "description": "The unique `Chargeflow` transaction identifier or the data of the transaction.", "example": "66e6ea9ecd94925a9f8060d9" }, "subscription": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The subscription ID associated with the dispute. Can be a Chargeflow subscription identifier or a subscription identifier from the source.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The subscription ID associated with the dispute. Can be a Chargeflow subscription identifier or a subscription identifier from the source.", "example": "66e6ea9ecd94925a9f8060d9" }, "source_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique subscription identifier appears on the source from which the subscription originated.", "example": "source_sub_1234567890" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the subscription belongs.", "example": "66e6ea9ecd94925a9f8060d9" }, "ext_account_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique account identifier appears on the platform. Null if not set by the platform.", "example": "acc_123456" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was created at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was updated at the source in ISO 8601 format.", "example": "2024-02-15T12:00:00Z" }, "start_date": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was started at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "end_date": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was ended at the source in ISO 8601 format.", "example": "2024-08-10T12:00:00Z" }, "cancellation_date": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was requested to be canceled at the source in ISO 8601 format. Returns null if a cancellation is never requested.", "example": "2024-07-10T12:00:00Z" }, "frequency": { "type": [ "string", "null" ], "enum": [ "day", "week", "month", "year" ], "description": "The frequency at which a subscription is billed.", "example": "month" }, "frequency_count": { "type": [ "integer", "null" ], "minimum": 1, "description": "The number of intervals per billing cycle. For example, if frequency = month and frequency_count = 1, the subscription renews every month. If frequency_count = 3, the subscription renews every three months.", "example": 1 }, "cancellation_reason": { "type": [ "string", "null" ], "enum": [ "too_expensive", "low_quality", "unused", "too_complex", "missing_features" ], "description": "The submitted reason for why the subscription has canceled.", "example": "too_expensive" }, "collection_method": { "type": [ "string", "null" ], "enum": [ "automatically", "automatically_with_reminder", "send_invoice" ], "description": "The billing method for the subscription.", "example": "automatically" }, "trial_start": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the trial of the subscription began at the source in ISO 8601 format. Returns null if no trial is offered or if the trial was not utilized.", "example": "2024-02-10T12:00:00Z" }, "trial_end": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the trial of the subscription ended at the source in ISO 8601 format. Returns null if no trial is offered or if the trial was not utilized.", "example": "2024-03-10T12:00:00Z" }, "renews_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription cycle renews at the source in ISO 8601 format. Returns null if the subscription has been canceled.", "example": "2024-03-10T12:00:00Z" }, "plan_name": { "type": [ "string", "null" ], "description": "The name of the plan associated with the subscription, representing the specific offering or service tier the subscriber is enrolled in.", "example": "Pro Plan" }, "pricing_model": { "type": [ "string", "null" ], "enum": [ "fixed_price", "usage_base" ], "description": "The pricing model associated with the subscription.", "example": "fixed_price" }, "status": { "type": [ "string", "null" ], "enum": [ "active", "inactive", "canceled" ], "description": "The current status of the subscription.", "example": "active" } }, "description": "A subscription represents a recurring payment between a buyer and a merchant." }, { "type": "null" } ], "description": "The unique `Chargeflow` subscription identifier or the data of the subscription.", "example": "66e6ea9ecd94925a9f8060d9" }, "order": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "example": "ord_1234567890" } ], "description": "The order ID associated with the dispute. Can be a Chargeflow order identifier or an order identifier from the source.", "example": "ord_1234567890" }, { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "example": "ord_1234567890" }, { "type": "null" } ], "description": "The order ID associated with the dispute. Can be a Chargeflow order identifier or an order identifier from the source.", "example": "ord_1234567890" }, "source_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique order identifier appears on the source from which the order originated.", "example": "order_1234567890" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the order belongs.", "example": "act_1234567890" }, "ext_account_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique account identifier appears on the platform. Null if not set by the platform.", "example": "acc_123456" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the order was created at the source in ISO 8601 format.", "example": "2025-01-27T10:00:00Z" }, "payment_status": { "type": [ "string", "null" ], "enum": [ "paid", "partially_paid", "refunded", "partially_refunded" ], "description": "The financial status of the order", "example": "paid" }, "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The order name or number as appear in your source", "example": "#ORD-12345" }, "type": { "type": [ "string", "null" ], "enum": [ "standard", "pre_order" ], "description": "The type of the order; defaults to standard.", "example": "standard" }, "amount": { "type": [ "number", "null" ], "minimum": 0, "description": "Order total amount after all deductions.", "example": 1000 }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "customer": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The full name of the customer who have made this order.", "example": "John Doe" }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 128, "description": "The email address belong to the customer. Valid format:", "example": "example@mail.com" }, "customer_since": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the customer has made their first order with the merchant in ISO 8601 format.", "example": "2025-01-27T10:00:00Z" }, "order_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "The count of orders made by this customer with the merchant.", "example": 1 }, "phone_number": { "type": [ "string", "null" ], "maxLength": 128, "description": "The phone number belong to the customer. Valid format:", "example": "1(123)4567890" }, "ip_address": { "type": [ "string", "null" ], "maxLength": 128, "description": "The IP address belongs to the customer in the context of the given order. Valid format: IPv4 or IPv6.", "example": "192.168.1.1" }, "verified_email": { "type": [ "boolean", "null" ], "description": "Whether the customer email address was verified by the merchant. If `true`, the customer's email was verified at least once by the merchant.", "example": true } }, "description": "The customer who made this order." }, "products": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The product name as appear on the merchant's product catalog.", "example": "Product Name" }, "id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The product unique identifier. Relevant to link it to tracking number and shipping method.", "example": "123456789" }, "type": { "type": [ "string", "null" ], "enum": [ "physical_good", "digital_good", "service", "other" ], "description": "The type of the product", "example": "physical_good" }, "quantity": { "type": [ "integer", "null" ], "minimum": 1, "description": "The number of items that were purchased.", "example": 1 }, "description": { "type": [ "string", "null" ], "maxLength": 1000, "description": "A short description of the product as communicated to the customer in the merchant's product page.", "example": "Product Description" }, "image_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 1000, "description": "A url of the primary product image associated with the product. Valid format:", "example": "https://myurl.com/image/product/123456789" }, "price": { "type": [ "number", "null" ], "minimum": 0, "description": "The price amount of the given product in the order's currency.", "example": 100 } } }, "description": "An array of the products purchased in this order." }, "shipping_address": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The name of the person associated with the shipping address.", "example": "John Doe" }, "line1": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "example": "123 Main St" }, "line2": { "type": [ "string", "null" ], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "example": "Apt 1" }, "city": { "type": [ "string", "null" ], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "example": "San Francisco" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Two-letter country code (ISO 3166-1 alpha-2) associated with the address lines", "example": "US" }, "state": { "type": [ "string", "null" ], "description": "State, county, province, or region associated with the address lines.", "example": "CA" }, "zip_code": { "type": [ "string", "null" ], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "example": "12345" }, "phone": { "type": [ "string", "null" ], "description": "The phone number of the person associated with the shipping address.", "example": "1(123)4567890" } }, "description": "The shipping address associated with the order." }, "fulfillments": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "product_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The product's unique identifier to which the shipping method and tracking number was applied. Set to null if this was applied to all products in this order.", "example": "123456789" }, "shipped_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the order was shipped in ISO 8601 format.", "example": "2025-01-27T10:00:00Z" }, "shipping_line_title": { "type": [ "string", "null" ], "maxLength": 128, "description": "The shipping line title.", "example": "FedEx" }, "shipping_method_price": { "type": [ "number", "null" ], "minimum": 0, "description": "The shipping method price as paid by the customer in the order's currency.", "example": 100 }, "tracking_number": { "type": [ "string", "null" ], "maxLength": 128, "description": "The tracking number that was provided to track the fulfillment journey.", "example": "123456789" }, "courier": { "type": [ "string", "null" ], "maxLength": 128, "description": "The shipping courier from which the tracking number originated and used to fulfill the order.", "example": "FedEx" } } }, "description": "Details about the order shipping lines and tracking numbers." } }, "description": "An order is a record of a customer's purchase request, detailing the items bought, payment information, fulfillment status, and more." }, { "type": "null" } ], "description": "The unique `Chargeflow` order identifier or the data of the order." } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "invalid_request_error", "description": "The type of error", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "missing_dispute_id", "missing_chargeflow_id" ], "description": "Specific error code", "example": "missing_dispute_id" }, "message": { "type": "string", "enum": [ "Dispute ID is required", "User chargeflowId is required" ], "description": "Human-readable error message", "example": "Dispute ID is required" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Required parameters are missing from the request", "example": { "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", "example": "authentication_error" }, "code": { "type": "string", "enum": [ "unauthorized", "invalid_credentials", "missing_credentials" ], "description": "Specific error code", "example": "unauthorized" }, "message": { "type": "string", "enum": [ "Unauthorized access", "Authentication credentials are missing or invalid" ], "description": "Human-readable error message", "example": "Unauthorized access" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Unauthorized - Authentication is required or has failed", "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "Unauthorized access", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "UnauthorizedError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "permission_error", "description": "The type of error", "example": "permission_error" }, "code": { "type": "string", "enum": [ "unauthorized_dispute_access", "invalid_platform_access", "forbidden" ], "description": "Specific error code", "example": "unauthorized_dispute_access" }, "message": { "type": "string", "enum": [ "Unauthorized access to dispute data", "Invalid platform access", "Unauthorized access" ], "description": "Human-readable error message", "example": "Unauthorized access to dispute data" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "User does not have permission to access this dispute", "example": { "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", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "dispute_not_found", "shop_not_found" ], "description": "Specific error code", "example": "dispute_not_found" }, "message": { "type": "string", "enum": [ "Dispute not found", "Platform shop not found / Merchant shop not found" ], "description": "Human-readable error message", "example": "Dispute not found" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "The requested dispute or associated shop does not exist", "example": { "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", "example": "api_error" }, "code": { "type": "string", "enum": [ "internal_error", "server_error", "account_creation_failed", "account_retrieval_failed", "account_update_failed" ], "description": "Specific error code", "example": "internal_error" }, "message": { "type": "string", "enum": [ "Internal server error", "An unexpected error occurred", "Failed to create account", "Failed to get accounts", "Failed to update account" ], "description": "Human-readable error message", "example": "Internal server error" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Internal Server Error - Something went wrong on our end. Please try again later.", "example": { "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "InternalServerError" } } } } } }, "patch": { "tags": [ "Disputes" ], "summary": "Enrich Dispute", "description": "Enrich a dispute with additional data to improve your chances of winning. This endpoint allows you to freely enrich the dispute with as much relevant information as needed, including transaction data, order data, subscription data, and more. \n\nNOTE: When updating array properties, the entire array will be overwritten. To maintain existing data, you must include all items you want to keep in the array, not just the items you want to add or modify.", "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.", "example": "66e6ea9ecd94925a9f8060d9" }, "required": true } ], "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.", "example": "tx_1234567890" }, "order_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "example": "ord_1234567890" }, { "type": "null" } ], "description": "The order ID associated with the dispute. Can be a Chargeflow order identifier or an order identifier from the source.", "example": "ord_1234567890" }, "subscription_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow subscription ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The subscription ID from the source.", "example": "sub_1234567890" }, { "type": "null" } ], "description": "The subscription ID associated with the dispute. Can be a Chargeflow subscription identifier or a subscription identifier from the source.", "example": "66e6ea9ecd94925a9f8060d9" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the transaction was created at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "type": { "type": [ "string", "null" ], "enum": [ "paid", "partially_paid", "refunded", "partially_refunded" ], "description": "The type of the transaction", "example": "paid" }, "amount": { "type": [ "number", "null" ], "minimum": 0, "description": "Transaction total amount after all deductions.", "example": 100 }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "payment_method": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The full name of the person to which the payment method belongs to.", "example": "John Doe" }, "type": { "type": [ "string", "null" ], "enum": [ "card", "wallet" ], "description": "The type of the payment method", "example": "card" }, "last4": { "type": [ "string", "null" ], "pattern": "^\\d{4}$", "minLength": 4, "maxLength": 4, "description": "The last four digits of the card used for the transaction. `card`", "example": "1234" }, "expiry_month": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 12, "description": "The month when the card used for the transaction is expired. `card`", "example": 1 }, "expiry_year": { "type": [ "integer", "null" ], "minimum": 2019, "maximum": 2100, "description": "The year when the card used for the transaction is expired. `card`", "example": 2025 }, "brand": { "type": [ "string", "null" ], "enum": [ "visa", "mastercard", "discover", "amex", "jcb", "unionpay", "diners", "other" ], "description": "The card brand used for the transaction. `card`", "example": "visa" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "The card issuance country - two-letter country code (ISO 3166-1 alpha-2). `card`", "example": "US" }, "wallet": { "type": [ "string", "null" ], "enum": [ "paypal", "klarna", "affirm", "afterpay", "sezzle", "zip", "venmo", "apple", "other" ], "description": "The name of the wallet which used for the transaction. `wallet`", "example": "paypal" }, "checks": { "type": "object", "properties": { "three_d_secure_result": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The 3D secure authentication outcome. `card`", "example": "passed" }, "avs_results": { "type": [ "string", "null" ], "enum": [ "N", "A", "Y", "Z" ], "description": "The address verification system outcome. `card`", "example": "N" }, "address_line1_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The address line1 check result. `card`", "example": "passed" }, "address_zip_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The address zip or postal code check result. `card`", "example": "passed" }, "cvc_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The card verification code result. `card`", "example": "passed" } }, "description": "The checks performed by the network at the time of payment. `card`" }, "wallet_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 128, "description": "The email address of the wallet which used for the transaction. `wallet`", "example": "john.doe@example.com" }, "wallet_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The wallet unique identifier which used for the transaction. `wallet`", "example": "1234567890" } }, "description": "The payment method used for the transaction.", "example": { "type": "card", "name": "John Doe", "last4": "1234", "expiry_month": 1, "expiry_year": 2025, "brand": "visa" } }, "billing_address": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The name of the person associated with the billing address.", "example": "John Doe" }, "line1": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "example": "123 Main St" }, "line2": { "type": [ "string", "null" ], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "example": "Apt 1" }, "city": { "type": [ "string", "null" ], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "example": "San Francisco" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Two-letter country code (ISO 3166-1 alpha-2) associated with the address lines", "example": "US" }, "state": { "type": [ "string", "null" ], "description": "State, county, province, or region associated with the address lines.", "example": "CA" }, "zip_code": { "type": [ "string", "null" ], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "example": "12345" }, "phone": { "type": [ "string", "null" ], "description": "The phone number of the person associated with the billing address.", "example": "1(123)4567890" } }, "description": "The billing address associated with the payment method at the time of the transaction.", "example": { "name": "John Doe", "line1": "123 Main St", "line2": "Apt 1", "city": "Anytown", "state": "NY", "zip_code": "12345", "country": "US", "phone": "+1234567890" } } }, "description": "A transaction represents a money exchange between a buyer and a merchant in return for a physical product, digital product, service, booking, or other goods and offerings." }, "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.", "example": "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.", "example": "2025-01-27T10:00:00Z" }, "payment_status": { "type": [ "string", "null" ], "enum": [ "paid", "partially_paid", "refunded", "partially_refunded" ], "description": "The financial status of the order", "example": "paid" }, "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The order name or number as appear in your source", "example": "#ORD-12345" }, "type": { "type": [ "string", "null" ], "enum": [ "standard", "pre_order" ], "description": "The type of the order; defaults to standard.", "example": "standard" }, "amount": { "type": [ "number", "null" ], "minimum": 0, "description": "Order total amount after all deductions.", "example": 1000 }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "customer": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The full name of the customer who have made this order.", "example": "John Doe" }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 128, "description": "The email address belong to the customer. Valid format:", "example": "example@mail.com" }, "customer_since": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the customer has made their first order with the merchant in ISO 8601 format.", "example": "2025-01-27T10:00:00Z" }, "order_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "The count of orders made by this customer with the merchant.", "example": 1 }, "phone_number": { "type": [ "string", "null" ], "maxLength": 128, "description": "The phone number belong to the customer. Valid format:", "example": "1(123)4567890" }, "ip_address": { "type": [ "string", "null" ], "maxLength": 128, "description": "The IP address belongs to the customer in the context of the given order. Valid format: IPv4 or IPv6.", "example": "192.168.1.1" }, "verified_email": { "type": [ "boolean", "null" ], "description": "Whether the customer email address was verified by the merchant. If `true`, the customer's email was verified at least once by the merchant.", "example": true } }, "description": "The customer who made this order." }, "products": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The product name as appear on the merchant's product catalog.", "example": "Product Name" }, "id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The product unique identifier. Relevant to link it to tracking number and shipping method.", "example": "123456789" }, "type": { "type": [ "string", "null" ], "enum": [ "physical_good", "digital_good", "service", "other" ], "description": "The type of the product", "example": "physical_good" }, "quantity": { "type": [ "integer", "null" ], "minimum": 1, "description": "The number of items that were purchased.", "example": 1 }, "description": { "type": [ "string", "null" ], "maxLength": 1000, "description": "A short description of the product as communicated to the customer in the merchant's product page.", "example": "Product Description" }, "image_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 1000, "description": "A url of the primary product image associated with the product. Valid format:", "example": "https://myurl.com/image/product/123456789" }, "price": { "type": [ "number", "null" ], "minimum": 0, "description": "The price amount of the given product in the order's currency.", "example": 100 } } }, "description": "An array of the products purchased in this order." }, "shipping_address": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The name of the person associated with the shipping address.", "example": "John Doe" }, "line1": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "example": "123 Main St" }, "line2": { "type": [ "string", "null" ], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "example": "Apt 1" }, "city": { "type": [ "string", "null" ], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "example": "San Francisco" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Two-letter country code (ISO 3166-1 alpha-2) associated with the address lines", "example": "US" }, "state": { "type": [ "string", "null" ], "description": "State, county, province, or region associated with the address lines.", "example": "CA" }, "zip_code": { "type": [ "string", "null" ], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "example": "12345" }, "phone": { "type": [ "string", "null" ], "description": "The phone number of the person associated with the shipping address.", "example": "1(123)4567890" } }, "description": "The shipping address associated with the order." }, "fulfillments": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "product_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The product's unique identifier to which the shipping method and tracking number was applied. Set to null if this was applied to all products in this order.", "example": "123456789" }, "shipped_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the order was shipped in ISO 8601 format.", "example": "2025-01-27T10:00:00Z" }, "shipping_line_title": { "type": [ "string", "null" ], "maxLength": 128, "description": "The shipping line title.", "example": "FedEx" }, "shipping_method_price": { "type": [ "number", "null" ], "minimum": 0, "description": "The shipping method price as paid by the customer in the order's currency.", "example": 100 }, "tracking_number": { "type": [ "string", "null" ], "maxLength": 128, "description": "The tracking number that was provided to track the fulfillment journey.", "example": "123456789" }, "courier": { "type": [ "string", "null" ], "maxLength": 128, "description": "The shipping courier from which the tracking number originated and used to fulfill the order.", "example": "FedEx" } } }, "description": "Details about the order shipping lines and tracking numbers." } }, "description": "An order is a record of a customer's purchase request, detailing the items bought, payment information, fulfillment status, and more." } } } } } }, "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.", "example": "66e6ea9ecd94925a9f8060d9" }, "source": { "type": [ "string", "null" ], "enum": [ "paypal", "shopify", "maverick", "businessTrack", "cpanel", "globalPayments", "merlink", "braintree", "klarna", "square", "afterpay", "oceanpayment", "payarc", "firstview", "nexio", "elevate", "stripe", "goatPayments", "woopay", "nuvei", "safecharge", "zenPayments", "select", 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", "example": "stripe" }, "source_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique dispute identifier appears on the source (processor) from which the dispute originated.", "example": "du_123456789" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the dispute belongs.", "example": "66e6ea9ecd94925a9f8060d9" }, "ext_account_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique account identifier appears on the platform. Null if not set by the platform.", "example": "acc_123456" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the dispute was created in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "reason": { "type": [ "string", "null" ], "enum": [ "fraud", "not_received", "not_as_described", "canceled_recurring_billing", "duplicate_charge", "credit_not_processed", "other" ], "description": "The reason the cardholder has disputed the transaction.", "example": "fraud" }, "due_by": { "type": [ "string", "null" ], "format": "date-time", "description": "The deadline to submit evidence to challenge the dispute in ISO 8601 format.", "example": "2024-02-20T12:00:00Z" }, "amount": { "type": [ "number", "null" ], "minimum": 0, "description": "Disputed amount. Equal to or less than the disputed transaction amount.", "example": 100 }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "status": { "type": [ "string", "null" ], "enum": [ "needs_response", "under_review", "won", "lost" ], "description": "The current status of the dispute.", "example": "needs_response" }, "stage": { "type": [ "string", "null" ], "enum": [ "Chargeback", "Inquiry", "Pre_arbitration", "Arbitration" ], "description": "The stage of the dispute.", "example": "Chargeback" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the dispute has been closed and resolved in ISO 8601 format. Returns null if the dispute is not yet closed.", "example": "2025-01-27T10:00:00Z" }, "transaction": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow transaction ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The transaction ID from the source.", "example": "tx_1234567890" } ], "description": "The transaction ID associated with the dispute. Can be a Chargeflow transaction identifier or a transaction identifier from the source.", "example": "tx_1234567890" }, { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow transaction ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The transaction ID from the source.", "example": "tx_1234567890" }, { "type": "null" } ], "description": "The transaction ID associated with the dispute. Can be a Chargeflow transaction identifier or a transaction identifier from the source.", "example": "tx_1234567890" }, "source_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique transaction identifier appears on the source from which the transaction originated.", "example": "tx_1234567890" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the transaction belongs.", "example": "66e6ea9ecd94925a9f8060d8" }, "ext_account_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique account identifier appears on the platform. Null if not set by the platform.", "example": "acc_123456" }, "order_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "example": "ord_1234567890" }, { "type": "null" } ], "description": "The order ID associated with the dispute. Can be a Chargeflow order identifier or an order identifier from the source.", "example": "ord_1234567890" }, "subscription_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow subscription ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The subscription ID from the source.", "example": "sub_1234567890" }, { "type": "null" } ], "description": "The subscription ID associated with the dispute. Can be a Chargeflow subscription identifier or a subscription identifier from the source.", "example": "66e6ea9ecd94925a9f8060d9" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the transaction was created at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "type": { "type": [ "string", "null" ], "enum": [ "paid", "partially_paid", "refunded", "partially_refunded" ], "description": "The type of the transaction", "example": "paid" }, "amount": { "type": [ "number", "null" ], "minimum": 0, "description": "Transaction total amount after all deductions.", "example": 100 }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "payment_method": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The full name of the person to which the payment method belongs to.", "example": "John Doe" }, "type": { "type": [ "string", "null" ], "enum": [ "card", "wallet" ], "description": "The type of the payment method", "example": "card" }, "last4": { "type": [ "string", "null" ], "pattern": "^\\d{4}$", "minLength": 4, "maxLength": 4, "description": "The last four digits of the card used for the transaction. `card`", "example": "1234" }, "expiry_month": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 12, "description": "The month when the card used for the transaction is expired. `card`", "example": 1 }, "expiry_year": { "type": [ "integer", "null" ], "minimum": 2019, "maximum": 2100, "description": "The year when the card used for the transaction is expired. `card`", "example": 2025 }, "brand": { "type": [ "string", "null" ], "enum": [ "visa", "mastercard", "discover", "amex", "jcb", "unionpay", "diners", "other" ], "description": "The card brand used for the transaction. `card`", "example": "visa" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "The card issuance country - two-letter country code (ISO 3166-1 alpha-2). `card`", "example": "US" }, "wallet": { "type": [ "string", "null" ], "enum": [ "paypal", "klarna", "affirm", "afterpay", "sezzle", "zip", "venmo", "apple", "other" ], "description": "The name of the wallet which used for the transaction. `wallet`", "example": "paypal" }, "checks": { "type": "object", "properties": { "three_d_secure_result": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The 3D secure authentication outcome. `card`", "example": "passed" }, "avs_results": { "type": [ "string", "null" ], "enum": [ "N", "A", "Y", "Z" ], "description": "The address verification system outcome. `card`", "example": "N" }, "address_line1_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The address line1 check result. `card`", "example": "passed" }, "address_zip_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The address zip or postal code check result. `card`", "example": "passed" }, "cvc_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The card verification code result. `card`", "example": "passed" } }, "description": "The checks performed by the network at the time of payment. `card`" }, "wallet_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 128, "description": "The email address of the wallet which used for the transaction. `wallet`", "example": "john.doe@example.com" }, "wallet_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The wallet unique identifier which used for the transaction. `wallet`", "example": "1234567890" } }, "description": "The payment method used for the transaction.", "example": { "type": "card", "name": "John Doe", "last4": "1234", "expiry_month": 1, "expiry_year": 2025, "brand": "visa" } }, "billing_address": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The name of the person associated with the billing address.", "example": "John Doe" }, "line1": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "example": "123 Main St" }, "line2": { "type": [ "string", "null" ], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "example": "Apt 1" }, "city": { "type": [ "string", "null" ], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "example": "San Francisco" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Two-letter country code (ISO 3166-1 alpha-2) associated with the address lines", "example": "US" }, "state": { "type": [ "string", "null" ], "description": "State, county, province, or region associated with the address lines.", "example": "CA" }, "zip_code": { "type": [ "string", "null" ], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "example": "12345" }, "phone": { "type": [ "string", "null" ], "description": "The phone number of the person associated with the billing address.", "example": "1(123)4567890" } }, "description": "The billing address associated with the payment method at the time of the transaction.", "example": { "name": "John Doe", "line1": "123 Main St", "line2": "Apt 1", "city": "Anytown", "state": "NY", "zip_code": "12345", "country": "US", "phone": "+1234567890" } } }, "description": "A transaction represents a money exchange between a buyer and a merchant in return for a physical product, digital product, service, booking, or other goods and offerings." }, { "type": "null" } ], "description": "The unique `Chargeflow` transaction identifier or the data of the transaction.", "example": "66e6ea9ecd94925a9f8060d9" }, "subscription": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The subscription ID associated with the dispute. Can be a Chargeflow subscription identifier or a subscription identifier from the source.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The subscription ID associated with the dispute. Can be a Chargeflow subscription identifier or a subscription identifier from the source.", "example": "66e6ea9ecd94925a9f8060d9" }, "source_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique subscription identifier appears on the source from which the subscription originated.", "example": "source_sub_1234567890" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the subscription belongs.", "example": "66e6ea9ecd94925a9f8060d9" }, "ext_account_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique account identifier appears on the platform. Null if not set by the platform.", "example": "acc_123456" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was created at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was updated at the source in ISO 8601 format.", "example": "2024-02-15T12:00:00Z" }, "start_date": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was started at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "end_date": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was ended at the source in ISO 8601 format.", "example": "2024-08-10T12:00:00Z" }, "cancellation_date": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was requested to be canceled at the source in ISO 8601 format. Returns null if a cancellation is never requested.", "example": "2024-07-10T12:00:00Z" }, "frequency": { "type": [ "string", "null" ], "enum": [ "day", "week", "month", "year" ], "description": "The frequency at which a subscription is billed.", "example": "month" }, "frequency_count": { "type": [ "integer", "null" ], "minimum": 1, "description": "The number of intervals per billing cycle. For example, if frequency = month and frequency_count = 1, the subscription renews every month. If frequency_count = 3, the subscription renews every three months.", "example": 1 }, "cancellation_reason": { "type": [ "string", "null" ], "enum": [ "too_expensive", "low_quality", "unused", "too_complex", "missing_features" ], "description": "The submitted reason for why the subscription has canceled.", "example": "too_expensive" }, "collection_method": { "type": [ "string", "null" ], "enum": [ "automatically", "automatically_with_reminder", "send_invoice" ], "description": "The billing method for the subscription.", "example": "automatically" }, "trial_start": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the trial of the subscription began at the source in ISO 8601 format. Returns null if no trial is offered or if the trial was not utilized.", "example": "2024-02-10T12:00:00Z" }, "trial_end": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the trial of the subscription ended at the source in ISO 8601 format. Returns null if no trial is offered or if the trial was not utilized.", "example": "2024-03-10T12:00:00Z" }, "renews_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription cycle renews at the source in ISO 8601 format. Returns null if the subscription has been canceled.", "example": "2024-03-10T12:00:00Z" }, "plan_name": { "type": [ "string", "null" ], "description": "The name of the plan associated with the subscription, representing the specific offering or service tier the subscriber is enrolled in.", "example": "Pro Plan" }, "pricing_model": { "type": [ "string", "null" ], "enum": [ "fixed_price", "usage_base" ], "description": "The pricing model associated with the subscription.", "example": "fixed_price" }, "status": { "type": [ "string", "null" ], "enum": [ "active", "inactive", "canceled" ], "description": "The current status of the subscription.", "example": "active" } }, "description": "A subscription represents a recurring payment between a buyer and a merchant." }, { "type": "null" } ], "description": "The unique `Chargeflow` subscription identifier or the data of the subscription.", "example": "66e6ea9ecd94925a9f8060d9" }, "order": { "anyOf": [ { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "example": "ord_1234567890" } ], "description": "The order ID associated with the dispute. Can be a Chargeflow order identifier or an order identifier from the source.", "example": "ord_1234567890" }, { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "example": "ord_1234567890" }, { "type": "null" } ], "description": "The order ID associated with the dispute. Can be a Chargeflow order identifier or an order identifier from the source.", "example": "ord_1234567890" }, "source_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique order identifier appears on the source from which the order originated.", "example": "order_1234567890" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the order belongs.", "example": "act_1234567890" }, "ext_account_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique account identifier appears on the platform. Null if not set by the platform.", "example": "acc_123456" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the order was created at the source in ISO 8601 format.", "example": "2025-01-27T10:00:00Z" }, "payment_status": { "type": [ "string", "null" ], "enum": [ "paid", "partially_paid", "refunded", "partially_refunded" ], "description": "The financial status of the order", "example": "paid" }, "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The order name or number as appear in your source", "example": "#ORD-12345" }, "type": { "type": [ "string", "null" ], "enum": [ "standard", "pre_order" ], "description": "The type of the order; defaults to standard.", "example": "standard" }, "amount": { "type": [ "number", "null" ], "minimum": 0, "description": "Order total amount after all deductions.", "example": 1000 }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "customer": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The full name of the customer who have made this order.", "example": "John Doe" }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 128, "description": "The email address belong to the customer. Valid format:", "example": "example@mail.com" }, "customer_since": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the customer has made their first order with the merchant in ISO 8601 format.", "example": "2025-01-27T10:00:00Z" }, "order_count": { "type": [ "integer", "null" ], "minimum": 0, "description": "The count of orders made by this customer with the merchant.", "example": 1 }, "phone_number": { "type": [ "string", "null" ], "maxLength": 128, "description": "The phone number belong to the customer. Valid format:", "example": "1(123)4567890" }, "ip_address": { "type": [ "string", "null" ], "maxLength": 128, "description": "The IP address belongs to the customer in the context of the given order. Valid format: IPv4 or IPv6.", "example": "192.168.1.1" }, "verified_email": { "type": [ "boolean", "null" ], "description": "Whether the customer email address was verified by the merchant. If `true`, the customer's email was verified at least once by the merchant.", "example": true } }, "description": "The customer who made this order." }, "products": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The product name as appear on the merchant's product catalog.", "example": "Product Name" }, "id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The product unique identifier. Relevant to link it to tracking number and shipping method.", "example": "123456789" }, "type": { "type": [ "string", "null" ], "enum": [ "physical_good", "digital_good", "service", "other" ], "description": "The type of the product", "example": "physical_good" }, "quantity": { "type": [ "integer", "null" ], "minimum": 1, "description": "The number of items that were purchased.", "example": 1 }, "description": { "type": [ "string", "null" ], "maxLength": 1000, "description": "A short description of the product as communicated to the customer in the merchant's product page.", "example": "Product Description" }, "image_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 1000, "description": "A url of the primary product image associated with the product. Valid format:", "example": "https://myurl.com/image/product/123456789" }, "price": { "type": [ "number", "null" ], "minimum": 0, "description": "The price amount of the given product in the order's currency.", "example": 100 } } }, "description": "An array of the products purchased in this order." }, "shipping_address": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The name of the person associated with the shipping address.", "example": "John Doe" }, "line1": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "example": "123 Main St" }, "line2": { "type": [ "string", "null" ], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "example": "Apt 1" }, "city": { "type": [ "string", "null" ], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "example": "San Francisco" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Two-letter country code (ISO 3166-1 alpha-2) associated with the address lines", "example": "US" }, "state": { "type": [ "string", "null" ], "description": "State, county, province, or region associated with the address lines.", "example": "CA" }, "zip_code": { "type": [ "string", "null" ], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "example": "12345" }, "phone": { "type": [ "string", "null" ], "description": "The phone number of the person associated with the shipping address.", "example": "1(123)4567890" } }, "description": "The shipping address associated with the order." }, "fulfillments": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "product_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The product's unique identifier to which the shipping method and tracking number was applied. Set to null if this was applied to all products in this order.", "example": "123456789" }, "shipped_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the order was shipped in ISO 8601 format.", "example": "2025-01-27T10:00:00Z" }, "shipping_line_title": { "type": [ "string", "null" ], "maxLength": 128, "description": "The shipping line title.", "example": "FedEx" }, "shipping_method_price": { "type": [ "number", "null" ], "minimum": 0, "description": "The shipping method price as paid by the customer in the order's currency.", "example": 100 }, "tracking_number": { "type": [ "string", "null" ], "maxLength": 128, "description": "The tracking number that was provided to track the fulfillment journey.", "example": "123456789" }, "courier": { "type": [ "string", "null" ], "maxLength": 128, "description": "The shipping courier from which the tracking number originated and used to fulfill the order.", "example": "FedEx" } } }, "description": "Details about the order shipping lines and tracking numbers." } }, "description": "An order is a record of a customer's purchase request, detailing the items bought, payment information, fulfillment status, and more." }, { "type": "null" } ], "description": "The unique `Chargeflow` order identifier or the data of the order." } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "invalid_request_error", "description": "The type of error", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "missing_dispute_id", "invalid_request_body" ], "description": "Specific error code", "example": "missing_dispute_id" }, "message": { "type": "string", "enum": [ "Dispute ID is required", "Invalid request body" ], "description": "Human-readable error message", "example": "Dispute ID is required" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "The request is missing required parameters or contains invalid data", "example": { "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", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "dispute_not_found" ], "description": "Specific error code", "example": "dispute_not_found" }, "message": { "type": "string", "enum": [ "Dispute not found" ], "description": "Human-readable error message", "example": "Dispute not found" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "The requested dispute does not exist", "example": { "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": [ "Subscription" ], "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.", "example": "66e6ea9ecd94925a9f8060d9" }, "required": true } ], "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.", "example": "source_sub_1234567890" }, "account_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the subscription belongs. This field is `required` for platform users.", "example": "66e6ea9ecd94925a9f8060d9" }, "created_at": { "type": "string", "format": "date-time", "description": "The time at which the subscription was created at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "start_date": { "type": "string", "format": "date-time", "description": "The time at which the subscription was started at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "frequency": { "type": "string", "enum": [ "day", "week", "month", "year" ], "description": "The frequency at which a subscription is billed.", "example": "month" }, "frequency_count": { "type": "integer", "minimum": 1, "description": "The number of intervals per billing cycle. For example, if frequency = month and frequency_count = 1, the subscription renews every month. If frequency_count = 3, the subscription renews every three months.", "example": 1 }, "collection_method": { "type": "string", "enum": [ "automatically", "automatically_with_reminder", "send_invoice" ], "default": "automatically", "description": "The billing method for the subscription.", "example": "automatically" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was updated at the source in ISO 8601 format.", "example": "2024-02-15T12:00:00Z" }, "end_date": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was ended at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "cancellation_date": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was requested to be canceled at the source in ISO 8601 format. Returns null if a cancellation is never requested.", "example": "2024-07-10T12:00:00Z" }, "cancellation_reason": { "type": [ "string", "null" ], "enum": [ "too_expensive", "low_quality", "unused", "too_complex", "missing_features" ], "description": "The submitted reason for why the subscription has canceled.", "example": "too_expensive" }, "trial_start": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the trial of the subscription began at the source in ISO 8601 format. Returns null if no trial is offered or if the trial was not utilized.", "example": "2024-02-10T12:00:00Z" }, "trial_end": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the trial of the subscription ended at the source in ISO 8601 format. Returns null if no trial is offered or if the trial was not utilized.", "example": "2024-03-10T12:00:00Z" }, "renews_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription cycle renews at the source in ISO 8601 format. Returns null if the subscription has been canceled.", "example": "2024-03-10T12:00:00Z" }, "plan_name": { "type": [ "string", "null" ], "description": "The name of the plan associated with the subscription, representing the specific offering or service tier the subscriber is enrolled in.", "example": "Pro Plan" }, "pricing_model": { "type": "string", "enum": [ "fixed_price", "usage_base" ], "default": "fixed_price", "description": "The pricing model associated with the subscription.", "example": "fixed_price" }, "status": { "type": "string", "enum": [ "active", "inactive", "canceled" ], "default": "active", "description": "The current status of the subscription.", "example": "active" } }, "required": [ "source_id", "created_at", "start_date", "frequency", "frequency_count" ], "description": "Creates a new Chargeflow subscription." } } } }, "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.", "example": "66e6ea9ecd94925a9f8060d9" }, "source_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique subscription identifier appears on the source from which the subscription originated.", "example": "source_sub_1234567890" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the subscription belongs.", "example": "66e6ea9ecd94925a9f8060d9" }, "ext_account_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique account identifier appears on the platform. Null if not set by the platform.", "example": "acc_123456" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was created at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was updated at the source in ISO 8601 format.", "example": "2024-02-15T12:00:00Z" }, "start_date": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was started at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "end_date": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was ended at the source in ISO 8601 format.", "example": "2024-08-10T12:00:00Z" }, "cancellation_date": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription was requested to be canceled at the source in ISO 8601 format. Returns null if a cancellation is never requested.", "example": "2024-07-10T12:00:00Z" }, "frequency": { "type": [ "string", "null" ], "enum": [ "day", "week", "month", "year" ], "description": "The frequency at which a subscription is billed.", "example": "month" }, "frequency_count": { "type": [ "integer", "null" ], "minimum": 1, "description": "The number of intervals per billing cycle. For example, if frequency = month and frequency_count = 1, the subscription renews every month. If frequency_count = 3, the subscription renews every three months.", "example": 1 }, "cancellation_reason": { "type": [ "string", "null" ], "enum": [ "too_expensive", "low_quality", "unused", "too_complex", "missing_features" ], "description": "The submitted reason for why the subscription has canceled.", "example": "too_expensive" }, "collection_method": { "type": [ "string", "null" ], "enum": [ "automatically", "automatically_with_reminder", "send_invoice" ], "description": "The billing method for the subscription.", "example": "automatically" }, "trial_start": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the trial of the subscription began at the source in ISO 8601 format. Returns null if no trial is offered or if the trial was not utilized.", "example": "2024-02-10T12:00:00Z" }, "trial_end": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the trial of the subscription ended at the source in ISO 8601 format. Returns null if no trial is offered or if the trial was not utilized.", "example": "2024-03-10T12:00:00Z" }, "renews_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the subscription cycle renews at the source in ISO 8601 format. Returns null if the subscription has been canceled.", "example": "2024-03-10T12:00:00Z" }, "plan_name": { "type": [ "string", "null" ], "description": "The name of the plan associated with the subscription, representing the specific offering or service tier the subscriber is enrolled in.", "example": "Pro Plan" }, "pricing_model": { "type": [ "string", "null" ], "enum": [ "fixed_price", "usage_base" ], "description": "The pricing model associated with the subscription.", "example": "fixed_price" }, "status": { "type": [ "string", "null" ], "enum": [ "active", "inactive", "canceled" ], "description": "The current status of the subscription.", "example": "active" } }, "description": "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", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "missing_dispute_id" ], "description": "Specific error code", "example": "missing_dispute_id" }, "message": { "type": "string", "enum": [ "Dispute ID is required" ], "description": "Human-readable error message", "example": "Dispute ID is required" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Dispute ID parameter is missing or invalid", "example": { "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", "example": "authentication_error" }, "code": { "type": "string", "enum": [ "unauthorized", "invalid_credentials", "missing_credentials" ], "description": "Specific error code", "example": "unauthorized" }, "message": { "type": "string", "enum": [ "Unauthorized access", "Authentication credentials are missing or invalid" ], "description": "Human-readable error message", "example": "Unauthorized access" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Unauthorized - Authentication is required or has failed", "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "Unauthorized access", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "UnauthorizedError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "permission_error", "description": "The type of error", "example": "permission_error" }, "code": { "type": "string", "enum": [ "forbidden", "invalid_platform_access", "account_not_found" ], "description": "Specific error code", "example": "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", "example": "Forbidden" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "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", "example": { "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", "example": "api_error" }, "code": { "type": "string", "enum": [ "internal_error", "server_error", "account_creation_failed", "account_retrieval_failed", "account_update_failed" ], "description": "Specific error code", "example": "internal_error" }, "message": { "type": "string", "enum": [ "Internal server error", "An unexpected error occurred", "Failed to create account", "Failed to get accounts", "Failed to update account" ], "description": "Human-readable error message", "example": "Internal server error" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Internal Server Error - Something went wrong on our end. Please try again later.", "example": { "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "InternalServerError" } } } } } } }, "/public/2025-04-01/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", "example": 0 } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "The number of disputes per page", "example": 25 } } ], "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.", "example": "66e6ea9ecd94925a9f8060d9" }, "source": { "type": [ "string", "null" ], "enum": [ "paypal", "shopify", "maverick", "businessTrack", "cpanel", "globalPayments", "merlink", "braintree", "klarna", "square", "afterpay", "oceanpayment", "payarc", "firstview", "nexio", "elevate", "stripe", "goatPayments", "woopay", "nuvei", "safecharge", "zenPayments", "select", "checkout", "deposyt", "affirm", "adyen", "asana", "import", "import/induced", "samcart", "easyPayDirect", "paysafe", "bravapay", "micamp", "approvely", "platpay", "clover", "airwallex", "worldpay", "sezzle", "luqra", "paymentTech", "paymentsAI", "mamopay", "emsdata", "paymentsHub", "publicApi", "nmi", "wepay", "zippay", "paymentInsider", "trxServices", "merchantic", "wooPayments", "wooCommerce", "swipeSimple", "gmail", "zohoPayments", "recharge", "trustpay", "wixPayments", "venmo", "skrill", "blogicSystems", "useePay", "thinkific", "revolut", "kajabi", "tiktok", "authorizeNet", "nabankco", "finix", "zendesk", "gorgias", "cloudbeds", "swipearas", "amazonPay", "incheck", "platform", "ebanx", "kurvpay" ], "description": "The source of the dispute. name of the PSP", "example": "stripe" }, "source_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique dispute identifier appears on the source (processor) from which the dispute originated.", "example": "du_123456789" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the dispute belongs.", "example": "66e6ea9ecd94925a9f8060d9" }, "ext_account_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique account identifier appears on the platform. Null if not set by the platform.", "example": "acc_123456" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the dispute was created in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "reason": { "type": [ "string", "null" ], "enum": [ "fraud", "not_received", "not_as_described", "canceled_recurring_billing", "duplicate_charge", "credit_not_processed", "other" ], "description": "The reason the cardholder has disputed the transaction.", "example": "fraud" }, "due_by": { "type": [ "string", "null" ], "format": "date-time", "description": "The deadline to submit evidence to challenge the dispute in ISO 8601 format.", "example": "2024-02-20T12:00:00Z" }, "amount": { "type": [ "number", "null" ], "minimum": 0, "description": "Disputed amount. Equal to or less than the disputed transaction amount.", "example": 100 }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "status": { "type": [ "string", "null" ], "enum": [ "needs_response", "under_review", "won", "lost" ], "description": "The current status of the dispute.", "example": "needs_response" }, "stage": { "type": [ "string", "null" ], "enum": [ "Chargeback", "Inquiry", "Pre_arbitration", "Arbitration" ], "description": "The stage of the dispute.", "example": "Chargeback" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the dispute has been closed and resolved in ISO 8601 format. Returns null if the dispute is not yet closed.", "example": "2025-01-27T10:00:00Z" }, "transaction": { "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.", "example": "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.", "example": "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.", "example": "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.", "example": "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", "example": 100 }, "offset": { "type": "integer", "minimum": 0, "default": 0, "description": "The page number of the current response", "example": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25, "description": "The number of disputes per page", "example": 25 }, "totalPages": { "type": "integer", "minimum": 0, "description": "Total number of pages available in the database", "example": 54 } }, "description": "Pagination information for the current response", "example": { "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", "example": "authentication_error" }, "code": { "type": "string", "enum": [ "unauthorized", "invalid_credentials", "missing_credentials" ], "description": "Specific error code", "example": "unauthorized" }, "message": { "type": "string", "enum": [ "Unauthorized access", "Authentication credentials are missing or invalid" ], "description": "Human-readable error message", "example": "Unauthorized access" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Unauthorized - Authentication is required or has failed", "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "Unauthorized access", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "UnauthorizedError" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "permission_error", "description": "The type of error", "example": "permission_error" }, "code": { "type": "string", "enum": [ "unauthorized_shop_access" ], "description": "Specific error code", "example": "unauthorized_shop_access" }, "message": { "type": "string", "enum": [ "Unauthorized access to shop data" ], "description": "Human-readable error message", "example": "Unauthorized access to shop data" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "User does not have access to the requested shop data", "example": { "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", "example": "api_error" }, "code": { "type": "string", "enum": [ "internal_error", "server_error", "account_creation_failed", "account_retrieval_failed", "account_update_failed" ], "description": "Specific error code", "example": "internal_error" }, "message": { "type": "string", "enum": [ "Internal server error", "An unexpected error occurred", "Failed to create account", "Failed to get accounts", "Failed to update account" ], "description": "Human-readable error message", "example": "Internal server error" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Internal Server Error - Something went wrong on our end. Please try again later.", "example": { "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error", "request_id": "req_abc123def456" } }, "x-readme-ref-name": "InternalServerError" } } } } } } }, "/public/2025-04-01/health-check/access-key": { "get": { "tags": [ "Health Check" ], "summary": "Validate Access Key", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/public/2025-04-01/health-check": { "get": { "tags": [ "Health Check" ], "summary": "Service Health Verification", "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", "example": "*%23http%3A%2F%2Ftest.com%2Fwebhook" }, "required": true } ], "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/disputes/{disputeId}/order": { "post": { "tags": [ "Disputes" ], "summary": "Update Dispute Order", "description": "Update the order associated with a dispute.\n \u26a0\ufe0f Soon to be deprecated \u26a0\ufe0f", "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.", "example": "66e6ea9ecd94925a9f8060d9" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "orderReference": { "type": "string", "maxLength": 10000, "description": "A field that can hold the name of the order as identified in your system, which could be an invoice ID or any other reference", "example": "Order-001" }, "creationDate": { "type": "string", "format": "date-time", "description": "The date and time when the order was created, recorded in ISO 8601 format", "example": "2022-01-01T00:00:00Z" }, "checkoutId": { "type": "string", "maxLength": 10000, "description": "An optional identifier for the checkout process associated with the order", "example": "CHK-78910" }, "orderStatusUrl": { "type": "string", "format": "uri", "description": "An optional URL that directs to a page where the status of the order can be reviewed", "example": "https://example.com/order/status/123456" }, "amount": { "type": "object", "properties": { "value": { "type": "number", "minimum": 0, "description": "The amount value", "example": 100 }, "currency": { "type": "string", "maxLength": 10, "description": "The three-letter ISO 4217 currency code represents the currency used for the amount", "example": "USD" } }, "additionalProperties": false }, "financialStatus": { "type": "string", "enum": [ "paid", "partially_refunded", "refunded" ], "description": "An enum value represents the current financial status of the order. Possible values include paid, partially_refunded, and refunded, which indicate the payment stage of the order", "example": "paid" }, "customer": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 128, "description": "A unique identifier for the customer within your system", "example": "12345" }, "creationDate": { "type": "string", "format": "date-time", "description": "The date and time when the customer was created or first entered into the system, in ISO 8601 format" }, "email": { "type": "string", "format": "email", "description": "The email address of the customer", "example": "email@mail.com" }, "firstName": { "type": "string", "maxLength": 128, "description": "The first name of the customer", "example": "Dan" }, "lastName": { "type": "string", "maxLength": 128, "description": "The last name of the customer", "example": "Brown" }, "phone": { "type": "string", "maxLength": 128, "description": "The phone number of the customer", "example": "+1234567890" }, "purchaseActivityId": { "type": "string", "maxLength": 128, "description": "Identifies the activity id" }, "activity": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 128, "description": "A unique identifier for the activity", "example": "12345" }, "activityDate": { "type": "string", "format": "date-time", "description": "The date and time when a activity was processed, in ISO 8601 format", "example": "2022-01-01T00:00:00Z" }, "type": { "type": "string", "enum": [ "signup", "login", "logout", "download", "export", "edit", "password_changed", "profile_updated", "general_action", "payment" ], "description": "An enum value represents a predefined status", "example": "signup" }, "description": { "type": "string", "maxLength": 10000, "description": "A free text explaining the activity event of the activity logged (e.g., a report has been downloaded, the user has changed their password, a successful payment has been processed, etc.)" }, "fingerprint": { "type": "object", "properties": { "type": { "type": "object", "properties": { "userAgent": { "type": "string", "maxLength": 512, "description": "An optional field containing details about the browsing client used to place the order, such as browser version and operating system", "example": "browser-fingerprint-details" }, "ipAddress": { "type": "string", "description": "The IP address of the device used to place the order", "example": "192.158.1.38" }, "MAC": { "type": "string", "maxLength": 128, "description": "The MAC address of the device used to place the order", "example": "00:00:00:00:00:00" } }, "additionalProperties": false }, "value": { "type": "string", "maxLength": 512, "description": "Fingerprint value", "example": "device address" } } }, "source": { "type": "string", "maxLength": 128, "description": "The source of the activity", "example": "API" } }, "additionalProperties": false } } }, "additionalProperties": false, "description": "An object that represents the customer\u2019s details under this order" }, "billingAddress": { "type": "object", "properties": { "firstName": { "type": "string", "maxLength": 128, "description": "The first name of the individual to whom the order will be billed", "example": "John" }, "lastName": { "type": "string", "maxLength": 128, "description": "The last name of the individual to whom the order will be billed", "example": "Doe" }, "country": { "type": "string", "maxLength": 128, "description": "The country to which the order will be billed, represented by its full name or ISO code", "example": "US" }, "state": { "type": "string", "maxLength": 128, "description": "The state or region of the billing address", "example": "CA" }, "city": { "type": "string", "maxLength": 128, "description": "The city of the billing address", "example": "LA" }, "address1": { "type": "string", "maxLength": 128, "description": "The primary street address for billing", "example": "123 Main St" }, "address2": { "type": "string", "maxLength": 128, "description": "An optional secondary address line for billing, which might include apartment numbers, suite numbers, etc", "example": "Apt 123" }, "zipCode": { "type": "string", "maxLength": 64, "description": "The postal code for the billing address", "example": "12345" }, "phone": { "type": "string", "maxLength": 64, "description": "An optional phone number for the billing recipient", "example": "+1234567890" } }, "additionalProperties": false, "description": "An object that represents the billing address of the order's payer" }, "shippingAddress": { "type": "object", "properties": { "firstName": { "type": "string", "maxLength": 128, "description": "The first name of the individual to whom the order will be billed", "example": "John" }, "lastName": { "type": "string", "maxLength": 128, "description": "The last name of the individual to whom the order will be billed", "example": "Doe" }, "country": { "type": "string", "maxLength": 128, "description": "The country to which the order will be billed, represented by its full name or ISO code", "example": "US" }, "state": { "type": "string", "maxLength": 128, "description": "The state or region of the billing address", "example": "CA" }, "city": { "type": "string", "maxLength": 128, "description": "The city of the billing address", "example": "LA" }, "address1": { "type": "string", "maxLength": 128, "description": "The primary street address for billing", "example": "123 Main St" }, "address2": { "type": "string", "maxLength": 128, "description": "An optional secondary address line for billing, which might include apartment numbers, suite numbers, etc", "example": "Apt 123" }, "zipCode": { "type": "string", "maxLength": 64, "description": "The postal code for the billing address", "example": "12345" }, "phone": { "type": "string", "maxLength": 64, "description": "An optional phone number for the billing recipient", "example": "+1234567890" } }, "additionalProperties": false, "description": "An object that represents the shipping address of the order's payer" }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "minimum": 0, "description": "The product id" }, "variantId": { "type": "number", "minimum": 0, "description": "The product variant id" }, "name": { "type": "string", "maxLength": 256, "description": "The name of the product included in the order", "example": "Product Name" }, "price": { "type": "object", "properties": { "value": { "type": "number", "minimum": 0, "description": "The amount value", "example": 100 }, "currency": { "type": "string", "maxLength": 10, "description": "The three-letter ISO 4217 currency code represents the currency used for the amount", "example": "USD" } }, "additionalProperties": false }, "imageUrl": { "type": "string", "format": "uri", "description": "A publicly available URL leading to an image of the product", "example": "https://example.com/image.png" }, "description": { "type": "string", "maxLength": 10000, "description": "A description of the product, providing details about its features, specifications, or usage" }, "refundTransactionId": { "type": "string", "maxLength": 128, "description": "If the product was refunded refers to the transaction Id. The transaction with that id is expected to be found in transactions array" }, "quantity": { "type": "number", "minimum": 0, "description": "The quantity of this product ordered" }, "discount": { "type": "object", "properties": { "value": { "type": "number", "minimum": 0, "description": "The amount value", "example": 100 }, "currency": { "type": "string", "maxLength": 10, "description": "The three-letter ISO 4217 currency code represents the currency used for the amount", "example": "USD" } }, "additionalProperties": false, "description": "An object that represents the total discounts associated with this order" }, "shipmentId": { "type": "string", "maxLength": 128, "description": "The shipment id associated with the product" } }, "additionalProperties": false }, "description": "An array of objects that represent the products included in this order" }, "transactions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 128, "description": "The transaction id" }, "transactionDate": { "type": "string", "format": "date-time", "description": "The date and time when the transaction was created, in ISO 8601 format", "example": "2022-01-01T00:00:00Z" }, "amount": { "type": "object", "properties": { "value": { "type": "number", "minimum": 0, "description": "The amount value", "example": 100 }, "currency": { "type": "string", "maxLength": 10, "description": "The three-letter ISO 4217 currency code represents the currency used for the amount", "example": "USD" } }, "additionalProperties": false }, "cardBrand": { "type": "string", "maxLength": 10, "description": "The brand of the card used for the transaction", "example": "visa" }, "cardLast4": { "type": "string", "maxLength": 4, "description": "The last 4 digits of the card used for the transaction", "example": "1234" }, "cardHolderName": { "type": "string", "maxLength": 100, "description": "The name of the card holder", "example": "John Doe" }, "cardCountry": { "type": "string", "maxLength": 2, "description": "The country of the card used for the transaction", "example": "US" }, "cardNetwork": { "type": "string", "maxLength": 10, "description": "The network of the card used for the transaction", "example": "visa" }, "cardExpirationMonth": { "type": "number", "minimum": 1, "maximum": 12, "description": "The month of the card expiration date", "example": 1 }, "cardExpirationYear": { "type": "number", "minimum": 2020, "maximum": 2040, "description": "The year of the card expiration date" }, "cvvCode": { "type": "string", "enum": [ "M", "N", "P", "S", "U", "X" ], "description": "The Card Verification Value (CVV or CVC) of the transaction", "example": "M" }, "customerName": { "type": "string", "maxLength": 100, "description": "The name of the customer", "example": "John Doe" }, "customerEmail": { "type": "string", "format": "email", "description": "The email of the customer" }, "orderId": { "type": "string", "maxLength": 128, "description": "The id of the order", "example": "1234567890" } }, "additionalProperties": false }, "description": "An array of objects that represent the transactions related to this order" }, "shipments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 128, "description": "The shipment id" }, "shipmentDate": { "type": "string", "format": "date-time", "description": "The date and time when the shipment was created, in ISO 8601 format", "example": "2022-01-01T00:00:00Z" }, "trackingNumber": { "type": "string", "maxLength": 128, "description": "The tracking number of the shipment", "example": "1234567890" } }, "additionalProperties": false }, "description": "An array of objects that represent the shipments related to shipments this order" }, "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 128, "description": "The subscription id" }, "status": { "type": "string", "enum": [ "active", "canceled", "paused", "expired" ], "description": "An enum value represents the current subscription status. Possible values include active, canceled, paused, and expired", "example": "active" }, "plan": { "type": "string", "maxLength": 128, "description": "The type of subscription plan or subscription name (e.g., basic, premium)", "example": "premium" }, "frequency": { "type": "number", "minimum": 0, "description": "The frequency of subscription renewal in days", "example": 30 }, "startDate": { "type": "string", "format": "date-time", "description": "The start date and time of the subscription in ISO 8601 format", "example": "2022-01-01T00:00:00Z" }, "updatedDate": { "type": "string", "format": "date-time", "description": "The last update date and time of the subscription in ISO 8601 format", "example": "2022-01-01T00:00:00Z" }, "renewalDate": { "type": "string", "format": "date-time", "description": "The next renewal date and time of the subscription in ISO 8601 format", "example": "2022-01-01T00:00:00Z" }, "cancellationReason": { "type": "string", "maxLength": 10000, "description": "The reason for the subscription cancellation", "example": "" }, "cancellationDate": { "type": "string", "format": "date-time", "description": "The date and time when the subscription was canceled, if applicable, in ISO 8601 format", "example": "2022-01-01T00:00:00Z" }, "chargesCount": { "type": "string", "maxLength": 10000, "description": "Total number of charges made under this subscription", "example": "" }, "chargesHistory": { "type": "array", "items": { "type": "object", "properties": { "chargeDate": { "type": "string", "format": "date-time", "description": "The date and time when a particular charge was made in ISO 8601 format", "example": "2022-01-01T00:00:00Z" }, "status": { "type": "string", "enum": [ "success", "failed", "refunded", "partially_refunded", "skipped" ], "description": "The current charge status. Possible values include success, failed, refunded, partially_refunded, and skipped", "example": "refunded" }, "amount": { "type": "object", "properties": { "value": { "type": "number", "minimum": 0, "description": "The amount value", "example": 100 }, "currency": { "type": "string", "maxLength": 10, "description": "The three-letter ISO 4217 currency code represents the currency used for the amount", "example": "USD" } }, "additionalProperties": false, "description": "Amount of subscription charge" }, "totalDiscounts": { "type": "object", "properties": { "value": { "type": "number", "minimum": 0, "description": "The amount value", "example": 100 }, "currency": { "type": "string", "maxLength": 10, "description": "The three-letter ISO 4217 currency code represents the currency used for the amount", "example": "USD" } }, "additionalProperties": false, "description": "An object that represents the total discounts applied to the charge" } }, "additionalProperties": false }, "description": "An array of objects that represent the history of the charges under this subscription" } }, "additionalProperties": false }, "description": "An array of objects that represent the subscriptions related to this order" }, "pastOrders": { "type": "array", "items": { "type": "object", "properties": { "orderId": { "type": "number", "description": "The unique identifier for the order", "example": 12345 }, "customerId": { "type": "number", "description": "The unique identifier for the customer", "example": 67890 }, "amount": { "type": [ "string", "null" ], "description": "The total amount of the order", "example": "99.99" }, "currency": { "type": [ "string", "null" ], "description": "The currency code for the order amount", "example": "USD" }, "transactionId": { "type": [ "number", "null" ], "description": "The unique identifier for the transaction", "example": 54321 }, "transactionDate": { "type": [ "string", "null" ], "format": "date-time", "description": "The date and time of the transaction in ISO 8601 format", "example": "2022-01-01T00:00:00Z" }, "transactionCardholderName": { "type": [ "string", "null" ], "description": "The name of the cardholder who made the transaction", "example": "John Doe" }, "transactionCardBrand": { "type": [ "string", "null" ], "description": "The brand of the card used for the transaction", "example": "visa" }, "transactionCardLast4": { "type": [ "string", "null" ], "description": "The last 4 digits of the card used for the transaction", "example": "4242" }, "transactionAuthorizationId": { "type": [ "string", "null" ], "description": "The authorization identifier for the transaction", "example": "auth_123xyz" }, "customerEmail": { "type": [ "string", "null" ], "format": "email", "description": "The email address of the customer", "example": "customer@example.com" } }, "required": [ "orderId", "customerId" ], "additionalProperties": false }, "description": "An array of objects that represent the past orders related to this order" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Order linked to dispute successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "The request id for tracking and auditing" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "invalid_request_error", "description": "The type of error", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_request_body", "missing_dispute_id", "missing_chargeflow_id" ], "description": "Specific error code", "example": "invalid_request_body" }, "message": { "type": "string", "enum": [ "Invalid request body", "Dispute ID is required", "User chargeflowId is required" ], "description": "Human-readable error message", "example": "Invalid request body" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "The request is missing required data or contains invalid parameters", "example": { "error": { "type": "invalid_request_error", "code": "invalid_request_body", "message": "Invalid request body", "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/DisputeOrderLinkingForbiddenError" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "invalid_request_error", "description": "The type of error", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "dispute_not_found", "shop_not_found" ], "description": "Specific error code", "example": "dispute_not_found" }, "message": { "type": "string", "enum": [ "Dispute not found", "Platform shop not found / Merchant shop not found" ], "description": "Human-readable error message", "example": "Dispute not found" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "The requested dispute or shop does not exist", "example": { "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", "example": "api_error" }, "code": { "type": "string", "enum": [ "internal_error" ], "description": "Specific error code", "example": "internal_error" }, "message": { "type": "string", "enum": [ "Internal server error" ], "description": "Human-readable error message", "example": "Internal server error" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "An unexpected error occurred while processing the request", "example": { "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error", "request_id": "req_abc123def456" } } } } } } } } }, "/public/2025-04-01/disputes/{disputeId}/transaction": { "post": { "tags": [ "Transaction" ], "summary": "Create Transaction", "description": "Creates a transaction 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.", "example": "66e6ea9ecd94925a9f8060d9" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "source_id": { "type": "string", "maxLength": 128, "description": "The unique transaction identifier appears on the source from which the transaction originated.", "example": "tx_1234567890" }, "account_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the transaction belongs.", "example": "66e6ea9ecd94925a9f8060d9" }, "created_at": { "type": "string", "format": "date-time", "description": "The time at which the transaction was created at the source in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "type": { "type": "string", "enum": [ "paid", "partially_paid", "refunded", "partially_refunded" ], "description": "The type of the transaction", "example": "paid" }, "amount": { "type": "number", "minimum": 0, "description": "Transaction total amount after all deductions.", "example": 100 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "payment_method": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The full name of the person to which the payment method belongs to.", "example": "John Doe" }, "type": { "type": [ "string", "null" ], "enum": [ "card", "wallet" ], "description": "The type of the payment method", "example": "card" }, "last4": { "type": [ "string", "null" ], "pattern": "^\\d{4}$", "minLength": 4, "maxLength": 4, "description": "The last four digits of the card used for the transaction. `card`", "example": "1234" }, "expiry_month": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 12, "description": "The month when the card used for the transaction is expired. `card`", "example": 1 }, "expiry_year": { "type": [ "integer", "null" ], "minimum": 2019, "maximum": 2100, "description": "The year when the card used for the transaction is expired. `card`", "example": 2025 }, "brand": { "type": [ "string", "null" ], "enum": [ "visa", "mastercard", "discover", "amex", "jcb", "unionpay", "diners", "other" ], "description": "The card brand used for the transaction. `card`", "example": "visa" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "The card issuance country - two-letter country code (ISO 3166-1 alpha-2). `card`", "example": "US" }, "wallet": { "type": [ "string", "null" ], "enum": [ "paypal", "klarna", "affirm", "afterpay", "sezzle", "zip", "venmo", "apple", "other" ], "description": "The name of the wallet which used for the transaction. `wallet`", "example": "paypal" }, "checks": { "type": "object", "properties": { "three_d_secure_result": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The 3D secure authentication outcome. `card`", "example": "passed" }, "avs_results": { "type": [ "string", "null" ], "enum": [ "N", "A", "Y", "Z" ], "description": "The address verification system outcome. `card`", "example": "N" }, "address_line1_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The address line1 check result. `card`", "example": "passed" }, "address_zip_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The address zip or postal code check result. `card`", "example": "passed" }, "cvc_check": { "type": [ "string", "null" ], "enum": [ "passed", "failed", "null" ], "description": "The card verification code result. `card`", "example": "passed" } }, "description": "The checks performed by the network at the time of payment. `card`" }, "wallet_email": { "type": [ "string", "null" ], "format": "email", "maxLength": 128, "description": "The email address of the wallet which used for the transaction. `wallet`", "example": "john.doe@example.com" }, "wallet_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The wallet unique identifier which used for the transaction. `wallet`", "example": "1234567890" } }, "description": "The payment method used by the customer to process the transaction." }, "billing_address": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "maxLength": 128, "description": "The name of the person associated with the billing address.", "example": "John Doe" }, "line1": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 40, "description": "The primary address line (e.g., street name).", "example": "123 Main St" }, "line2": { "type": [ "string", "null" ], "maxLength": 40, "description": "An optional address line (e.g., floor, apartment number, etc.).", "example": "Apt 1" }, "city": { "type": [ "string", "null" ], "maxLength": 35, "description": "City, district, suburb, town, or village associated with the address lines.", "example": "San Francisco" }, "country": { "type": [ "string", "null" ], "pattern": "^[A-Z]{2}$", "description": "Two-letter country code (ISO 3166-1 alpha-2) associated with the address lines", "example": "US" }, "state": { "type": [ "string", "null" ], "description": "State, county, province, or region associated with the address lines.", "example": "CA" }, "zip_code": { "type": [ "string", "null" ], "maxLength": 10, "description": "ZIP or postal code associated with the address lines.", "example": "12345" }, "phone": { "type": [ "string", "null" ], "description": "The phone number of the person associated with the billing address.", "example": "1(123)4567890" } }, "description": "The billing address associated with the payment method at the time of the transaction" }, "order_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow order ID associated with the dispute.", "example": "66e6ea9ecd94925a9f8060d9" }, { "type": "string", "maxLength": 128, "description": "The order ID from the source.", "example": "ord_1234567890" } ], "description": "The unique Chargeflow identifier of the order to which the transaction is linked.", "example": "66e6ea9ecd94925a9f8060d9" }, "subscription_id": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow identifier of the subscription to which the transaction is linked.", "example": "66e6ea9ecd94925a9f8060d9" } }, "required": [ "source_id", "account_id", "created_at", "type", "amount", "currency" ], "description": "Creates a new Chargeflow transaction." } } } }, "responses": { "200": { "description": "Transaction created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "The request id for tracking and auditing" } }, "required": [ "requestId" ] } } } }, "501": { "description": "Not Implemented - Please contact support at hello@chargeflow.io" } } } }, "/public/2025-04-01/disputes/{disputeId}/user_events_log": { "post": { "tags": [ "User Event Log" ], "summary": "Create User Event Log", "description": "Creates an user events log 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.", "example": "66e6ea9ecd94925a9f8060d9" }, "required": true } ], "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.", "example": "sub_1234567890" }, "account_id": { "type": "string", "maxLength": 128, "description": "The unique Chargeflow account identifier to which the subscription belongs.", "example": "acct_1234567890" }, "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "maxLength": 10000, "description": "The unique identifier of the event. Defaults to null.", "example": "evt_123456" }, "name": { "type": "string", "maxLength": 10000, "description": "The name of the event.", "example": "login" }, "date": { "type": "string", "format": "date-time", "description": "The time at which the event was created at the source in ISO 8601 format.", "example": "2025-01-27T10:00:00Z" }, "ip_address": { "type": [ "string", "null" ], "description": "The IP address belongs to the customer in the context of the given session. Valid format: IPv4 or IPv6. Defaults to null.", "example": "192.168.1.1" }, "user_agent": { "type": [ "string", "null" ], "description": "The user agent identifies the browser, application, or device used during the event. Defaults to null.", "example": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" } }, "required": [ "name", "date" ] }, "description": "A list of events performed by a customer." } }, "required": [ "source_id", "account_id", "events" ], "description": "Creates a new Chargeflow user event log." } } } }, "responses": { "200": { "description": "User event log created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "The request id for tracking and auditing" } }, "required": [ "requestId" ] } } } }, "501": { "description": "Not Implemented - Please contact support at hello@chargeflow.io" } } } }, "/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.", "example": "user@example.com" }, "account_id": { "type": "string", "description": "The Chargeflow account ID. Required for platform API keys, ignored for merchant API keys.", "example": "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.", "example": "req_abc123" }, "status": { "type": "string", "description": "The current status of the removal request.", "example": "acknowledged" }, "chargeflow_id": { "type": "string", "description": "The Chargeflow account ID associated with this request.", "example": "66e6ea9ecd94925a9f8060d9" }, "created_at": { "type": "string", "description": "The time the request was created in ISO 8601 format.", "example": "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", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "duplicate_request" ], "description": "Specific error code", "example": "duplicate_request" }, "message": { "type": "string", "enum": [ "A removal request for this email already exists" ], "description": "Human-readable error message", "example": "A removal request for this email already exists" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "A removal request for this email and account already exists", "example": { "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.", "example": "req_abc123" }, "required": true }, { "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.", "example": "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.", "example": "req_abc123" }, "status": { "type": "string", "description": "The current status of the removal request.", "example": "acknowledged" }, "chargeflow_id": { "type": "string", "description": "The Chargeflow account ID associated with this request.", "example": "66e6ea9ecd94925a9f8060d9" }, "created_at": { "type": "string", "description": "The time the request was created in ISO 8601 format.", "example": "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", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "removal_request_not_found" ], "description": "Specific error code", "example": "removal_request_not_found" }, "message": { "type": "string", "enum": [ "Removal request not found" ], "description": "Human-readable error message", "example": "Removal request not found" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "The specified removal request does not exist", "example": { "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", "example": "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.", "example": "66e6ea9ecd94925a9f8060d9" }, "source": { "type": [ "string", "null" ], "enum": [ "paypal", "shopify", "maverick", "businessTrack", "cpanel", "globalPayments", "merlink", "braintree", "klarna", "square", "afterpay", "oceanpayment", "payarc", "firstview", "nexio", "elevate", "stripe", "goatPayments", "woopay", "nuvei", "safecharge", "zenPayments", "select", 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", "example": "stripe" }, "source_id": { "type": [ "string", "null" ], "maxLength": 128, "description": "The unique dispute identifier appears on the source (processor) from which the dispute originated.", "example": "du_123456789" }, "account_id": { "type": [ "string", "null" ], "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow account identifier to which the dispute belongs.", "example": "66e6ea9ecd94925a9f8060d9" }, "created_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the dispute was created in ISO 8601 format.", "example": "2024-02-10T12:00:00Z" }, "reason": { "type": [ "string", "null" ], "enum": [ "fraud", "not_received", "not_as_described", "canceled_recurring_billing", "duplicate_charge", "credit_not_processed", "other" ], "description": "The reason the cardholder has disputed the transaction.", "example": "fraud" }, "due_by": { "type": [ "string", "null" ], "format": "date-time", "description": "The deadline to submit evidence to challenge the dispute in ISO 8601 format.", "example": "2024-02-20T12:00:00Z" }, "amount": { "type": [ "number", "null" ], "minimum": 0, "description": "Disputed amount. Equal to or less than the disputed transaction amount.", "example": 100 }, "currency": { "type": [ "string", "null" ], "pattern": "^[A-Z]{3}$", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO 4217 currency code in uppercase.", "example": "USD" }, "status": { "type": [ "string", "null" ], "enum": [ "needs_response", "under_review", "won", "lost" ], "description": "The current status of the dispute.", "example": "needs_response" }, "stage": { "type": [ "string", "null" ], "enum": [ "Chargeback", "Inquiry", "Pre_arbitration", "Arbitration" ], "description": "The stage of the dispute.", "example": "Chargeback" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The time at which the dispute has been closed and resolved in ISO 8601 format. Returns null if the dispute is not yet closed.", "example": "2025-01-27T10:00:00Z" }, "transaction": { "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.", "example": "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.", "example": "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.", "example": "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.", "example": "66e6ea9ecd94925a9f8060d9" } } }, "creationDate": { "type": "string", "format": "date-time", "description": "The creation date of the webhook in ISO8601 format", "example": "2021-01-01T00:00:00Z" }, "webhookId": { "type": "string", "format": "uuid", "default": "0b5868f0-9cd9-4e02-b241-7e5eb7f184be", "description": "The webhook id", "example": "123e4567-e89b-12d3-a456-426614174000" } } } } } }, "responses": { "200": { "description": "OK" } } } }, "alerts.created": { "post": { "summary": "Alerts Created Event", "description": "The **Alert Created** webhook is available exclusively for Chargeflow Alerts customers. It notifies your system in real time whenever a new pre-chargeback alert is created for your account. When a new alert is received by Chargeflow, the webhook sends an HTTP `POST` request to your configured endpoint containing the alert ID and key metadata.\n\nMerchants can use this webhook to:\n* **Trigger automated workflows** (e.g., refund, order cancellation, tagging) immediately when an alert is received.\n* **Ingest alerts into internal systems** for logging, monitoring, or case management.\n* **Notify relevant teams** (support, fraud, risk) without needing to poll the API.\n\nThe webhook payload includes the alert ID and basic fields typically available at ingestion. For full alert details\u2014which may evolve over time (e.g., matched transaction ID, refund status)\u2014you can call the **Get Alert by ID** endpoint.", "tags": [ "Webhooks Events" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the alert", "example": "687448f9dad73b4c91ba9e2b" }, "account_id": { "type": "string", "description": "The account identifier associated with the alert", "example": "66c58917f37db4bc8d455caa" }, "ext_account_id": { "type": [ "string", "null" ], "description": "The external account identifier", "example": null }, "transaction": { "type": "null", "description": "The transaction object associated with the alert", "example": null }, "created_at": { "type": "string", "description": "The date when the alert was created", "example": "2025-07-13T19:29:29.000Z" }, "network_transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "The network transaction identifier", "example": "465167618285922" }, "created_at": { "type": "string", "description": "The date when the network transaction was created", "example": "2025-06-16T00:00:00.000Z" }, "card_brand": { "type": "string", "description": "The card brand used in the transaction", "example": "visa" }, "amount": { "type": "number", "description": "The amount of the network transaction", "example": 171.59 }, "currency": { "type": "string", "description": "The currency of the network transaction", "example": "USD" }, "bin": { "type": "number", "description": "The Bank Identification Number", "example": 443603 }, "last4": { "type": "number", "description": "The last four digits of the card", "example": 720 }, "auth_code": { "type": "string", "description": "The authorization code from the transaction", "example": "016259" }, "arn": { "type": "string", "description": "The Acquirer Reference Number", "example": "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", "example": "2025-07-13T19:29:30.209Z" }, "status": { "type": "string", "enum": [ "alerted", "pending", "refund_initiated", "prevented" ], "description": "The current status of the alert", "example": "pending" }, "statement_descriptor": { "type": "string", "description": "The statement descriptor for the transaction", "example": "ELEMENTOR.COM" }, "amount": { "type": "number", "description": "The amount associated with the alert", "example": 171.59 }, "currency": { "type": "string", "description": "The currency of the alert amount", "example": "USD" }, "outcome": { "type": "string", "enum": [ "duplicate", "not_found", "prevented", "pending", "chargebacked", "previously_refunded", "error" ], "description": "The outcome of the alert", "example": "pending" }, "type": { "type": "string", "enum": [ "ethoca", "cdrn", "rdr", "fraud_warning", "other" ], "description": "The type of alert", "example": "fraud_warning" }, "reason": { "type": "string", "enum": [ "service", "fraud", "processing", "authorization" ], "description": "The reason for the alert", "example": "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": "The **Alert Transaction Linked** webhook is available exclusively for Chargeflow Alerts customers. It notifies your system in real time whenever Chargeflow successfully matches a pre-chargeback alert to a transaction in your payment processor. When this occurs, the webhook sends an HTTP POST request to your configured endpoint containing the alert ID and the matched transaction ID.\n\nMerchants can use this webhook to:\n* Trigger workflows that depend on having transaction-level data (e.g., adding customer tags, cancelling subscriptions, etc.).\n* Ingest alert-transaction data into internal systems for logging, monitoring, or case management.\n\nThe webhook payload includes the alert ID, the matched transaction ID, and basic metadata about the alert. For full alert details \u2014 which may evolve over time (e.g., outcome) \u2014 you can call the **Get Alert by ID** endpoint.", "tags": [ "Webhooks Events" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the alert", "example": "alert_123456789" }, "account_id": { "type": "string", "description": "The account identifier associated with the alert", "example": "account_987654321" }, "ext_account_id": { "type": "string", "description": "The external account identifier from the platform", "example": "platform_acc_12345" }, "transaction_id": { "type": "string", "description": "The transaction identifier associated with the alert", "example": "txn_abcdef123456" }, "created_at": { "type": "string", "description": "The date when the alert was created", "example": "2025-07-31T12:34:56Z" }, "network_transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "The network transaction identifier", "example": "net_txn_78910" }, "created_at": { "type": "string", "description": "The date when the network transaction was created", "example": "2025-07-31T12:30:00Z" }, "amount": { "type": "number", "description": "The amount of the network transaction", "example": 12500 }, "currency": { "type": "string", "description": "The currency of the network transaction amount", "example": "USD" }, "card_brand": { "type": "string", "description": "The card brand used in the transaction", "example": "Visa" }, "bin": { "type": "string", "description": "The first 6 digits of the card", "example": "411111" }, "last4": { "type": "string", "description": "The last four digits of the card used in the transaction", "example": "1111" }, "auth_code": { "type": "string", "description": "The authorization code from the transaction", "example": "AUTH1234" }, "arn": { "type": "string", "description": "The Acquirer Reference Number", "example": "ARN56789" } }, "description": "Network transaction details associated with the alert" }, "status_date": { "type": "string", "description": "The date when the status was last updated", "example": "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.", "example": "alerted" }, "statement_descriptor": { "type": "string", "description": "The statement descriptor for the transaction.", "example": "My Merchant Store" }, "amount": { "type": "number", "description": "The amount associated with the alert", "example": 12500 }, "currency": { "type": "string", "description": "The currency of the alert amount", "example": "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.", "example": "pending" }, "type": { "type": "string", "description": "The type of alert. Type can be one of the following: fraud_warning, ethoca, cdrn, rdr, other.", "example": "fraud_warning" }, "reason": { "type": "string", "description": "The reason for the alert. Reason can be one of the following: fraud, processing, authorization, service.", "example": "fraud" }, "transactionId": { "type": "string", "description": "The id of the transaction you want to update alert with", "example": "txn_abcdef123456" } }, "required": [ "id", "account_id" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK" } } } }, "alerts.updated": { "post": { "summary": "Alerts Outcome Updated Event", "description": "The **Alert Outcome Updated** webhook `(alerts.outcome.updated)` is available exclusively for Chargeflow Alerts customers. It notifies your system whenever the outcome of handling a pre-chargeback alert changes.\n\nThe **outcome** field describes the result of Chargeflow's attempt to process the alert \u2014 whether a linked transaction was found and if a refund was successfully applied. This webhook ensures your systems remain up to date as alerts move through their lifecycle.\n\nPossible outcome values: `duplicate`, `not_found`, `prevented`, `pending`, `chargebacked`, `previously_refunded`, `error` when handling the alert.\n\nThe webhook payload includes the alert ID, the updated outcome value, and supporting metadata. If further details are required, you can call the **Get Alert by ID** endpoint to retrieve the complete alert record.", "tags": [ "Webhooks Events" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the alert", "example": "687448f9dad73b4c91ba9e2b" }, "account_id": { "type": "string", "description": "The account identifier associated with the alert", "example": "66c58917f37db4bc8d455caa" }, "ext_account_id": { "type": [ "string", "null" ], "description": "The external account identifier", "example": null }, "transaction": { "type": "null", "description": "The transaction object associated with the alert", "example": null }, "created_at": { "type": "string", "description": "The date when the alert was created", "example": "2025-07-13T19:29:29.000Z" }, "network_transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "The network transaction identifier", "example": "465167618285922" }, "created_at": { "type": "string", "description": "The date when the network transaction was created", "example": "2025-06-16T00:00:00.000Z" }, "card_brand": { "type": "string", "description": "The card brand used in the transaction", "example": "visa" }, "amount": { "type": "number", "description": "The amount of the network transaction", "example": 171.59 }, "currency": { "type": "string", "description": "The currency of the network transaction", "example": "USD" }, "bin": { "type": "number", "description": "The Bank Identification Number", "example": 443603 }, "last4": { "type": "number", "description": "The last four digits of the card", "example": 720 }, "auth_code": { "type": "string", "description": "The authorization code from the transaction", "example": "016259" }, "arn": { "type": "string", "description": "The Acquirer Reference Number", "example": "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", "example": "2025-07-13T19:29:30.209Z" }, "status": { "type": "string", "enum": [ "alerted", "pending", "refund_initiated", "prevented" ], "description": "The current status of the alert", "example": "pending" }, "statement_descriptor": { "type": "string", "description": "The statement descriptor for the transaction", "example": "ELEMENTOR.COM" }, "amount": { "type": "number", "description": "The amount associated with the alert", "example": 171.59 }, "currency": { "type": "string", "description": "The currency of the alert amount", "example": "USD" }, "outcome": { "type": "string", "enum": [ "duplicate", "not_found", "prevented", "pending", "chargebacked", "previously_refunded", "error" ], "description": "The outcome of the alert", "example": "pending" }, "type": { "type": "string", "enum": [ "ethoca", "cdrn", "rdr", "fraud_warning", "other" ], "description": "The type of alert", "example": "fraud_warning" }, "reason": { "type": "string", "enum": [ "service", "fraud", "processing", "authorization" ], "description": "The reason for the alert", "example": "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. Generate it in the Developer Hub under Settings." } }, "schemas": { "BadRequestError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "invalid_request_error", "description": "The type of error", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_parameter", "missing_parameter", "invalid_format" ], "description": "Specific error code", "example": "invalid_parameter" }, "message": { "type": "string", "enum": [ "Bad Request", "Invalid request parameters" ], "description": "Human-readable error message", "example": "Bad Request" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Bad Request - The request contains invalid parameters or is malformed", "example": { "error": { "type": "invalid_request_error", "code": "invalid_parameter", "message": "Bad Request", "request_id": "req_abc123def456" } } }, "DisputeOrderLinkingForbiddenError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "permission_error", "description": "The type of error", "example": "permission_error" }, "code": { "type": "string", "enum": [ "unauthorized_dispute_access", "invalid_platform_access", "shop_not_active", "dispute_not_active" ], "description": "Specific error code", "example": "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", "example": "Unauthorized access to dispute data" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "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", "example": { "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", "example": "permission_error" }, "code": { "type": "string", "enum": [ "forbidden", "insufficient_permissions" ], "description": "Specific error code", "example": "forbidden" }, "message": { "type": "string", "enum": [ "Forbidden", "You do not have permission to access this resource" ], "description": "Human-readable error message", "example": "Forbidden" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Forbidden - The request is understood but has been refused due to insufficient permissions", "example": { "error": { "type": "permission_error", "code": "forbidden", "message": "Forbidden", "request_id": "req_abc123def456" } } }, "InternalServerError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "api_error", "description": "The type of error", "example": "api_error" }, "code": { "type": "string", "enum": [ "internal_error", "server_error", "account_creation_failed", "account_retrieval_failed", "account_update_failed" ], "description": "Specific error code", "example": "internal_error" }, "message": { "type": "string", "enum": [ "Internal server error", "An unexpected error occurred", "Failed to create account", "Failed to get accounts", "Failed to update account" ], "description": "Human-readable error message", "example": "Internal server error" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Internal Server Error - Something went wrong on our end. Please try again later.", "example": { "error": { "type": "api_error", "code": "internal_error", "message": "Internal server error", "request_id": "req_abc123def456" } } }, "UnauthorizedError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "authentication_error", "description": "The type of error", "example": "authentication_error" }, "code": { "type": "string", "enum": [ "unauthorized", "invalid_credentials", "missing_credentials" ], "description": "Specific error code", "example": "unauthorized" }, "message": { "type": "string", "enum": [ "Unauthorized access", "Authentication credentials are missing or invalid" ], "description": "Human-readable error message", "example": "Unauthorized access" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "req_abc123def456" } }, "required": [ "type", "code", "message" ], "description": "Error details" } }, "required": [ "error" ], "description": "Unauthorized - Authentication is required or has failed", "example": { "error": { "type": "authentication_error", "code": "unauthorized", "message": "Unauthorized access", "request_id": "req_abc123def456" } } }, "UpdateDisputeForbiddenError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "const": "permission_error", "description": "The type of error", "example": "permission_error" }, "code": { "type": "string", "enum": [ "unauthorized_dispute_access", "unauthorized_resource_access" ], "description": "Specific error code", "example": "unauthorized_dispute_access" }, "message": { "type": "string", "enum": [ "Unauthorized access to dispute data", "Unauthorized access to resource" ], "description": "Human-readable error message", "example": "Unauthorized access to dispute data" }, "request_id": { "type": "string", "description": "Request identifier for debugging", "example": "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", "example": { "error": { "type": "permission_error", "code": "unauthorized_dispute_access", "message": "Unauthorized access to dispute data", "request_id": "req_abc123def456" } } } } } }