Chargeback Provider Integration

🧩 This guide explains how external chargeback and dispute management providers (e.g., Disputifier, Chargeblast, Chargeback911) can connect to the TagadaPay public API to automate refunds and synchronize chargeback alerts.

⚙️ Overview

TagadaPay enables seamless API-based integration for chargeback providers who need to:

Fetch merchants’ payments for alert matching
Automatically trigger refunds when alerts occur
Pass contextual metadata (alert details, provider info, reason codes) into the refund request

Each merchant can generate a unique Access Token directly from the TagadaPay Dashboard:

Dashboard → Settings → Access Tokens

This token authenticates all API requests securely.

🔐 Authentication

All endpoints require Bearer token authentication:

Authorization: Bearer <merchant_access_token>

Each merchant’s token is scoped to their own data
Providers must request the merchant to create and share this token during onboarding

💳 Endpoints Overview

Endpoint	Method	Purpose
`/api/public/v1/payments`	POST	Retrieve payments for matching alerts
`/api/public/v1/payments/refund`	POST	Process refunds automatically with metadata

📦 1️⃣ Fetch Payments

Endpoint

POST /api/public/v1/payments

Purpose
Fetch transactions for alert reconciliation or matching. Example Request

{
  "filters": {
    "processorTransactionId": "pi_3ABC123XYZ",
    "status": ["succeeded", "authorized"]
  },
  "limit": 10
}

Example Response

{
  "success": true,
  "data": [
    {
      "id": "pay_123",
      "orderId": "ord_456",
      "amount": 99.99,
      "currency": "USD",
      "status": "succeeded",
      "processorTransactionId": "pi_3ABC123XYZ",
      "customer": {
        "email": "john@example.com"
      },
      "createdAt": "2024-10-23T12:34:56Z"
    }
  ]
}

💸 2️⃣ Refund Payment

Endpoint

POST /api/public/v1/payments/refund

Purpose
Initiate a refund when a dispute alert (Ethoca, Verifi, RDR, or CDRN) is detected. Example Request

{
  "orderId": "ord_456",
  "amount": 99.99,
  "reason": "Chargeback alert - Ethoca",
  "notifyCustomer": true,
  "metadata": {
    "source": {
      "type": "alert_provider",
      "provider": "disputifier"
    },
    "dispute": {
      "alertId": "ETH-2024-123456",
      "network": "ethoca",
      "reason": "Fraudulent transaction",
      "receivedAt": "2024-10-23T10:15:00Z"
    }
  }
}

Example Response

{
  "success": true,
  "refundId": "rfnd_789",
  "orderId": "ord_456",
  "amount": 99.99,
  "status": "completed",
  "processedAt": "2024-10-23T10:16:30Z"
}

🧠 Metadata Structure

The metadata field provides context for the refund. This data is stored in the transaction record and enhances analytics.

Metadata Schema

Field	Type	Example	Description
`source.type`	string	`"alert_provider"`	Always “alert_provider” for chargeback integrations
`source.provider`	string	`"disputifier"`	Provider name (e.g., chargeblast, disputifier)
`dispute.alertId`	string	`"ETH-2024-123456"`	Unique ID of the alert
`dispute.network`	string	`"ethoca"`	Alert program name (ethoca, cdrn, rdr)
`dispute.reason`	string	`"Fraudulent transaction"`	Human-readable explanation
`dispute.receivedAt`	string	`"2024-10-23T10:15:00Z"`	ISO 8601 timestamp

🔁 Automatic vs Manual Refund Flow

⚙️ Automatic Flow

Used when the provider’s app has Auto Refund enabled. Flow:

Provider receives a chargeback alert
Provider calls TagadaPay’s /payments/refund with metadata
TagadaPay refunds automatically, updates status='refunded'
Provider is notified via 200 OK response (no webhook required)

🧩 Manual Flow

Used when the provider does not auto-refund. Flow:

Merchant manually triggers refund in TagadaPay Dashboard
Provider syncs payment data via /payments API
Provider updates alert status internally after refund is detected

🚨 Error Handling & Idempotency

Duplicate alerts should send the same orderId + alertId. TagadaPay safely ignores duplicate refund requests.

Error Codes

400: Missing fields or invalid JSON
401: Invalid or expired access token
404: Order not found
409: Transaction already refunded

Response 200 OK confirms success — no need for follow-up “outcome” call.

🪜 Step-by-Step Example Integration

Merchant Setup

Go to Dashboard → Settings → Access Tokens
Copy API key and share it with provider

Provider Setup

Add TagadaPay integration in provider’s UI 2. Enter merchant’s Access Token

Fetch Transactions

Use /payments to match alerts by transaction ID, card, and amount

Trigger Refund

When an alert is confirmed, call /payments/refund with metadata

Verification

TagadaPay refunds payment, marks as disputed, and logs metadata

💡 Common Mistakes & Best Practices

✅ Do

Always include metadata.source.type="alert_provider" and metadata.source.provider with your provider name
Use merchant-specific API keys (not global)
Keep refund payloads idempotent (same alertId)
Search for payment first using /payments endpoint
Include alert timestamp in dispute.receivedAt

