Skip to main content

​
What is a Refund?

A refund returns money to a customer for a previous payment. This is different from canceling a payment before it’s processed—refunds are for payments that have already been completed. Common scenarios:
  • Customer returns a product
  • Service was not delivered as promised
  • Customer cancels and is eligible for a refund
  • Partial refund for damaged items or partial service
  • Customer dispute resolution

​
Why Partial Refunds Exist

Sometimes you need to refund only part of a payment: Real-world examples:
  • Multi-item order: Customer returns 2 out of 5 items → Partial refund for those 2 items
  • Service cancellation: Customer cancels mid-month → Refund for unused portion
  • Damaged goods: Product arrived damaged but customer keeps it → Partial refund as compensation
  • Shipping issues: Order delayed, customer gets partial refund for inconvenience
  • Subscription proration: Customer cancels subscription, refund unused portion of current period
Benefits of partial refunds:
  • Better customer experience (fair refunds)
  • Flexibility in handling edge cases
  • Can issue multiple partial refunds (as long as total doesn’t exceed original amount)

​
Refund Basics

​
What You Can Refund

  • Any amount up to the original payment (excluding taxes, see below)
  • Multiple partial refunds (as long as the total doesn’t exceed the original)
  • Full refund (returns the entire amount)
  • Cannot refund more than the original payment
  • Cannot refund if already fully refunded

​
Important Limitations

Note: Currently, Revolv3 supports refunds only for transactions processed by Revolv3. If a payment was processed by another payment service provider (PSP), you’ll need to handle the refund through that provider.

​
How Refunds Work

Here’s the process:
  1. You issue a refund via API or portal
  2. Revolv3 processes the refund through the same processor that handled the original payment
  3. Money is returned to the customer’s original payment method
  4. Timing varies:
    • Credit cards: Usually 3-10 business days to appear on customer’s statement
    • ACH: 1-5 business days (similar to ACH payments)
The customer sees the refund on their credit card statement or bank account, but it’s not instant—it takes a few days to process.

​
Refund Flow Sequence

​
Processing a Refund via API

​
API Endpoint

POST {{Api Root}}/api/Invoices/{invoiceId}/refund
Replace {invoiceId} with the invoice ID from the original payment.

​
Required Parameters

  • invoiceId (in URL): The invoice ID of the original payment transaction. You get this from the payment response when you first charged the customer.
  • amount (in request body, optional): The refund amount.
    • If not provided, defaults to full refund
    • Must be less than or equal to the original amount (excluding taxes)

​
Sample Refund Request

Full refund (return entire amount): 
POST /api/Invoices/237058/refund
{
  // No amount specified = full refund
}
Partial refund (return specific amount): 
POST /api/Invoices/237058/refund
{
  "amount": 1.03 // Refund $1.03 (must be ≤ original amount)
}

​
Understanding the Request

ParameterDescription
invoiceIdThe invoice ID from the original payment. This links the refund to the original transaction.
amountOptional. Refund amount (excluding taxes). If omitted, refunds the full amount.
Important: The refund amount is specified excluding taxes. If the original payment included tax, Revolv3 will automatically calculate and refund the proportional tax amount. See the Taxes section below for details.

​
Refund Response

When you issue a refund, Revolv3 creates a new invoice for the refund and returns details: 
{
  "invoice": {
    "invoiceId": 237059, // New invoice ID for this refund
    "parentInvoiceId": 237058, // Links back to original payment
    "customerId": null,
    "merchantInvoiceRefId": null,
    "paymentMethod": {
      "paymentMethodId": 6469,
      "billingAddressId": 7551,
      "billingFirstName": "Joe",
      "billingLastName": "Smith",
      "billingAddress": {
        "addressId": 7551,
        "addressLine1": "381 Forest Ave. Suite C",
        "city": "Laguna Beach",
        "state": "CA",
        "postalCode": "92651",
        "country": "US"
      },
      "paymentMethodCreditCardDetails": {
        "binNumber": "444433",
        "paymentLast4Digit": "1111",
        "paymentExpirationDate": "0330"
      }
    },
    "invoiceStatus": "Refund", // Status indicates this is a refund
    "subtotal": 1.03,
    "tax": 0.0,
    "total": 1.03,
    "billingDate": "7/11/2024"
  },
  "refunds": [
    {
      "invoiceAttemptId": 114130,
      "amount": -1.03, // Negative amount indicates refund
      "invoiceAttemptStatus": "Success",
      "invoiceAttemptDate": "2024-07-11T18:19:28.6971789Z",
      "paymentProcessor": "WorldPay",
      "processorTransactionId": "84082561857760470",
      "responseCode": "000",
      "responseMessage": "Approved"
    }
  ],
  "refundedSubtotal": 1.03, // Total refunded so far (subtotal)
  "refundedTax": 0.0000, // Total tax refunded
  "refundedTotal": 1.03 // Total refunded (subtotal + tax)
}

​
Understanding the Response

FieldDescription
invoice.invoiceIdNew invoice ID created for this refund. Save this for your records.
invoice.parentInvoiceIdLinks back to the original payment invoice.
invoice.invoiceStatusWill be "Refund" for full refunds or "PartialRefund" for partial refunds.
refunds[].invoiceAttemptStatusStatus of the refund attempt. "Success" means it was processed.
refunds[].amountNegative amount (indicates money going back to customer).
refundedSubtotalTotal amount refunded so far (excluding tax).
refundedTaxTotal tax refunded so far.
refundedTotalTotal refunded (subtotal + tax).

​
Understanding Taxes in Refunds

Tax handling can be confusing. Here’s how it works:

​
If Original Payment Had No Tax

