Unlinked Refunds
Unlinked refunds let merchants credit a customer's card directly without referencing a previous payment. This is useful for goodwill credits, promotional refunds, or when a linked refund cannot be processed due to payment unavailability or expiration.
To integrate Unlinked Refunds, follow the Integration Guide for step-by-step instructions and API details.
Key Benefits
A customer experienced a service issue and the merchant wants to issue a $25 goodwill credit. The original payment was 6 months ago and is no longer available for linked refund. Using unlinked refund, the merchant credits $25 directly to the customer's card on file—no original transaction needed.
| Without Unlinked Refunds | With Unlinked Refunds |
|---|---|
| Must have an original payment to reverse | Credit any saved card independently |
| Cannot issue goodwill credits through payment system | Direct promotional credits and adjustments |
| Failed linked refunds require manual intervention | Automated credit to customer's card |
| Expired or disputed payments block refunds | Works regardless of original payment status |
How It Works
Unlinked Refund Flow
Business Rules
Pre-Conditions
- Valid customer information required (first name, last name, HSID)
- Payment method must be CARD type only (ACH/bank accounts not supported)
- Payment method must belong to the specified customer
- Each refund requires a unique
merchantTransactionId - Payment method must be active and not expired
Post-Conditions
| Outcome | Behaviour |
|---|---|
| ✅ Refund successful | Status → COMPLETED, merchant receives REFUND_SUCCESS webhook |
| ❌ Validation fails | Status → FAILED, merchant receives REFUND_FAILED webhook with error details |
| ❌ Card invalid/expired | Status → FAILED, funds not returned |
Constraints
| Constraint | Detail |
|---|---|
| Payment Method Type | CARD only — ACH and bank account payment methods are rejected |
| Maximum Amount | $10,000 USD per refund |
| Minimum Amount | 1¢ per refund |
| Customer Required | Customer must exist and be associated with the payment method |
| Unique Transaction ID | Each refund requires a unique merchantTransactionId—duplicates are rejected |
| No Retries | Failed refunds must be manually corrected and resubmitted with new transaction ID |
| Single Refund | One unlinked refund per merchantTransactionId—cannot be reused |
Scenarios
✅ Standard Scenarios
| # | Scenario | Final Outcome | Merchant Action |
|---|---|---|---|
| 1 | Goodwill credit to active card | ✅ COMPLETED | None |
| 2 | Promotional refund without prior payment | ✅ COMPLETED | None |
| 3 | Credit issued after linked refund fails | ✅ COMPLETED | None |
| 4 | Refund to customer with new card replacement | ✅ COMPLETED | None |
| 5 | Customer not found in system | ❌ FAILED | Verify customer HSID and ensure customer exists |
| 6 | Payment method not associated with customer | ❌ FAILED | Update customer-payment method association |
| 7 | ACH payment method provided | ❌ FAILED | Use CARD payment method only |
| 8 | Card expired or deleted | ❌ FAILED | Use alternate card or manual credit |
Edge Cases
The probability of these edge cases occurring in production is low (< 1%). CCG validates upfront and returns clear error messages.
Edge Cases
| # | Scenario | Outcome | Recovery |
|---|---|---|---|
| 1 | Duplicate merchantTransactionId used | ❌ FAILED | Generate new unique transaction ID and resubmit |
| 2 | Amount exceeds $10,000 USD limit | ❌ FAILED | Reduce amount to $10,000 or split into multiple refunds |
| 3 | Customer created but payment method association fails | ❌ FAILED | Verify payment method belongs to customer in system |
| 4 | Stripe account has insufficient balance | ⚠️ PENDING | Refund held until balance available; configure autodebit |
Notifications
CCG sends one refund webhook per request:
| Outcome | Webhook Event |
|---|---|
| Card credited successfully | REFUND_SUCCESS |
| Validation or processing failed | REFUND_FAILED |
| Refund queued (rare) | REFUND_PENDING |
Unlinked refund webhooks do not include a paymentId field since there's no associated payment. The payload includes refundId, merchantTransactionId, and paymentMethod details.
Status Reference
| Status | Meaning | Merchant Action |
|---|---|---|
INITIATED | Refund request accepted; validation started | Wait for final status |
PENDING | Refund queued by processor (rare) | Wait for webhook or poll status |
COMPLETED | Credit successfully issued to card | None |
FAILED | Refund could not be processed | Review error details and correct issue |
Related Documentation
- Linked Refunds: Split Tender Refunds
- General Refunds: Refunds Overview
- Technical Integration: Unlinked Refunds API
- Webhooks: Refund Webhook Events