Handling Refunds, Chargebacks & Disputes Programmatically¶

Overview¶

4Geeks Payments provides comprehensive tools for managing refunds, chargebacks, and disputes. As your Merchant of Record, 4Geeks handles the liability and compliance aspects, but you still need to manage the customer experience and operational workflows.

In this tutorial, you will:

Process full and partial refunds via API
Handle chargeback notifications
Manage dispute resolution workflows
Set up automated refund policies
Monitor refund and dispute metrics

Step 1: Process Refunds¶

Full Refund¶

const refund = await axios.post(
  `https://api.4geeks.io/v1/charges/${chargeId}/refunds`,
  {
    reason: 'requested_by_customer'
    // No amount = full refund
  },
  {
    headers: { 'Authorization': `Bearer ${SECRET_KEY}` }
  }
);

console.log('Refund processed:', refund.data);
// ref_xxxxxxxxxxxxx

Partial Refund¶

const partialRefund = await axios.post(
  `https://api.4geeks.io/v1/charges/${chargeId}/refunds`,
  {
    amount: 2500,  // $25.00 in cents
    reason: 'product_defective'
  },
  {
    headers: { 'Authorization': `Bearer ${SECRET_KEY}` }
  }
);

Refund Reasons¶

Reason	Description
`requested_by_customer`	Customer requested the refund
`duplicate`	Duplicate charge was made
`fraudulent`	Charge was unauthorized
`product_defective`	Product was defective or not as described
`service_not_delivered`	Service was not provided
`subscription_canceled`	Subscription was canceled

Multiple Refunds on Same Charge¶

You can process multiple partial refunds on a single charge:

// First partial refund: $25
await axios.post(`https://api.4geeks.io/v1/charges/${chargeId}/refunds`, {
  amount: 2500,
  reason: 'product_defective'
}, { headers: { 'Authorization': `Bearer ${SECRET_KEY}` } });

// Second partial refund: $15
await axios.post(`https://api.4geeks.io/v1/charges/${chargeId}/refunds`, {
  amount: 1500,
  reason: 'shipping_delay'
}, { headers: { 'Authorization': `Bearer ${SECRET_KEY}` } });

// Total refunded: $40 of original $100 charge

Step 2: Handle Chargebacks¶

Chargeback Webhook Events¶

When a chargeback occurs, you’ll receive a webhook notification:

// In your webhook handler
switch (event.type) {
  case 'chargeback.created':
    // Customer disputed the charge with their bank
    console.log('Chargeback created:', event.data);
    // Gather evidence: order details, delivery confirmation, communication
    submitChargebackEvidence(event.data.chargeback_id, evidence);
    break;

  case 'chargeback.updated':
    // Status changed (under review, evidence submitted, etc.)
    console.log('Chargeback updated:', event.data);
    break;

  case 'chargeback.won':
    // You won the dispute — funds returned
    console.log('Chargeback won:', event.data);
    updateOrderStatus(event.data.charge_id, 'chargeback_won');
    break;

  case 'chargeback.lost':
    // You lost the dispute — funds deducted
    console.log('Chargeback lost:', event.data);
    updateOrderStatus(event.data.charge_id, 'chargeback_lost');
    break;
}

Submitting Chargeback Evidence¶

const evidence = await axios.post(
  `https://api.4geeks.io/v1/chargebacks/${chargebackId}/evidence`,
  {
    // Evidence types
    product_description: 'Detailed description of the product/service',
    customer_communication: 'Email/chat logs showing customer agreement',
    delivery_confirmation: 'Tracking number and delivery confirmation',
    customer_signature: 'Signed delivery receipt (if applicable)',
    cancellation_policy: 'Link to your refund/cancellation policy',
    service_logs: 'Server logs showing service was provided',
    additional_evidence: 'Any other relevant documentation'
  },
  {
    headers: { 'Authorization': `Bearer ${SECRET_KEY}` }
  }
);

Chargeback Timeline¶