If the original payment didn’t include tax:
  • Refund the amount you specify (or full amount if not specified)
  • No tax calculation needed

​
If Original Payment Included Tax

If the original payment included tax (e.g., from a subscription): For full refunds:
  • Specify the refund amount excluding taxes
  • Revolv3 automatically refunds the full tax amount as well
  • Customer gets back: refund amount + full tax
For partial refunds:
  • Specify the refund amount excluding taxes
  • Revolv3 automatically calculates proportional tax
  • Example: If original was $100 + $10 tax = $110 total, and you refund $50:
    • Customer gets: $50 (subtotal) + $5 (proportional tax) = $55 total
If you don’t specify an amount:
  • Defaults to full refund (including all taxes)

​
Example: Tax Refund Calculation

Original payment:
  • Subtotal: $100.00
  • Tax: $10.00
  • Total: $110.00
Partial refund of $50: 
POST /api/Invoices/12345/refund
{
  "amount": 50.00 // Excluding tax
}
Result:
  • Refunded subtotal: $50.00
  • Refunded tax: $5.00 (proportional: 50% of original tax)
  • Total refunded: $55.00

​
Processing Refunds via Portal

You can also issue refunds through the Revolv3 portal:
  1. Go to the Invoices screen
  2. Select the invoice you want to refund
  3. Click Refund in the Invoice section
  4. Choose:
    • Full refund: Return the entire amount
    • Partial refund: Enter a specific amount
  5. Click Refund to process
The portal shows the original transaction amount (excluding taxes) and lets you enter a different amount for partial refunds.

​
Real-World Refund Scenarios

​
Scenario 1: Customer Returns One Item from Multi-Item Order

Original order:
  • Item A: $30.00
  • Item B: $20.00
  • Item C: $15.00
  • Total: $65.00
Customer returns Item B: 
POST /api/Invoices/12345/refund
{
  "amount": 20.00 // Refund for Item B
}
Result: Customer gets $20.00 back. Order status: Partial refund. You can refund more later if needed.

​
Scenario 2: Subscription Cancellation with Proration

Original subscription:
  • Monthly fee: $29.99
  • Customer paid on the 1st
  • Customer cancels on the 15th (halfway through month)
Refund calculation:
  • Unused portion: $29.99 / 2 = $14.99
POST /api/Invoices/12345/refund
{
  "amount": 14.99 // Prorated refund
}
Result: Customer gets $14.99 back for the unused portion.

​
Scenario 3: Multiple Partial Refunds

Original order: $100.00 First refund: $30.00 (customer returns one item) 
POST /api/Invoices/12345/refund
{ "amount": 30.00 }
Second refund: $20.00 (compensation for delay) 
POST /api/Invoices/12345/refund
{ "amount": 20.00 }
Total refunded: $50.00 Remaining: $50.00 (can still refund up to this amount)

​
Scenario 4: Full Refund

Customer wants to return entire order: 
POST /api/Invoices/12345/refund
// No amount = full refund
Result: Customer gets the full amount back. Invoice status: Refund.

​
Why Refunds Fail

Refunds can fail validation for several reasons:
ReasonExplanation
Amount too highRequested refund exceeds the original payment amount (excluding taxes)
Already fully refundedThe invoice has already been fully refunded, no remaining amount
Partial refunds exceed totalSum of all partial refunds would exceed the original amount
Invoice not foundThe invoice ID doesn’t exist or wasn’t processed by Revolv3
What to do if refund fails:
  • Check the error message for the specific reason
  • Verify the invoice ID is correct
  • Check how much has already been refunded
  • Ensure the amount is valid

​
Refund Timing Considerations

​
Credit Card Refunds

  • Processing time: Usually processed within 1-2 business days
  • Customer sees it: 3-10 business days on their statement (depends on their bank)
  • Best practice: Tell customers it takes 5-10 business days to appear

​
ACH Refunds

  • Processing time: 1-5 business days (similar to ACH payments)
  • Customer sees it: When the ACH batch processes
  • Best practice: Tell customers it takes 3-5 business days

​
Important Notes

  • Refunds are not instant: Even though Revolv3 processes them quickly, banks take time to post them
  • Set customer expectations: Always tell customers when to expect the refund
  • Track refund status: Use webhooks or API polling to know when refunds complete
  • Keep records: Store refund invoice IDs for customer support and reconciliation

​
Best Practices

  1. Store original invoice IDs: You’ll need them to issue refunds
  2. Set customer expectations: Tell them refunds take 5-10 business days
  3. Handle partial refunds gracefully: Have a clear policy on when partial refunds are appropriate
  4. Track refund history: Keep records of all refunds for customer support
  5. Use webhooks: Get notified when refunds complete
  6. Reconcile regularly: Match refunds with your accounting records
  7. Have a refund policy: Clear policy helps avoid disputes

​
Common Questions

Q: Can I refund more than the original payment? A: No, you can only refund up to the original payment amount (excluding taxes). Q: How long do refunds take? A: Revolv3 processes them quickly (1-2 days), but banks take 3-10 business days to show them on customer statements. Q: Can I cancel a refund? A: No, once a refund is issued, it cannot be cancelled. You’d need to charge the customer again if you made a mistake. Q: What if the customer’s card is expired? A: The refund will still go through—banks handle expired card refunds automatically. Q: Can I refund to a different payment method? A: No, refunds always go back to the original payment method. If the customer wants a different method, you’d need to process it as a new transaction.

​
Next Steps

  • Invoice Status — Understand refund statuses (Refund, PartialRefund)
  • Subscriptions — Learn about canceling subscriptions and refunds
  • Webhooks — Set up notifications for refund completions