{ "openapi": "3.1.0", "info": { "title": "Platforms (Connect) API", "version": "1.0.0", "description": "The Chargeflow Platform API enables partners to integrate with Chargeflow and manage connected merchant accounts. Use this API to manage merchant accounts, configure integrations." }, "security": [ { "apiKey": [] } ], "tags": [ { "name": "Disputes", "description": "Disputes management endpoints" }, { "name": "Webhooks Events", "description": "Webhook event notifications" } ], "servers": [ { "url": "https://api.chargeflow.io", "description": "Production server" } ], "paths": { "/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/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" } } } } } } } } } }, "webhooks": { "integration.access.error": { "post": { "summary": "Integration Access Error Event", "tags": [ "Webhooks Events" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The webhook type", "example": "integration.access_error" }, "data": { "type": "object", "properties": { "account_id": { "type": "string", "description": "The unique Chargeflow object identifier of the account.", "example": "acct_1234567890" }, "integration_id": { "type": "string", "description": "The unique Chargeflow object identifier of the integration.", "example": "int_1234567890" }, "error_message": { "type": "string", "description": "The error message describing the access error.", "example": "Access token expired or invalid." } } }, "creationDate": { "type": "string", "format": "date-time", "description": "The creation date of the webhook in ISO8601 format", "example": "2021-01-01T00:00:00Z" }, "webhookId": { "type": "string", "format": "uuid", "default": "2ce92305-2f21-4888-a09f-3256bf7c678e", "description": "The webhook id", "example": "123e4567-e89b-12d3-a456-426614174000" } } } } } }, "responses": { "200": { "description": "OK" } } } }, "evidence.ready": { "post": { "summary": "Evidence Ready Event", "tags": [ "Webhooks Events" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow object identifier", "example": "66e6ea9ecd94925a9f8060d9" }, "disputeId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow dispute identifier", "example": "66e6ea9ecd94925a9f8060d9" }, "evidenceId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow evidence identifier", "example": "66e6ea9ecd94925a9f8060d9" }, "fileUrl": { "type": "string", "description": "The URL to the generated evidence file", "example": "https://cdn.chargeflow.io/evidence/ev_abc123456789/v2/evidence.pdf" }, "version": { "type": "number", "description": "The version number of the evidence file", "example": 1 }, "createdAt": { "type": "string", "default": "2026-05-07T16:25:29.880Z", "description": "The timestamp when the evidence was generated" } }, "required": [ "accountId", "disputeId", "evidenceId", "fileUrl", "version" ] } } } }, "responses": { "200": { "description": "OK" } } } }, "evidence.error": { "post": { "summary": "Evidence Error Event", "tags": [ "Webhooks Events" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "accountId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow object identifier", "example": "66e6ea9ecd94925a9f8060d9" }, "disputeId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow dispute identifier", "example": "66e6ea9ecd94925a9f8060d9" }, "evidenceId": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The unique Chargeflow evidence identifier", "example": "66e6ea9ecd94925a9f8060d9" }, "errorCode": { "type": "string", "description": "The error code indicating the type of failure", "example": "EVIDENCE_GENERATION_FAILED" }, "errorMessage": { "type": "string", "description": "A descriptive message explaining the error", "example": "Failed to generate evidence PDF due to missing dispute data" }, "version": { "type": "number", "description": "The version number of the evidence file", "example": 1 }, "createdAt": { "type": "string", "default": "2026-05-07T16:25:29.880Z", "description": "The timestamp when the error occurred" } }, "required": [ "accountId", "disputeId", "evidenceId", "errorCode", "errorMessage", "version" ] } } } }, "responses": { "200": { "description": "OK" } } } }, "dispute.created": { "post": { "summary": "Dispute Created Event", "tags": [ "Webhooks Events" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The webhook type", "example": "dispute.created" }, "data": { "type": "object", "properties": { "chargeflowDisputeId": { "type": "string", "description": "The Chargeflow dispute id", "example": "66e6ea9ecd94925a9f8060d9" }, "dispute": { "type": "object", "properties": { "processorId": { "type": "string", "description": "The processor dispute id", "example": "PP-D-4012" }, "processor": { "type": "string", "description": "The dispute processor", "example": "paypal" }, "amount": { "type": "object", "properties": { "value": { "type": "number", "minimum": 0, "description": "The amount value", "example": 100 }, "currency": { "type": "string", "maxLength": 10, "description": "The three-letter ISO 4217 currency code represents the currency used for the amount", "example": "USD" } }, "additionalProperties": false }, "status": { "type": "string", "enum": [ "under_review", "lost", "awaiting_response", "refunded", "won", "needs_response", "appealable" ], "description": "The dispute status", "example": "won" }, "reason": { "type": "string", "enum": [ "bank_cannot_process", "check_returned", "credit_not_processed", "customer_initiated", "debit_not_authorized", "duplicate", "general", "incorrect_account_details", "insufficient_funds", "product_not_received", "product_unacceptable", "not_received", "not_as_described", "subscription_canceled", "canceled", "duplicate_charge", "payment_by_other_means", "unrecognized", "incorrect_amount", "fraud", "canceled_recurring_billing", "other", "problem_with_remittance", "unauthorized" ], "description": "The processor dispute reason", "example": "fraud" }, "responseDueDate": { "type": "string", "format": "date-time", "description": "The response due date in ISO8601 format", "example": "2021-01-01T00:00:00Z" } } }, "transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "The transaction id", "example": "123e4567-e89b-12d3-a456-426614174000" }, "creationDate": { "type": "string", "format": "date-time", "description": "The creation date of the webhook in ISO8601 format", "example": "2021-01-01T00:00:00Z" }, "source": { "type": [ "string", "null" ], "description": "The source of the transaction", "example": "stripe" }, "orderId": { "type": "string", "description": "As recieved from the payment processor, if available", "example": "4141404271159" }, "customerEmail": { "type": "string", "format": "email", "description": "The customer email, as recieved from the payment processor, if available", "example": "john@example.com" } } }, "vendorAccountId": { "type": "string", "description": "The vendor account id", "example": "55617" }, "accountId": { "type": "string", "description": "The account id", "example": "67598401g210baf852j1f6dd" } } }, "creationDate": { "type": "string", "format": "date-time", "description": "The creation date of the webhook in ISO8601 format", "example": "2021-01-01T00:00:00Z" }, "webhookId": { "type": "string", "format": "uuid", "default": "e11e21e3-41ec-4c9d-9381-442cb6030ce1", "description": "The webhook id", "example": "123e4567-e89b-12d3-a456-426614174000" } } } } } }, "responses": { "200": { "description": "OK" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Your Chargeflow API key. Generate it in the Developer Hub under Settings." } } } }