{ "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": "Disputes", "description": "Disputes management endpoints" }, { "name": "Webhooks Management", "description": "Webhook configuration and management" }, { "name": "Webhooks Events", "description": "Webhook event notifications" } ], "servers": [ { "url": "https://api.chargeflow.io", "description": "Production server" } ], "paths": { "/public/2024-03-18/webhooks/{id}": { "delete": { "tags": [ "Webhooks Management" ], "summary": "Delete Webhook", "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": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the webhook was successfully deleted" } } } } } } } } }, "/public/2024-03-18/disputes": { "get": { "tags": [ "Disputes" ], "summary": "Get Disputes", "description": "Note: This endpoint is not supported for platforms. Please use the new endpoint at /public/2025-04-01/disputes", "parameters": [ { "in": "query", "name": "limit", "description": "Maximum number of disputes to return in a single response", "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 15, "description": "Maximum number of disputes to return in a single response", "example": 15 } }, { "in": "query", "name": "offset", "description": "Number of disputes to skip for pagination", "schema": { "type": "number", "minimum": 0, "default": 0, "description": "Number of disputes to skip for pagination", "example": 0 } }, { "in": "query", "name": "dateCreatedFrom", "description": "Filter disputes created after this date (ISO 8601 format)", "schema": { "type": "string", "description": "Filter disputes created after this date (ISO 8601 format)", "example": "2024-01-01T00:00:00Z" } }, { "in": "query", "name": "dateCreatedTo", "description": "Filter disputes created before this date (ISO 8601 format)", "schema": { "type": "string", "description": "Filter disputes created before this date (ISO 8601 format)", "example": "2024-03-18T23:59:59Z" } }, { "in": "query", "name": "amountFrom", "description": "Filter disputes with amount greater than or equal to this value", "schema": { "type": "number", "minimum": 0, "default": 0, "description": "Filter disputes with amount greater than or equal to this value", "example": 100 } }, { "in": "query", "name": "amountTo", "description": "Filter disputes with amount less than or equal to this value", "schema": { "type": "number", "minimum": 0, "default": 1000, "description": "Filter disputes with amount less than or equal to this value", "example": 1000 } }, { "in": "query", "name": "statusNames", "description": "Filter disputes by status (comma-separated values)", "schema": { "type": "string", "description": "Filter disputes by status (comma-separated values)", "example": "needs_response", "enum": [ "won", "lost", "refunded", "under_review", "warning_under_review", "needs_response", "warning_needs_response", "warning_awaiting_response", "awaiting_response", "warning_won", "appealable", "insured", "open", "action_required", "processing" ] } }, { "in": "query", "name": "reason", "description": "Filter disputes by reason (comma-separated values)", "schema": { "type": "string", "description": "Filter disputes by reason (comma-separated values)", "example": "fraud", "enum": [ "bank_cannot_process", "check_returned", "credit_not_processed", "customer_initiated", "debit_not_authorized", "duplicate", "general", "incorrect_account_details", "insufficient_funds", "product_not_received", "product_unacceptable", "not_received", "not_as_described", "subscription_canceled", "canceled", "duplicate_charge", "payment_by_other_means", "unrecognized", "incorrect_amount", "fraud", "canceled_recurring_billing", "other", "problem_with_remittance", "unauthorized" ] } }, { "in": "query", "name": "processorNames", "description": "Filter disputes by payment processor (comma-separated values)", "schema": { "type": "string", "description": "Filter disputes by payment processor (comma-separated values)", "example": "stripe", "enum": [ "stripe", "shopify", "klarna", "afterpay", "paypal", "adyen" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalCount": { "type": "number", "description": "Total number of disputes available in the database", "example": 100 }, "hasMore": { "type": "boolean", "description": "Indicates if there are more disputes available beyond the current response", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "chargeflowDisputeId": { "type": "string", "description": "The Chargeflow dispute id", "example": "66e6ea9ecd94925a9f8060d9" }, "dispute": { "type": "object", "properties": { "processorId": { "type": "string", "description": "The processor dispute id", "example": "PP-D-4012" }, "processor": { "type": "string", "description": "The dispute processor", "example": "paypal" }, "amount": { "type": "object", "properties": { "value": { "type": "number", "minimum": 0, "description": "The amount value", "example": 100 }, "currency": { "type": "string", "maxLength": 10, "description": "The three-letter ISO 4217 currency code represents the currency used for the amount", "example": "USD" } }, "additionalProperties": false }, "status": { "type": "string", "enum": [ "under_review", "lost", "awaiting_response", "refunded", "won", "needs_response", "appealable" ], "description": "The dispute status", "example": "won" }, "reason": { "type": "string", "enum": [ "bank_cannot_process", "check_returned", "credit_not_processed", "customer_initiated", "debit_not_authorized", "duplicate", "general", "incorrect_account_details", "insufficient_funds", "product_not_received", "product_unacceptable", "not_received", "not_as_described", "subscription_canceled", "canceled", "duplicate_charge", "payment_by_other_means", "unrecognized", "incorrect_amount", "fraud", "canceled_recurring_billing", "other", "problem_with_remittance", "unauthorized" ], "description": "The processor dispute reason", "example": "fraud" }, "responseDueDate": { "type": "string", "format": "date-time", "description": "The response due date in ISO8601 format", "example": "2021-01-01T00:00:00Z" } } }, "transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "The transaction id", "example": "123e4567-e89b-12d3-a456-426614174000" }, "creationDate": { "type": "string", "format": "date-time", "description": "The creation date of the webhook in ISO8601 format", "example": "2021-01-01T00:00:00Z" }, "source": { "type": [ "string", "null" ], "description": "The source of the transaction", "example": "stripe" }, "orderId": { "type": "string", "description": "As recieved from the payment processor, if available", "example": "4141404271159" }, "customerEmail": { "type": "string", "format": "email", "description": "The customer email, as recieved from the payment processor, if available", "example": "john@example.com" } } } } }, "description": "Array of dispute objects returned in the response" } } } } } } } }, "post": { "tags": [ "Disputes" ], "summary": "Create Dispute", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "disputeId": { "type": "string", "maxLength": 10000, "description": "The id of the dispute in your payment processor.", "example": "dp_1MykdxFtDWhhyHE1BFAV3osZ" }, "creationDate": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp - when the charge was disputed.", "example": "2022-01-01T00:00:00Z" }, "due_by": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp - when dispute evidence needs to be disputed by.", "example": "2022-01-01T00:00:00Z" }, "charge": { "type": "string", "maxLength": 10000, "description": "The id of the disputed charge in your payment processor.", "example": "ch_3MmlLrLkdIwHu7ix0snN0B15" }, "transactionId": { "type": "string", "maxLength": 128, "description": "The id of the transaction in your payment processor.", "example": "pi_1MykXhFtDWhhyHE1UjsZZ3xQ" }, "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" }, "reason": { "type": "string", "enum": [ "general", "fraudulent", "duplicate", "subscription_canceled", "product_unacceptable", "product_not_received", "unrecognized", "credit_not_processed", "incorrect_account_details", "insufficient_funds", "bank_cannot_process", "debit_not_authorized", "goods_services_returned_or_refused", "goods_services_cancelled", "transaction_amount_differs", "retrieved" ], "description": "The bank provided reason for the dispute.", "example": "general" }, "disputeAmount": { "type": "number", "minimum": 0, "description": "The amount of the disputed charge. Amounts are in cents (or other minor currency unit.)", "example": 100 }, "currency": { "type": "string", "maxLength": 10, "description": "The currency code of the disputed charge. e.g. 'USD'.", "example": "USD" }, "processor": { "type": "string", "maxLength": 128, "description": "The payment processor for the charge.", "example": "Stripe, Shopify, Braintree etc." }, "status": { "type": "string", "enum": [ "needs_response", "warning_needs_response" ], "description": "The status of the dispute.", "example": "needs_response" }, "isChargeRefundable": { "type": "boolean", "description": "Is the disputed charge refundable.", "example": true }, "addressLine1Check": { "type": "string", "enum": [ "pass", "fail", "unavailable", "unchecked" ], "description": "State of address check (if available). One of\u00a0pass,\u00a0fail,\u00a0unavailable,\u00a0unchecked.", "example": "fail" }, "addressZipCheck": { "type": "string", "enum": [ "pass", "fail", "unavailable", "unchecked" ], "description": "State of address zip check (if available). One of\u00a0pass,\u00a0fail,\u00a0unavailable,\u00a0unchecked.", "example": "pass" }, "cvcCheck": { "type": "string", "enum": [ "pass", "fail", "unavailable", "unchecked" ], "description": "State of cvc check (if available). One of\u00a0pass,\u00a0fail,\u00a0unavailable,\u00a0unchecked.", "example": "pass" }, "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "minimum": 0, "description": "The product id" }, "variantId": { "type": "number", "minimum": 0, "description": "The product variant id" }, "name": { "type": "string", "maxLength": 256, "description": "The name of the product included in the order", "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": "List of products the customer purchased." }, "pastPayments": { "type": "array", "items": { "type": "string" }, "description": "History of the customer's valid, non-disputed transactions using the same card.", "example": [ "null" ] }, "handleByChargeflow": { "type": "boolean", "description": "Whether you wish Chargeflow to handle the dispute or not. If True - Chargeflow will submit evidence for the dispute. If False - Chargeflow will not handle the dispute.", "example": true } }, "required": [ "disputeId", "creationDate", "due_by", "disputeAmount", "currency", "processor", "isChargeRefundable", "handleByChargeflow" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "The request id for tracking and auditing" } }, "required": [ "requestId" ] } } } } } } }, "/public/2024-03-18/health-check": { "get": { "tags": [ "Health Check" ], "summary": "Service Health Verification", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string", "description": "OK" } } } } } } }, "/public/2024-03-18/health-check/access-key": { "get": { "tags": [ "Health Check" ], "summary": "Validate Access Key", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/public/2024-03-18/webhooks": { "get": { "tags": [ "Webhooks Management" ], "summary": "Get All Webhooks", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the webhook was successfully registered" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The id of the webhook registration" }, "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", "description": "The URL to send the webhook to" }, "active": { "type": "boolean", "description": "Whether the webhook is active" }, "version": { "type": "string", "description": "The API version for this webhook" } } }, "description": "The list of webhook registrations" } } } } } } } }, "post": { "tags": [ "Webhooks Management" ], "summary": "Create Webhook", "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": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the webhook was successfully registered" }, "id": { "type": [ "string", "null" ], "description": "The id of the webhook registration" } } } } } } } } }, "/public/2024-03-18/disputes/{disputeId}/order": { "post": { "tags": [ "Disputes" ], "summary": "Update Dispute Order", "parameters": [ { "in": "path", "name": "disputeId", "description": "The Chargeflow dispute id", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The Chargeflow dispute id", "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": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "The request id for tracking and auditing" } } } } } } } } }, "/public/2024-03-18/disputes/{disputeId}/evidence": { "post": { "tags": [ "Disputes" ], "summary": "Upload Evidence", "parameters": [ { "in": "path", "name": "disputeId", "description": "The Chargeflow dispute id", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The Chargeflow dispute id", "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": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "description": "The request id for tracking and auditing" }, "evidenceId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The evidence id" } } } } } } } } } }, "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": { "chargeflowDisputeId": { "type": "string", "description": "The Chargeflow dispute id", "example": "66e6ea9ecd94925a9f8060d9" }, "dispute": { "type": "object", "properties": { "processorId": { "type": "string", "description": "The processor dispute id", "example": "PP-D-4012" }, "processor": { "type": "string", "description": "The dispute processor", "example": "paypal" }, "amount": { "type": "object", "properties": { "value": { "type": "number", "minimum": 0, "description": "The amount value", "example": 100 }, "currency": { "type": "string", "maxLength": 10, "description": "The three-letter ISO 4217 currency code represents the currency used for the amount", "example": "USD" } }, "additionalProperties": false }, "status": { "type": "string", "enum": [ "under_review", "lost", "awaiting_response", "refunded", "won", "needs_response", "appealable" ], "description": "The dispute status", "example": "won" }, "reason": { "type": "string", "enum": [ "bank_cannot_process", "check_returned", "credit_not_processed", "customer_initiated", "debit_not_authorized", "duplicate", "general", "incorrect_account_details", "insufficient_funds", "product_not_received", "product_unacceptable", "not_received", "not_as_described", "subscription_canceled", "canceled", "duplicate_charge", "payment_by_other_means", "unrecognized", "incorrect_amount", "fraud", "canceled_recurring_billing", "other", "problem_with_remittance", "unauthorized" ], "description": "The processor dispute reason", "example": "fraud" }, "responseDueDate": { "type": "string", "format": "date-time", "description": "The response due date in ISO8601 format", "example": "2021-01-01T00:00:00Z" } } }, "transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "The transaction id", "example": "123e4567-e89b-12d3-a456-426614174000" }, "creationDate": { "type": "string", "format": "date-time", "description": "The creation date of the webhook in ISO8601 format", "example": "2021-01-01T00:00:00Z" }, "source": { "type": [ "string", "null" ], "description": "The source of the transaction", "example": "stripe" }, "orderId": { "type": "string", "description": "As recieved from the payment processor, if available", "example": "4141404271159" }, "customerEmail": { "type": "string", "format": "email", "description": "The customer email, as recieved from the payment processor, if available", "example": "john@example.com" } } } } }, "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": "96f76c6b-1a88-4ef9-89a7-522ce542782b", "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." } } } }