Integration guide

Set up White-Label Connect - create your platform account, generate API keys, register webhooks, connect merchant integrations, and handle disputes.

Beta

White-Label (previously "Chargeflow Embedded") is currently in beta. Capabilities and APIs may change.

This guide walks you through the full setup process for integrating White-Label Connect into your platform.

Platform setup

Complete these three steps before building your merchant-facing integration.

Chargeflow creates your platform account. Provide your platform email address to your Chargeflow account manager to get started. Once created, your team will receive an invitation to the Chargeflow Connect UI.

Generate API keys

Log in to your Chargeflow Connect account and navigate to the Developer Hub and generate your API credentials. Keys act on your live account - see Test credentials.

Your API key is passed as the x-api-key header on all API requests. Optionally, enable HMAC Signature Validation for an additional layer of request authenticity. See the Authentication guide for instructions.

Register webhooks

Subscribe to the dispute lifecycle webhooks to receive real-time notifications:

Event	Description
`dispute.created`	Fires when a new dispute is ingested and initial enrichment is complete.

You can subscribe to additional events as your integration matures.

Building your integration

Once your platform account is configured, follow these steps to build the merchant-facing integration.

Initialize integrations

Use the Integrations API to connect each merchant's data sources to Chargeflow. Chargeflow uses these connections to automatically fetch and enrich dispute data.

Required: PSP (payment service provider). Chargeflow cannot ingest disputes without a PSP connection.

Recommended: eCommerce platform or other data enrichment sources (order management systems, CRM, shipping providers). Each additional source enriches the evidence package and improves win rates.

Terminal

POST https://api.chargeflow.io/public/2025-04-01/integrations

Refer to the Integrations API reference for supported providers and required credential fields.

Handle new disputes

Listen for the dispute.created webhook. This event fires when Chargeflow has ingested a new dispute from the merchant's PSP and completed the initial enrichment pass.

Deliveries arrive wrapped in the standard webhook envelope, with the dispute resource under data:

Response

{
  "webhookId": "wh_abc123",
  "creationDate": "2025-01-27T10:00:00Z",
  "type": "dispute.created",
  "data": {
    "...": "the dispute resource"
  }
}

The full payload schema lives in the API reference: dispute.created.

Your webhook handler should record the dispute and trigger any downstream notifications to the merchant if required by your product.

Enrich dispute data (recommended)

Use the Update Dispute API to enrich disputes with additional order or communication data before Chargeflow finalizes the evidence package. The richer the context, the more compelling the evidence.

Terminal

PATCH https://api.chargeflow.io/public/2025-04-01/disputes/{disputeId}

See the Enrich Dispute API reference for the full list of enrichable fields.

Tip

Even partial enrichment helps. If you have order data but not subscription data, send what you have. Missing pieces won't block evidence generation; the AI prioritizes whatever impactful data is available.

Track dispute progress

Use the dispute.created webhook to stay informed as disputes are ingested for your merchants.

Use these events to:

Surface dispute status in your merchant portal
Trigger notifications to merchants when Chargeflow takes action
Record outcomes for reporting and analytics

Next steps

Onboard a merchantCreate merchant accounts via API.Webhook eventsFull event reference.Monitor integration healthVerify connectivity before going live.