Stage	Timing	Action Required
Chargeback filed	Day 0	Receive notification, gather evidence
Evidence deadline	Day 7-14	Submit all evidence before deadline
Bank review	Day 14-30	Wait for bank decision
Decision	Day 30-60	Receive win/lost notification
Representment	Day 60-75	Optional: challenge the decision

Step 3: Manage Disputes¶

Dispute vs. Chargeback¶

Aspect	Dispute	Chargeback
Initiated by	Customer contacts you directly	Customer contacts their bank
Resolution	You resolve with customer	Bank decides the outcome
Fees	No additional fees	Chargeback fee applies
Timeline	Immediate	30-75 days
Control	Full control	Limited control

Proactive Dispute Prevention¶

// Set up automated refund for high-risk situations
const charge = await axios.get(
  `https://api.4geeks.io/v1/charges/${chargeId}`,
  { headers: { 'Authorization': `Bearer ${SECRET_KEY}` } }
);

// If customer requests refund, process it immediately
// to prevent chargeback
if (charge.data.customer_complaint === true) {
  await axios.post(
    `https://api.4geeks.io/v1/charges/${chargeId}/refunds`,
    { reason: 'requested_by_customer' },
    { headers: { 'Authorization': `Bearer ${SECRET_KEY}` } }
  );
}

Step 4: Set Up Automated Refund Policies¶

Auto-Refund Rules¶

Configure automatic refunds based on conditions:

// Example: Auto-refund if subscription canceled within trial period
const subscription = await axios.get(
  `https://api.4geeks.io/v1/subscriptions/${subId}`,
  { headers: { 'Authorization': `Bearer ${SECRET_KEY}` } }
);

if (subscription.data.trial_period && 
    subscription.data.days_active <= subscription.data.trial_period_days) {
  // Auto-refund the first charge
  await axios.post(
    `https://api.4geeks.io/v1/charges/${subscription.data.latest_charge_id}/refunds`,
    { reason: 'subscription_canceled' },
    { headers: { 'Authorization': `Bearer ${SECRET_KEY}` } }
  );
}

Refund Policy Configuration¶

Go to Payments → Settings → Refunds
Configure:
Auto-refund window: Time period for automatic refunds (e.g., 14 days)
Partial refund allowed: Yes/No
Refund processing time: Instant, 1-3 days, 5-10 days
Notification settings: Email customer on refund

Step 5: Monitor Refund & Dispute Metrics¶

Dashboard Metrics¶

Metric	Description	Target
Refund rate	% of transactions refunded	<5%
Chargeback rate	% of transactions disputed	<1%
Chargeback win rate	% of chargebacks won	>60%
Average refund amount	Mean refund value	Track trend
Refund processing time	Average time to process	<24 hours

Access Reports¶

Go to Payments → Analytics → Refunds & Disputes
View real-time dashboards
Filter by date range, product, and reason
Export reports for analysis

Best Practices¶

Refund Management¶

Process refunds quickly: Fast refunds prevent chargebacks
Communicate clearly: Tell customers when to expect their refund
Document everything: Keep records of all refund requests and processing
Analyze refund patterns: Identify products or services with high refund rates

Chargeback Prevention¶

Clear product descriptions: Avoid misleading claims
Easy refund process: Make it easier to refund than to dispute
Delivery confirmation: Always provide tracking and proof of delivery
Customer communication: Respond to complaints before they escalate

Dispute Resolution¶

Respond quickly: Address customer complaints within 24 hours
Be fair: Offer reasonable solutions before chargebacks happen
Document interactions: Keep records of all customer communications
Learn from disputes: Use dispute data to improve products and processes

What’s Next?¶

Learn about Multi-Currency Checkout
Explore Tax Compliance as MoR
Read about 3D Secure for Fraud Prevention

Need Help?¶

Documentation: docs.4geeks.io/en/payments
API Reference: docs.4geeks.io/en/api
Support: Available through the console dashboard

Still questions? Ask the community.