Refunds, Reversals, Voids and Partial-Capture Payment Workflows
Architecture for refund processing, reversals, voids, and partial-capture payment workflows
Refunds return funds from a captured payment to the customer. Reversals cancel a transaction before settlement. Voids cancel an authorized but not captured payment. Partial capture captures less than the authorized amount. Key workflows: full refund, partial refund, void (before capture), reversal (before settlement), and partial capture. Each has different timing, state transitions, and settlement implications. Architecture requires idempotent APIs, state machine management, and reconciliation across gateway, bank, and ledger.
Payment modifications (refunds, reversals, voids, partial captures) are essential workflows for any payment system. Each modification has different timing requirements, state transitions, and settlement implications.
Refunds return funds from captured payments (full or partial). Voids cancel authorized but not captured payments. Reversals cancel transactions before settlement. Partial captures capture less than the authorized amount. Each requires careful state management and reconciliation.
This topic covers payment modification workflows, state machine design, and reconciliation for modified transactions.
A refund is the return of funds from a captured payment to the customer. A reversal cancels a transaction before it settles. A void cancels an authorized but not captured payment. A partial capture captures less than the authorized amount. Each modification has different timing requirements, state transitions, and settlement implications.
Payment modifications are a critical part of customer service and operations. Customers expect fast refunds for returns. Merchants need void and partial capture for order modifications. Incorrect handling leads to financial discrepancies and customer disputes.
For payment platforms, modification workflows must be idempotent, reliable, and properly reconciled. Failed or duplicate modifications lead to financial losses and customer complaints.
In 2026, instant refunds are becoming the standard, with real-time payment rails enabling immediate fund return. AI-driven refund automation handles common refund scenarios without manual intervention.
The rise of real-time payments (UPI, FedNow) makes reversals more complex, as real-time transactions are irrevocable once completed.
Payment modification workflows:
Reference Architecture
A modification request is received. The system validates the current state allows the modification. The modification is processed. The state transitions. Settlement impact is calculated. Reconciliation updates all systems.
| Modification | When | State Transition |
|---|---|---|
| Void | After auth, before capture | authorized → voided |
| Capture | After auth | authorized → captured |
| Partial Capture | After auth | authorized → partially_captured |
| Full Refund | After capture | captured → refunded |
| Partial Refund | After capture | captured → partially_refunded |
| Reversal | Before settlement | captured → reversed |
Payment modification technical architecture:
Payment state machine with all valid states and transitions. Invalid transitions rejected. State stored in database with optimistic locking.
All modification APIs require idempotency keys. Prevents duplicate modifications on retries.
Full refund: refund entire captured amount. Partial refund: refund portion. Multiple partial refunds allowed up to captured amount. Refund status tracked.
Cancel authorized but not captured payment. Releases hold on customer funds. Only possible before capture.
Capture less than authorized amount. Useful for partial order fulfillment. Remaining authorization may be voided or captured later.
Cancel transaction before settlement. Rare, used for error correction. May require network support.
Payment modification APIs:
POST /payments/{id}/refund with full amount.
POST /payments/{id}/refund with partial amount.
POST /payments/{id}/void to cancel authorized payment.
POST /payments/{id}/capture with partial amount.
/v1/payments/{id}/refundProcess a partial refund
Request
POST /v1/payments/pay_001/refund
Idempotency-Key: refund_001
Authorization: Bearer sk_live_xxx
{
"amount": 1000,
"reason": "customer_returned_item"
}Response
{
"id": "re_26JAnRef",
"payment_id": "pay_001",
"status": "processed",
"amount": 1000,
"refund_type": "partial",
"remaining_captured_amount": 3999
}/v1/payments/{id}/voidVoid an authorized payment
Request
POST /v1/payments/pay_002/void Idempotency-Key: void_001 Authorization: Bearer sk_live_xxx
Response
{
"id": "pay_002",
"status": "voided",
"voided_at": "2026-01-01T10:00:00Z"
}Modification data architecture:
| Data | Purpose | Storage |
|---|---|---|
| Payment State | Current state of payment | PostgreSQL (ACID) |
| Modification Records | Refund, void, capture records | PostgreSQL |
| Settlement Impact | Adjustments to settlement | Settlement DB |
| Reconciliation | Match modifications across systems | Reconciliation DB |
Payment modification implementations:
Context: Payment modification APIs.
Problem: Provide clean APIs for refunds, voids, and partial captures.
Architecture: REST APIs with idempotency, state machine, and automatic reconciliation.
Technology: Ruby, Go, PostgreSQL
Outcomes: Millions of modifications processed reliably.
Lessons: Idempotency is critical for modifications. State machine prevents invalid transitions.
Storing PAN or CVV in databases creates massive PCI DSS scope and security risk. Always use tokenization.
Missing idempotency keys on payment endpoints causes duplicate charges on retries. Every payment API must support idempotency.
Treating inherently asynchronous payment operations as synchronous causes timeouts and poor UX. Use webhooks and async patterns.
Failing to retry failed webhook deliveries causes merchants to miss critical payment status updates. Implement exponential backoff retry.
Manual reconciliation at scale is error-prone and slow. Automate reconciliation from day one.
Depending on a single payment rail creates a single point of failure. Implement multi-rail architecture with failover.
Launching without fraud monitoring leads to chargebacks and losses. Implement real-time fraud detection from day one.
Using the transaction database as the financial ledger leads to accuracy and audit issues. Maintain a separate double-entry ledger.
| KPI | Description | Target |
|---|---|---|
| Authorization Rate | Percentage of payment attempts that receive authorization | > 95% |
| Payment Success Rate | Percentage of initiated payments that complete successfully | > 97% |
| API Latency (p99) | 99th percentile API response time | < 500ms |
| TPS Capacity | Transactions per second the system can handle | Based on peak demand |
| Fraud Rate | Fraudulent transactions as percentage of total | < 0.1% |
| Chargeback Rate | Chargebacks as percentage of transactions | < 0.75% |
| Uptime | System availability | 99.99% |
| Reconciliation Accuracy | Percentage of transactions successfully reconciled | > 99.5% |
Build Payment Modification APIs
Objective: Design and implement refund, void, and partial capture APIs.
Scenario: Build modification APIs for a payment gateway with proper state management and reconciliation.
- Design payment state machine with all states
- Implement full and partial refund APIs
- Implement void API
- Implement partial capture API
- Design reconciliation for modifications
Deliverables: Modification APIs, state machine, reconciliation.
Validation: Process refund. Process partial refund. Void authorized payment. Partial capture. Verify state transitions. Verify reconciliation.
What is the difference between void and refund?
Void cancels an authorized but not captured payment, releasing the hold on customer funds. Refund returns funds from a captured payment. Void is before settlement; refund is after settlement.
Can you refund more than the captured amount?
No, refunds cannot exceed the captured amount. Multiple partial refunds are allowed up to the total captured amount. The system must track remaining refundable amount.
What is a partial capture?
Partial capture captures less than the authorized amount. Useful when the actual charge is less than authorized (e.g., some items out of stock, restaurant tip adjustment). The remaining authorization can be voided or captured separately.
Payment Service Provider: entity that enables merchants to accept payments through multiple payment methods via a single integration.
Payment Facilitator: entity that enables sub-merchants to accept payments under the PayFac master merchant account.
Bank or financial institution that processes card transactions on behalf of merchants.
Bank or financial institution that issues payment cards to consumers.
Fee paid between the acquiring bank and the issuing bank for card transactions, set by card networks.
Merchant ID: unique identifier assigned to a merchant by the acquirer.
Primary Account Number: the 14-19 digit number on a payment card, considered sensitive cardholder data under PCI DSS.
Process of replacing sensitive card data with a non-sensitive token.
Process of verifying that a payment account has sufficient funds and is valid for a transaction.
Process of finalizing a previously authorized transaction, triggering the transfer of funds.
Process of exchanging transaction details between acquiring and issuing banks.
Actual transfer of funds between banks to complete a payment transaction.
Transaction dispute initiated by a cardholder through their issuing bank.
Merchant Category Code: 4-digit code classifying the type of goods or services a merchant sells.
3-D Secure: authentication protocol for card-not-present transactions.
Payment Card Industry Data Security Standard: security standard for organizations handling cardholder data.
Hardware Security Module: physical computing device that safeguards and manages digital keys.
Property of an API where making the same request multiple times produces the same result as making it once.
HTTP callback triggered by an event, used in payments for asynchronous notifications.
Unified Payments Interface: India real-time payment system developed by NPCI.
National Payments Corporation of India: umbrella organization for retail payment systems in India.
Reserve Bank of India: India central bank and regulatory authority for payment systems.
International standard for electronic data interchange between financial institutions.
Automated Clearing House: US electronic payment network for batch-processed bank-to-bank transfers.
US Federal Reserve instant payment service launched in 2023.
Single Euro Payments Area: EU payment integration initiative.
Real-Time Payments: payment infrastructure enabling instant, irrevocable payments 24/7.
Financial record-keeping system using double-entry accounting.
Process of matching transaction records across different systems to ensure consistency.
Financial arrangement where a third party holds funds until conditions are met.
Buy Now Pay Later: short-term financing allowing consumers to pay in installments.
Banking-as-a-Service: model where licensed banks provide banking infrastructure via APIs.
Practice of providing secure API access to bank account data and payment initiation.
Integration of financial services into non-financial platforms via APIs.
Cryptocurrency designed to maintain stable value by pegging to a reference asset.
Return of funds from a captured payment to the customer.
Cancellation of an authorized but not captured payment.
Capturing less than the authorized amount.
Cancellation of a transaction before settlement.
- Architecture designed and reviewed
- API contracts defined with idempotency
- Authentication and authorization implemented
- PCI DSS scope assessed and minimized via tokenization
- Error handling and retry logic designed
- Webhook delivery and retry implemented
- Security review completed (encryption, HSM, key management)
- Regulatory requirements identified (RBI, PCI DSS, AML)
- Data model defined (transactions, ledger, reconciliation)
- Observability implemented (metrics, logs, traces, alerts)
- Testing completed (unit, integration, load, chaos)
- Disaster recovery designed and tested
- Reconciliation process validated
- Fraud detection deployed and tuned
- Production readiness assessed and approved
Designs end-to-end payment architecture including gateways, orchestration, rails, security, and compliance.
Designs comprehensive fintech platform architecture including payments, banking, ledgers, risk, and compliance.
Designs API-first payment platforms including REST APIs, webhooks, SDKs, developer portals, and API governance.
Implements and operates payment infrastructure including gateway, routing, processing, reconciliation, and settlement.
Builds internal developer platforms for payment integration, providing self-service APIs, SDKs, and golden paths.
Applies software engineering to payment operations, managing SLI/SLO/error budgets and incident response.
Monitors transaction patterns, investigates suspicious activity, tunes fraud rules, and manages chargeback disputes.
Defines payment product strategy, manages roadmap, balances user experience with compliance, and drives payment metrics.
Ensures payment systems meet PCI DSS, RBI, AML, and other regulatory requirements.
Implements and operates treasury management systems including liquidity management, settlement, FX, and bank connectivity.
2027: Refunds and Reversals will see increased AI integration with AI agents handling routine payment decisions, intelligent routing optimization, and predictive fraud prevention becoming standard capabilities.
2028: Autonomous payment systems will mature with self-healing infrastructure, AI-driven reconciliation, and cross-border real-time payments reducing settlement time from days to seconds.
2029: Programmable money and tokenized deposits will enable new payment models with conditional settlement, smart contract-based escrow, and machine-to-machine payments becoming practical.
2030: The convergence of AI, blockchain, and real-time payments will be complete. Refunds and Reversals will be managed through AI agents with humans governing policy, security, and business alignment. Payments will be invisible, instant, and intelligent.
- Payment modifications include refunds, voids, partial captures, and reversals.
- Each modification has specific timing and state transition requirements.
- Idempotency is critical for safe modification processing.
- State machine prevents invalid modifications.
- Reconciliation must account for all modifications.