Chargebacks Page

View, search, and manage payment disputes from PayArc with automatic order linkage and Signifyd integration.

Overview

The Chargebacks page provides a centralized view of all payment disputes (chargebacks) received from PayArc. The system automatically:

• Receives dispute webhooks from PayArc
• Links disputes to NMI transactions and orders
• Creates Signifyd dispute cases for fraud analysis
• Tracks processing status and resolution

Access: GSM Middleware → Chargebacks (menu position 3)

Permission Required: manage_gsm_middleware

---

Interface Elements

Header Search & Filters

*/}

Search Box

Purpose: Find specific disputes quickly

Searches across:

• Case ID (PayArc dispute identifier)
• Order number (your order number)
• Transaction ID (NMI or PayArc transaction ID)

Usage:

1. Type search term in "Search" field
2. Click "Search" button or press Enter
3. Results update immediately

Example: Search for "123456" to find order, case, or transaction

---

Status Filter

Purpose: Filter disputes by processing status

Available statuses:

Status	Description	Use Case
All Statuses	Show all disputes	Default view
Pending	Waiting for processing	Disputes just received
Processing	Currently being processed	In-progress linkage/Signifyd
Completed	Successfully processed	Linked and resolved
Failed	Processing failed	Requires manual review

Usage: Select status from dropdown to filter table

---

Chargebacks Table

Columns:

Column	Description	Example
Case ID	PayArc dispute case identifier	DSP123456
Order Number	Linked order number	100012345
Amount	Dispute amount	$149.99
Status	Processing status badge	🟢 Completed
Reason	Dispute reason code	10.4
Received At	When webhook was received	2024-12-15 10:30 AM
Completed At	When processing completed	2024-12-15 10:31 AM
Actions	View details button	View Details

Status Badge Colors:

• 🟢 Green — Completed
• 🔵 Blue — Processing
• ⚫ Gray — Pending
• 🔴 Red — Failed

---

Pagination Controls

Bottom of table:

• "Showing X of Y chargebacks" — Result count
• Previous / Next buttons — Navigate pages
• "Page X of Y" — Current page indicator

Page Size: 50 chargebacks per page (default)

---

Chargeback Details Modal

Open: Click "View Details" button for any chargeback

Basic Information Section

Fields displayed:

Field	Description	Example
Case ID	PayArc case identifier	DSP123456
Case Number	PayArc case number	CB-2024-001
Processing Status	Current status badge	🟢 Completed
Amount	Disputed amount	$149.99
Reason	Reason code and description	10.4 - Fraud
Order Number	Linked order	100012345
Match Strategy	How order was found	nmi_transaction_id
NMI Transaction ID	NMI reference	3456789012
Signifyd Case ID	Signifyd case number	987654321

---

Action Log Section

Purpose: Audit trail of all processing steps

Shows:

• Webhook received
• Order linkage attempt
• NMI API query
• Signifyd case creation
• Success/failure events

Example log entries:

Timestamp	Action	Details
2024-12-15 10:30:15	webhook_received	PayArc dispute webhook received
2024-12-15 10:30:16	searching_nmi	Querying NMI for transaction
2024-12-15 10:30:17	order_linked	Found order 100012345
2024-12-15 10:30:18	signifyd_created	Created Signifyd case 987654321
2024-12-15 10:30:20	completed	Processing completed successfully

---

Error Section

Displays if:

• Order linkage fails
• NMI API errors
• Signifyd API errors
• Database errors

Error message includes:

• What failed
• Why it failed
• Suggested remediation

Example:

🔴 Failed to link order: No NMI transaction found matching
transaction ID 3456789012. Check NMI credentials in Merchant Accounts.

---

Common Workflows

Reviewing New Disputes

Goal: Process incoming dispute notifications

Steps:

1. Navigate to Chargebacks page
2. Set status filter to "Pending"
3. Click "View Details" for each pending dispute
4. Verify order linkage is correct
5. Check if Signifyd case was created
6. Review action log for any issues

Expected outcome: All pending disputes move to "Completed" status

---

Finding a Specific Dispute

Goal: Look up dispute details by case ID or order

Steps:

1. Enter case ID or order number in search box
2. Press Enter or click "Search"
3. View results in table
4. Click "View Details" for full information

Example: Search "DSP123456" to find dispute case

---

Investigating Failed Disputes

Goal: Resolve disputes that couldn't auto-process

Steps:

1. Set status filter to "Failed"
2. Click "View Details" on failed dispute
3. Read error message carefully
4. Check action log for where it failed
5. Fix underlying issue (credentials, order data, etc.)
6. Re-process if possible or handle manually

Common failure reasons:

• NMI credentials invalid
• Order not found in database
• Signifyd API rate limit
• Network timeout

---

Monthly Dispute Review

Goal: Analyze dispute trends and counts

Steps:

1. Set status to "All Statuses"
2. Note total count at bottom of page
3. Review common reason codes
4. Click through disputes to identify patterns
5. Check "Completed At" dates to verify timely processing

Metrics to track:

• Total disputes per month
• Average processing time
• Success rate (Completed vs Failed)
• Most common reason codes

---

Technical Details

Data Source

Table: rm_payarc_dispute_linkages

Populated by:

• PayArc dispute webhooks (received in rm_webhooks table)
• Queue worker processes webhooks
• Chargeback processor links orders and creates Signifyd cases

Related Documentation:

• Database Schema - rm_payarc_dispute_linkages
• PayArc Webhooks

---

API Endpoint

GET /wp-json/gsm-middleware/v1/chargebacks

Query Parameters:

Parameter	Type	Description	Example
page	int	Page number (1-based)	1
per_page	int	Results per page (max 100)	50
search	string	Search term	DSP123456
status	string	Filter by status	completed

Response:

{
  "items": [
    {
      "id": 123,
      "case_id": "DSP123456",
      "case_number": "CB-2024-001",
      "order_number": "100012345",
      "amount": "149.99",
      "processing_status": "completed",
      "reason_code": "10.4",
      "reason_desc": "Fraud",
      "nmi_transaction_id": "3456789012",
      "signifyd_case_id": "987654321",
      "match_strategy": "nmi_transaction_id",
      "webhook_received_at": "2024-12-15 10:30:15",
      "completed_at": "2024-12-15 10:30:20",
      "error_message": null,
      "action_log": [...]
    }
  ],
  "total": 42,
  "page": 1,
  "per_page": 50
}

Controller: src/API/Chargebacks_REST_Controller.php

---

React Component

Component: assets/js/components/ChargebacksViewer.jsx

State Management:

• Uses WordPress @wordpress/element hooks
• Fetches via @wordpress/api-fetch
• Client-side pagination and filtering

Key Features:

• Real-time search with Enter key support
• Status filtering with immediate update
• Paginated results (50 per page)
• Details modal with action log
• Status badge color coding
• Currency and date formatting

---

Troubleshooting

"No chargebacks found" with Pending Filter

Cause: All disputes processed successfully

Solution: This is expected! Switch to "All Statuses" to see historical disputes.

---

Order Number Shows "-" (Dash)

Cause: Dispute couldn't be linked to an order

Solution:

1. Click "View Details"
2. Check error message
3. Verify NMI credentials in Merchant Accounts
4. Confirm orders are being synced to database
5. Check action log for specific failure point

---

Status Stuck on "Processing"

Cause: Queue worker may be down or stuck

Solution:

1. Check WP-Cron is running: wp cron event list
2. Check queue worker status in Control Panel
3. Review debug.log for errors:

   tail -100 wp-content/debug.log | grep chargeback

4. Manually trigger queue: wp gsm process-queue

---

Signifyd Case ID Missing

Cause: Signifyd credentials not configured or API error

Solution:

1. Verify Signifyd enabled in site settings
2. Check Signifyd API key and team ID
3. Review action log in details modal
4. Check error message for API response
5. Verify Signifyd account has active subscription

---

Wrong Order Linked

Cause: Multiple orders with same transaction ID or matching collision

Solution:

1. Click "View Details"
2. Note "Match Strategy" field
3. Verify NMI transaction ID in NMI dashboard
4. Check if multiple orders share same trans_id
5. Manually correct linkage in database if needed:

   UPDATE rm_payarc_dispute_linkages
   SET order_number = 'CORRECT_ORDER'
   WHERE case_id = 'DSP123456';

---

Related Documentation

• Merchant Accounts - Configure NMI, Signifyd credentials
• Database Schema - Table structure
• PayArc Webhooks - Webhook processing

---

Best Practices

1. Check daily for new pending disputes during business hours
2. Review failed disputes within 24 hours to ensure timely processing
3. Monitor trends - increasing disputes may indicate fraud or policy issues
4. Verify Signifyd integration - ensures fraud analysis for every dispute
5. Keep NMI credentials current - expired keys prevent order linkage
6. Archive old disputes - Consider data retention policy after 1-2 years