{ "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", "description": "The Delete Webhook API allows you to delete a webhook registration by providing the webhook ID.", "parameters": [ { "in": "path", "name": "id", "description": "The Webhook id to delete", "schema": { "type": "string", "description": "The Webhook id to delete", "examples": ["*%23http%3A%2F%2Ftest.com%2Fwebhook"] }, "required": true, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "responses": { "200": { "description": "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", "examples": [15] }, "example": "10" }, { "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", "examples": [0] }, "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)", "examples": ["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)", "examples": ["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", "examples": [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", "examples": [1000] } }, { "in": "query", "name": "statusNames", "description": "Filter disputes by status (comma-separated values)", "schema": { "type": "string", "description": "Filter disputes by status (comma-separated values)", "examples": ["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)", "examples": ["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)", "examples": ["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", "examples": [100] }, "hasMore": { "type": "boolean", "description": "Indicates if there are more disputes available beyond the current response", "examples": [true] }, "data": { "type": "array", "items": { "type": "object", "properties": { "chargeflowDisputeId": { "type": "string", "description": "The Chargeflow dispute id", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "dispute": { "type": "object", "properties": { "processorId": { "type": "string", "description": "The processor dispute id", "examples": ["PP-D-4012"] }, "processor": { "type": "string", "description": "The dispute processor", "examples": ["paypal"] }, "amount": { "type": "object", "properties": { "value": { "type": "number", "minimum": 0, "description": "The amount value", "examples": [100] }, "currency": { "type": "string", "maxLength": 10, "description": "The three-letter ISO 4217 currency code represents the currency used for the amount", "examples": ["USD"] } }, "additionalProperties": false }, "status": { "type": "string", "enum": [ "under_review", "lost", "awaiting_response", "refunded", "won", "needs_response", "appealable" ], "description": "The dispute status", "examples": ["won"] }, "reason": { "type": "string", "enum": [ "bank_cannot_process", "check_returned", "credit_not_processed", "customer_initiated", "debit_not_authorized", "duplicate", "general", "incorrect_account_details", "insufficient_funds", "product_not_received", "product_unacceptable", "not_received", "not_as_described", "subscription_canceled", "canceled", "duplicate_charge", "payment_by_other_means", "unrecognized", "incorrect_amount", "fraud", "canceled_recurring_billing", "other", "problem_with_remittance", "unauthorized" ], "description": "The processor dispute reason", "examples": ["fraud"] }, "responseDueDate": { "type": "string", "format": "date-time", "description": "The response due date in ISO8601 format", "examples": ["2021-01-01T00:00:00Z"] } } }, "transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "The transaction id", "examples": ["123e4567-e89b-12d3-a456-426614174000"] }, "creationDate": { "type": "string", "format": "date-time", "description": "The creation date of the webhook in ISO8601 format", "examples": ["2021-01-01T00:00:00Z"] }, "source": { "type": ["string", "null"], "description": "The source of the transaction", "examples": ["stripe"] }, "orderId": { "type": "string", "description": "As recieved from the payment processor, if available", "examples": ["4141404271159"] }, "customerEmail": { "type": "string", "format": "email", "description": "The customer email, as recieved from the payment processor, if available", "examples": ["john@example.com"] } } } } }, "description": "Array of dispute objects returned in the response" } } } } } } } }, "post": { "tags": ["Disputes"], "summary": "Create Dispute", "description": "Creates a dispute in Chargeflow that can either be viewed through the Chargeflow platform or managed by Chargeflow.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "disputeId": { "type": "string", "maxLength": 10000, "description": "The id of the dispute in your payment processor.", "examples": ["dp_1MykdxFtDWhhyHE1BFAV3osZ"] }, "creationDate": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp - when the charge was disputed.", "examples": ["2022-01-01T00:00:00Z"] }, "due_by": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp - when dispute evidence needs to be disputed by.", "examples": ["2022-01-01T00:00:00Z"] }, "charge": { "type": "string", "maxLength": 10000, "description": "The id of the disputed charge in your payment processor.", "examples": ["ch_3MmlLrLkdIwHu7ix0snN0B15"] }, "transactionId": { "type": "string", "maxLength": 128, "description": "The id of the transaction in your payment processor.", "examples": ["pi_1MykXhFtDWhhyHE1UjsZZ3xQ"] }, "transactionDate": { "type": "string", "format": "date-time", "description": "The date and time when the transaction was created, in ISO 8601 format", "examples": ["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.", "examples": ["general"] }, "disputeAmount": { "type": "number", "minimum": 0, "description": "The amount of the disputed charge. Amounts are in cents (or other minor currency unit.)", "examples": [100] }, "currency": { "type": "string", "maxLength": 10, "description": "The currency code of the disputed charge. e.g. 'USD'.", "examples": ["USD"] }, "processor": { "type": "string", "maxLength": 128, "description": "The payment processor for the charge.", "examples": ["Stripe, Shopify, Braintree etc."] }, "status": { "type": "string", "enum": ["needs_response", "warning_needs_response"], "description": "The status of the dispute.", "examples": ["needs_response"] }, "isChargeRefundable": { "type": "boolean", "description": "Is the disputed charge refundable.", "examples": [true] }, "addressLine1Check": { "type": "string", "enum": ["pass", "fail", "unavailable", "unchecked"], "description": "State of address check (if available). One of pass, fail, unavailable, unchecked.", "examples": ["fail"] }, "addressZipCheck": { "type": "string", "enum": ["pass", "fail", "unavailable", "unchecked"], "description": "State of address zip check (if available). One of pass, fail, unavailable, unchecked.", "examples": ["pass"] }, "cvcCheck": { "type": "string", "enum": ["pass", "fail", "unavailable", "unchecked"], "description": "State of cvc check (if available). One of pass, fail, unavailable, unchecked.", "examples": ["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", "examples": ["Product Name"] }, "price": { "type": "object", "properties": { "value": { "type": "number", "minimum": 0, "description": "The amount value", "examples": [100] }, "currency": { "type": "string", "maxLength": 10, "description": "The three-letter ISO 4217 currency code represents the currency used for the amount", "examples": ["USD"] } }, "additionalProperties": false }, "imageUrl": { "type": "string", "format": "uri", "description": "A publicly available URL leading to an image of the product", "examples": ["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", "examples": [100] }, "currency": { "type": "string", "maxLength": 10, "description": "The three-letter ISO 4217 currency code represents the currency used for the amount", "examples": ["USD"] } }, "additionalProperties": false, "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.", "examples": [["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.", "examples": [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", "description": "Confirms the Chargeflow API is reachable and responding. Use it as a connectivity check before you start integrating.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string", "description": "OK" } } } } } } }, "/public/2024-03-18/health-check/access-key": { "get": { "tags": ["Health Check"], "summary": "Validate Access Key", "description": "Confirms your API key is valid and authorized to call the Chargeflow API.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string" } } } } } } }, "/public/2024-03-18/webhooks": { "get": { "tags": ["Webhooks Management"], "summary": "Get All Webhooks", "description": "The Get All Webhooks API allows you to retrieve all webhook registrations for a specific chargeflowId.", "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", "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": "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}/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 Chargeflow dispute id", "schema": { "type": "string", "pattern": "^[0-9a-fA-F]{24}$", "description": "The Chargeflow dispute id", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "required": true, "example": "66e6ea9ecd94925a9f8060d9" } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "oneOf": [ { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "evidenceUploadCategory": { "type": "string", "enum": ["tracking_information", "customer_communication", "invoice"], "description": "The category of the evidence upload", "examples": ["invoice"] } }, "required": ["file", "evidenceUploadCategory"], "additionalProperties": false }, { "type": "object", "properties": { "file": { "type": "string", "format": "binary" }, "evidenceUploadCategory": { "type": "string", "enum": ["additional_evidence", "additional_notes"], "description": "The category of the evidence upload", "examples": ["additional_evidence"] }, "content": { "type": "string", "description": "The content of the evidence. Only required with `additional_notes` and `additional_evidence` categories", "examples": ["Product picture"] } }, "required": ["file", "evidenceUploadCategory", "content"], "additionalProperties": false } ] } } } }, "responses": { "200": { "description": "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", "examples": ["dispute.created"] }, "data": { "type": "object", "properties": { "chargeflowDisputeId": { "type": "string", "description": "The Chargeflow dispute id", "examples": ["66e6ea9ecd94925a9f8060d9"] }, "dispute": { "type": "object", "properties": { "processorId": { "type": "string", "description": "The processor dispute id", "examples": ["PP-D-4012"] }, "processor": { "type": "string", "description": "The dispute processor", "examples": ["paypal"] }, "amount": { "type": "object", "properties": { "value": { "type": "number", "minimum": 0, "description": "The amount value", "examples": [100] }, "currency": { "type": "string", "maxLength": 10, "description": "The three-letter ISO 4217 currency code represents the currency used for the amount", "examples": ["USD"] } }, "additionalProperties": false }, "status": { "type": "string", "enum": [ "under_review", "lost", "awaiting_response", "refunded", "won", "needs_response", "appealable" ], "description": "The dispute status", "examples": ["won"] }, "reason": { "type": "string", "enum": [ "bank_cannot_process", "check_returned", "credit_not_processed", "customer_initiated", "debit_not_authorized", "duplicate", "general", "incorrect_account_details", "insufficient_funds", "product_not_received", "product_unacceptable", "not_received", "not_as_described", "subscription_canceled", "canceled", "duplicate_charge", "payment_by_other_means", "unrecognized", "incorrect_amount", "fraud", "canceled_recurring_billing", "other", "problem_with_remittance", "unauthorized" ], "description": "The processor dispute reason", "examples": ["fraud"] }, "responseDueDate": { "type": "string", "format": "date-time", "description": "The response due date in ISO8601 format", "examples": ["2021-01-01T00:00:00Z"] } } }, "transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "The transaction id", "examples": ["123e4567-e89b-12d3-a456-426614174000"] }, "creationDate": { "type": "string", "format": "date-time", "description": "The creation date of the webhook in ISO8601 format", "examples": ["2021-01-01T00:00:00Z"] }, "source": { "type": ["string", "null"], "description": "The source of the transaction", "examples": ["stripe"] }, "orderId": { "type": "string", "description": "As recieved from the payment processor, if available", "examples": ["4141404271159"] }, "customerEmail": { "type": "string", "format": "email", "description": "The customer email, as recieved from the payment processor, if available", "examples": ["john@example.com"] } } } } }, "creationDate": { "type": "string", "format": "date-time", "description": "The creation date of the webhook in ISO8601 format", "examples": ["2021-01-01T00:00:00Z"] }, "webhookId": { "type": "string", "format": "uuid", "default": "96f76c6b-1a88-4ef9-89a7-522ce542782b", "description": "The webhook id", "examples": ["123e4567-e89b-12d3-a456-426614174000"] } } } } } }, "responses": { "200": { "description": "OK" } } } }, "alerts.created": { "post": { "summary": "Alerts Created Event", "description": "Fires when a new pre-chargeback alert is created for your account. The payload carries the alert ID and key metadata.", "tags": ["Webhooks Events"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the alert", "examples": ["687448f9dad73b4c91ba9e2b"] }, "account_id": { "type": "string", "description": "The account identifier associated with the alert", "examples": ["66c58917f37db4bc8d455caa"] }, "ext_account_id": { "type": ["string", "null"], "description": "The external account identifier", "examples": [null] }, "transaction": { "type": "null", "description": "The transaction object associated with the alert", "examples": [null] }, "created_at": { "type": "string", "description": "The date when the alert was created", "examples": ["2025-07-13T19:29:29.000Z"] }, "network_transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "The network transaction identifier", "examples": ["465167618285922"] }, "created_at": { "type": "string", "description": "The date when the network transaction was created", "examples": ["2025-06-16T00:00:00.000Z"] }, "card_brand": { "type": "string", "description": "The card brand used in the transaction", "examples": ["visa"] }, "amount": { "type": "number", "description": "The amount of the network transaction", "examples": [171.59] }, "currency": { "type": "string", "description": "The currency of the network transaction", "examples": ["USD"] }, "bin": { "type": "number", "description": "The Bank Identification Number", "examples": [443603] }, "last4": { "type": "number", "description": "The last four digits of the card", "examples": [720] }, "auth_code": { "type": "string", "description": "The authorization code from the transaction", "examples": ["016259"] }, "arn": { "type": "string", "description": "The Acquirer Reference Number", "examples": ["24000775168100002149105"] } }, "required": [ "id", "created_at", "card_brand", "amount", "currency", "bin", "last4", "auth_code", "arn" ], "description": "Network transaction details" }, "status_date": { "type": "string", "description": "The date when the status was last updated", "examples": ["2025-07-13T19:29:30.209Z"] }, "status": { "type": "string", "enum": ["alerted", "pending", "refund_initiated", "prevented"], "description": "The current status of the alert", "examples": ["pending"] }, "statement_descriptor": { "type": "string", "description": "The statement descriptor for the transaction", "examples": ["ELEMENTOR.COM"] }, "amount": { "type": "number", "description": "The amount associated with the alert", "examples": [171.59] }, "currency": { "type": "string", "description": "The currency of the alert amount", "examples": ["USD"] }, "outcome": { "type": "string", "enum": [ "duplicate", "not_found", "prevented", "pending", "chargebacked", "previously_refunded", "error" ], "description": "The outcome of the alert", "examples": ["pending"] }, "type": { "type": "string", "enum": ["ethoca", "cdrn", "rdr", "fraud_warning", "other"], "description": "The type of alert", "examples": ["fraud_warning"] }, "reason": { "type": "string", "enum": ["service", "fraud", "processing", "authorization"], "description": "The reason for the alert", "examples": ["fraud"] } }, "required": [ "id", "account_id", "ext_account_id", "created_at", "network_transaction", "status_date", "status", "statement_descriptor", "amount", "currency", "outcome", "type", "reason" ] } } } }, "responses": { "200": { "description": "OK" } } } }, "alerts.transaction.linked": { "post": { "summary": "Alert Transaction Linked Event", "description": "Fires when Chargeflow matches a pre-chargeback alert to a transaction in your payment processor. The payload carries the alert ID and the matched transaction ID.", "tags": ["Webhooks Events"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the alert", "examples": ["alert_123456789"] }, "account_id": { "type": "string", "description": "The account identifier associated with the alert", "examples": ["account_987654321"] }, "ext_account_id": { "type": "string", "description": "The external account identifier from the platform", "examples": ["platform_acc_12345"] }, "transaction_id": { "type": "string", "description": "The transaction identifier associated with the alert", "examples": ["txn_abcdef123456"] }, "created_at": { "type": "string", "description": "The date when the alert was created", "examples": ["2025-07-31T12:34:56Z"] }, "network_transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "The network transaction identifier", "examples": ["net_txn_78910"] }, "created_at": { "type": "string", "description": "The date when the network transaction was created", "examples": ["2025-07-31T12:30:00Z"] }, "amount": { "type": "number", "description": "The amount of the network transaction", "examples": [12500] }, "currency": { "type": "string", "description": "The currency of the network transaction amount", "examples": ["USD"] }, "card_brand": { "type": "string", "description": "The card brand used in the transaction", "examples": ["Visa"] }, "bin": { "type": "string", "description": "The first 6 digits of the card", "examples": ["411111"] }, "last4": { "type": "string", "description": "The last four digits of the card used in the transaction", "examples": ["1111"] }, "auth_code": { "type": "string", "description": "The authorization code from the transaction", "examples": ["AUTH1234"] }, "arn": { "type": "string", "description": "The Acquirer Reference Number", "examples": ["ARN56789"] } }, "description": "Network transaction details associated with the alert" }, "status_date": { "type": "string", "description": "The date when the status was last updated", "examples": ["2025-07-31T13:00:00Z"] }, "status": { "type": "string", "description": "The current status of the alert. Status can be one of the following: alerted, pending, refund_initiated, prevented.", "examples": ["alerted"] }, "statement_descriptor": { "type": "string", "description": "The statement descriptor for the transaction.", "examples": ["My Merchant Store"] }, "amount": { "type": "number", "description": "The amount associated with the alert", "examples": [12500] }, "currency": { "type": "string", "description": "The currency of the alert amount", "examples": ["USD"] }, "outcome": { "type": "string", "description": "The outcome of the alert. Outcome can be one of the following: duplicate, not_found, prevented, pending, chargebacked, previously_refunded, error.", "examples": ["pending"] }, "type": { "type": "string", "description": "The type of alert. Type can be one of the following: fraud_warning, ethoca, cdrn, rdr, other.", "examples": ["fraud_warning"] }, "reason": { "type": "string", "description": "The reason for the alert. Reason can be one of the following: fraud, processing, authorization, service.", "examples": ["fraud"] }, "transactionId": { "type": "string", "description": "The id of the transaction you want to update alert with", "examples": ["txn_abcdef123456"] } }, "required": ["id", "account_id"], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK" } } } }, "alerts.updated": { "post": { "summary": "Alerts Outcome Updated Event", "description": "Fires when the outcome of a pre-chargeback alert changes. The payload carries the alert ID, the new outcome, and supporting metadata.", "tags": ["Webhooks Events"], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the alert", "examples": ["687448f9dad73b4c91ba9e2b"] }, "account_id": { "type": "string", "description": "The account identifier associated with the alert", "examples": ["66c58917f37db4bc8d455caa"] }, "ext_account_id": { "type": ["string", "null"], "description": "The external account identifier", "examples": [null] }, "transaction": { "type": "null", "description": "The transaction object associated with the alert", "examples": [null] }, "created_at": { "type": "string", "description": "The date when the alert was created", "examples": ["2025-07-13T19:29:29.000Z"] }, "network_transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "The network transaction identifier", "examples": ["465167618285922"] }, "created_at": { "type": "string", "description": "The date when the network transaction was created", "examples": ["2025-06-16T00:00:00.000Z"] }, "card_brand": { "type": "string", "description": "The card brand used in the transaction", "examples": ["visa"] }, "amount": { "type": "number", "description": "The amount of the network transaction", "examples": [171.59] }, "currency": { "type": "string", "description": "The currency of the network transaction", "examples": ["USD"] }, "bin": { "type": "number", "description": "The Bank Identification Number", "examples": [443603] }, "last4": { "type": "number", "description": "The last four digits of the card", "examples": [720] }, "auth_code": { "type": "string", "description": "The authorization code from the transaction", "examples": ["016259"] }, "arn": { "type": "string", "description": "The Acquirer Reference Number", "examples": ["24000775168100002149105"] } }, "required": [ "id", "created_at", "card_brand", "amount", "currency", "bin", "last4", "auth_code", "arn" ], "description": "Network transaction details" }, "status_date": { "type": "string", "description": "The date when the status was last updated", "examples": ["2025-07-13T19:29:30.209Z"] }, "status": { "type": "string", "enum": ["alerted", "pending", "refund_initiated", "prevented"], "description": "The current status of the alert", "examples": ["pending"] }, "statement_descriptor": { "type": "string", "description": "The statement descriptor for the transaction", "examples": ["ELEMENTOR.COM"] }, "amount": { "type": "number", "description": "The amount associated with the alert", "examples": [171.59] }, "currency": { "type": "string", "description": "The currency of the alert amount", "examples": ["USD"] }, "outcome": { "type": "string", "enum": [ "duplicate", "not_found", "prevented", "pending", "chargebacked", "previously_refunded", "error" ], "description": "The outcome of the alert", "examples": ["pending"] }, "type": { "type": "string", "enum": ["ethoca", "cdrn", "rdr", "fraud_warning", "other"], "description": "The type of alert", "examples": ["fraud_warning"] }, "reason": { "type": "string", "enum": ["service", "fraud", "processing", "authorization"], "description": "The reason for the alert", "examples": ["fraud"] } }, "required": [ "id", "account_id", "ext_account_id", "created_at", "network_transaction", "status_date", "status", "statement_descriptor", "amount", "currency", "outcome", "type", "reason" ] } } } }, "responses": { "200": { "description": "OK" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Your Chargeflow API key, sent on every request. Generate one in the [Chargeflow App](https://app.chargeflow.io/settings#developers), or see [API keys](/docs/reference/api-fundamentals/test-credentials)." } } } }