❌ Don’t

Skip metadata — it breaks automatic dispute tagging
Send multiple refund calls with different IDs for the same alert
Use sandbox token in production environment
Hard-code transaction ID formats (support multiple processors)

🔧 Complete Example Code

Node.js Implementation

const axios = require('axios');

async function handleChargebackAlert(alert, merchantApiToken) {
  const baseURL = 'https://app.tagadapay.com';

  // Step 1: Search for payment
  const searchResponse = await axios.post(
    `${baseURL}/api/public/v1/payments`,
    {
      filters: {
        processorTransactionId: alert.transactionId,
        status: ['succeeded', 'authorized'],
      },
      limit: 1,
    },
    {
      headers: {
        Authorization: `Bearer ${merchantApiToken}`,
        'Content-Type': 'application/json',
      },
    },
  );

  if (!searchResponse.data.success || searchResponse.data.data.length === 0) {
    console.log('No matching payment found');
    return { matched: false };
  }

  const payment = searchResponse.data.data[0];

  // Step 2: Process refund with metadata
  const refundResponse = await axios.post(
    `${baseURL}/api/public/v1/payments/refund`,
    {
      orderId: payment.orderId,
      amount: payment.amount,
      reason: `Chargeback alert - ${alert.network}`,
      notifyCustomer: true,
      metadata: {
        source: {
          type: 'alert_provider',
          provider: 'your-provider-name',
        },
        dispute: {
          alertId: alert.id,
          network: alert.network,
          reason: alert.reason,
          receivedAt: alert.receivedAt,
        },
      },
    },
    {
      headers: {
        Authorization: `Bearer ${merchantApiToken}`,
        'Content-Type': 'application/json',
      },
    },
  );

  if (refundResponse.data.success) {
    console.log('Refund successful:', refundResponse.data.refundId);
    return {
      matched: true,
      refunded: true,
      refundId: refundResponse.data.refundId,
    };
  } else {
    console.error('Refund failed:', refundResponse.data.error);
    return {
      matched: true,
      refunded: false,
      error: refundResponse.data.error,
    };
  }
}

// Usage
const alert = {
  id: 'ETH-2024-123456',
  transactionId: 'pi_3ABC123XYZ',
  network: 'ethoca',
  reason: 'Fraudulent transaction',
  receivedAt: '2024-10-23T10:15:00Z',
};

handleChargebackAlert(alert, 'sk_live_abc123...');

⚠️ Internal Notes

This document is for internal and partner developers only.
Public release requires approval from the TagadaPay Engineering Team.Path: /internal/chargeback-provider-integration
Visibility: Internal → “Developer Tools” section

✅ Quick Reference Summary

🔑 Authenticate:

Authorization: Bearer <merchant_access_token>

📥 Fetch Payments:

POST /api/public/v1/payments

💸 Send Refund:

POST /api/public/v1/payments/refund

Include full metadata with source.type="alert_provider", source.provider, and dispute objects. 🎯 Result:
TagadaPay auto-handles refund + dispute marking + analytics tracking.

🧠 With this single integration model, any chargeback provider can connect to TagadaPay in under one day — securely, consistently, and with full refund automation support.

Plugin SDK

Plugin CLI

Integration Guides

⚙️ Overview

🔐 Authentication

💳 Endpoints Overview

📦 1️⃣ Fetch Payments

💸 2️⃣ Refund Payment

🧠 Metadata Structure

Metadata Schema

🔁 Automatic vs Manual Refund Flow

⚙️ Automatic Flow

🧩 Manual Flow

🚨 Error Handling & Idempotency

Error Codes

🪜 Step-by-Step Example Integration

💡 Common Mistakes & Best Practices

✅ Do

❌ Don’t

🔧 Complete Example Code

Node.js Implementation

⚠️ Internal Notes

✅ Quick Reference Summary

Plugin SDK

Plugin CLI

Integration Guides

​⚙️ Overview

​🔐 Authentication

​💳 Endpoints Overview

​📦 1️⃣ Fetch Payments

​💸 2️⃣ Refund Payment

​🧠 Metadata Structure

​Metadata Schema

​🔁 Automatic vs Manual Refund Flow

​⚙️ Automatic Flow

​🧩 Manual Flow

​🚨 Error Handling & Idempotency

​Error Codes

​🪜 Step-by-Step Example Integration

​💡 Common Mistakes & Best Practices

​✅ Do

​❌ Don’t

​🔧 Complete Example Code

​Node.js Implementation

​⚠️ Internal Notes

​✅ Quick Reference Summary

⚙️ Overview

🔐 Authentication

💳 Endpoints Overview

📦 1️⃣ Fetch Payments

💸 2️⃣ Refund Payment

🧠 Metadata Structure

Metadata Schema

🔁 Automatic vs Manual Refund Flow

⚙️ Automatic Flow

🧩 Manual Flow

🚨 Error Handling & Idempotency

Error Codes

🪜 Step-by-Step Example Integration

💡 Common Mistakes & Best Practices

✅ Do

❌ Don’t

🔧 Complete Example Code

Node.js Implementation

⚠️ Internal Notes

✅ Quick Reference Summary