Collection Scenarios - Refunds and Reversals

This document details the scenarios that NUE supports for processing refunds or reversals through interactions with external payment systems.

In cases of returns or cancellations, refunds are issued to customers, either partially or in full, reversing the original invoice transaction. 

Reversing an invoice involves canceling the invoice to nullify the transaction and correct any errors, effectively removing its impact on financial records; this is used when the invoice was issued incorrectly, such as with incorrect dates, amounts, or customer details.

The key differences between refunding invoices and reversing invoices are: 

• Outcome: Refunding an invoice returns money to the customer, while reversing an invoice cancels the transaction as if it never happened. Sometimes, even invoices that are paid or partially paid need to be reversed.
• Financial Records: Refunding keeps the invoice record but shows it as refunded, whereas reversing cancels, removes or nullifies the invoice.

Refund or partially refund a paid invoice

As a finance ops user, I can issue a refund to a paid or partially paid invoice, either in the external system, or in Nue, which in turn creates a credit-back type credit memo in Nue, and refund-type payment applications accordingly.  

Companies may refund a paid or partially paid invoice in the external payment system or in Nue.  When processing refunds, we need to consider the following payment scenarios: 

• An invoice is fully or partially paid by a single payment transaction;
• An invoice’s balance is offset fully or partially by applying credit memos or negative invoices;
• A combination of both.  

Therefore in Nue, refunds for paid or partially paid invoices are handled based on the payment types on the payment applications when the invoice was paid.  If multiple payment types were used, Nue processes refunds in the following priority order: 

1. Credit Memos / Negative Invoices
2. Payments

Within each payment type, if there are more than one payment applications, Nue processes refunds from the lowest amount to the highest amount.  

When refunds are processed, we create Refund Applications records, which is essentially Payment Applications with Refund record type, to track the refund transaction details.  

When refund applications are created for an invoice, the payment status of the invoice will be as follows: 

• Partially Refunded: If the total refund amount is less than the total payment amount of the invoice.
• Refunded: If the total refund amount is equal to the total payment amount of the invoice.

At the item level, the refunds will be applied to the invoice items from the lowest amount to the highest amount.

Refund invoices with payments only

When payments are refunded, a credit memo with the "Credit Back" payment status is generated and linked to the invoice, as shown in the following diagram.

To track the refund transaction, a Refund Application is created between this credit memo and the invoice. Consequently, the credit memo balance becomes zero, as its amount has been applied to offset the invoice's amount.

Example

Invoice INV-001 with balance of $100 has been fully paid by 2 payments: P-001 and P-002, as shown below.  

There are the following 2 payment applications created and associated to the invoice: 

Now 2 refunds are issued: Refund R-001 with amount $40, and Refund R-002 with amount $60. As part of the refund process, the following credit memos with Credit Back payment status are created to offset the invoice: 

Both CM-001 and CM-002 are associated with INV-001, having balances $0.

The following Refund Applications are created:

Refund invoices with non-electronic payments

When a customer requests a refund for an invoice paid through a non-electronic method, they will be presented with two options:

1. Convert the refund amount to a credit memo.
2. Write off the payment and issue an offline refund.

Example

Invoice INV-001 has a balance of $100 and includes two payment applications:

1. Payment Application #1: Applied credit memo CM-001 with an amount of $30.
2. Payment Application #2: Applied non-electronic payment with an amount of $70.

Therefore this invoice has the following payment applications: 

The customer now wants to request a refund for this invoice. In this case, we will unapply the $30 credit memo and refund the $70 non-electronic payment.

Option 1: Refund $70 offline
(Coming soon) In Nue, we will create a credit memo to write-off the invoice, which generates a write-off type payment application and set the invoice payment status to “Refunded”

Option 2: Convert $70 to Credit Memo
(Coming soon) In Nue, we will create a standalone Credit Memo from the invoice and set the invoice payment status to “Refunded”. 

Refund invoices with debit memos associated

When processing refunds for an invoice associated with a debit memo, we will first refund the invoice for the particular payment type before processing refunds for the debit memo.  

When refund applications are created for a debit memo, the payment status of the debit memo will be as follows: 

• Paid or Partially Paid: If the total refund amount against the invoice is less than the total payment amount of the invoice. 
• Partially Refunded: If the total refund amount against the invoice exceeds the total payment amount of the invoice, but the remaining refund amount is less than the total payment amount of the debit memo.
• Refunded: If the total refund amount against the invoice is equal to the combined total payment amount of the invoice and the debit memo.

Example

Invoice INV-001 has a balance of $100 and is linked to a debit memo DM-001 with a balance of $10. Both are fully paid. Three refunds have been issued in the amounts of $90, $15, and $5, respectively.

The Payment Status of INV-001 and DM-001 after each refund is detailed in the following table:

Implementation Guide

The following Refund Invoices API can be used to refund a list of invoices, and generate refund applications accordingly: 

POST https://api.nue.io/billing/invoices:refund

curl --location 'https://api.nue.io/billing/invoices:refund' \
--header 'Content-Type: application/json \
--header 'nue-api-key: {nue-api-key}' \
--data '{
  RefundInvoices: [
    {
      "invoiceId": "1fa145d6-33c7-42ae-b376-d4644e0611b5",
      "accountId": "0016D00000x1IkoQAE",
      "paymentSource": "QuickBooks",
      "paymentId": "PI-001",
      "paymentNumber": "PA-Number-001",
      "transactionAmount": "320.00",
      "paymentMethod": "Electronic"
    },
    {
      "invoiceId": "6c76a85b-b6f3-4775-a7b4-3a3c8dbce08d",
      "accountId": "0016D00000x1IkoQAE",
      "paymentSource": "QuickBooks",
      "paymentId": "PI-002",
      "paymentNumber": "PA-Number-002",
      "transactionAmount": "550.00",
      "paymentMethod": "Electronic"
    ]
}

"configMap": {"triggerFromNue": false}

Reverse invoices

As a finance ops user, I am able to reverse an invoice, i.e., cancel (paid or partially paid) invoices to correct billing errors.

Occasionally, when you discover mistakes on an active invoice, you can reverse the invoice, correct the mistakes, and then generate a new corrected invoice for the same billing period.

For example, when a user creates an order with incorrect dates or amounts, invoices might already be activated and paid or partially paid. In this scenario, the active invoices have likely been transferred to Rev Rec systems or a downstream GL system. It is possible to reverse the paid or partially paid invoices resulting from the incorrect orders.

Reverse an active invoice with Transferred payment status

In this case, the invoice has been transferred to the payment system, but is not paid.  When the finance ops user cancels the invoice, Nue will cancel or void the invoice in the payment system, and cancel the invoice in Nue.

Reverse a fully paid invoice

In this case, the finance ops user cancels the paid invoice.  Nue handles the following in one transaction: 

1. Process refund of the paid invoice: 
1. Refund the full amount in the payment system. 
2. Create a Credit Back type credit memo in Nue associated with the invoice.  
3. Set the invoice’s Payment Status to Refunded.
4. Create a Credit Memo Application between the invoice and the credit memo
5. Set the Payment Status to Refunded.
2. Cancel the invoice: 
1. The associated Credit Back credit memos will also be canceled when the invoice is canceled.

Reverse a partially paid invoice

In this case, the finance ops user cancels the partially paid invoice.  Nue handles the following in one transaction: 

1. Process refund for the paid amount by executing the refund steps; 
2. Cancel the invoice and set the payment status to Refunded.

Reverse a refunded or partially refunded invoice

In this case, the finance ops user cancels the refunded or partially refunded invoice. We do the following in a single transaction

1. Process refund of the remaining part of the partially refunded invoice, if there is any
1. Refund the remaining amount in the payment system
2. Create a Credit Back type credit memo in Nue associated with the invoice.  
3. Set the invoice’s Payment Status to Refunded.
4. Create a Credit Memo Application between the invoice and the credit memo
5. Set the Payment Status to Refunded.
2. Cancel the invoice:
1. The associated Credit Back credit memo is also canceled when the invoice is canceled.

Reverse an invoice with credit memos applied, potentially payments applied as well  

In this case, the invoice’s balance has been reduced by applying credit memos, and applying payments.  When a finance ops user cancels the invoice, the following actions occur: 

• Process refund of the paid amount;
• Unapply the credit memos;
• Cancel the invoice and set the payment status to: 
1. Refunded, if there are payments refunded;
2. Canceled, if only credit memos are unapplied.

Example

Invoice INV-001 has an amount of $100.  It has received 2 payments: Payment #1 of amount $40 via credit memo application, and Payment #2 of amount $30 via credit card.  It has a remaining balance of $30.

When the invoice is canceled, payment #1 will be reversed by un-applying the credit memo, and payment $2 will be refunded.  The following refund application and credit memo application are created: 

The following shows the refund application details for the Credit Back type credit memo: 

The following shows the credit memo application details for the credit memo applied to the invoice: 

Reverse an invoice with a debit memo associated

In this case, when the finance ops user cancels the invoice, we automatically cancel the associated debit memo(s) as well.  The following actions occur: 

1. Cancel associated debit memos one by one
   1. When canceling a debit memo, Nue processes the same actions as reversing an invoice.
2. Cancel the invoice

For paid or partially paid debit memos and invoices, the Payment Status is set to 

• Refunded, if there are payments refunded;
• Canceled, if only credit memos are unapplied.  

Implementation Guide

To implement the Reverse Invoice integration with an external payment system, 

Webhooks

When an invoice is activated, an invoice.canceled Webhook event is raised with the payload containing the invoice and invoice items.

APIs

The following Cancel Invoices API can be used to reverse invoices: 

POST /billing/invoices:cancel

{
  "invoiceIds": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "notifyCrm": true,
  "notifyDebitMemoChangedToCrm": true,
  "notifyPaymentChangedToCrm": true,
  "invoiceComment": {
    "comment": "example comment"
  },
  "paymentDetail": "string"
}

Cancel Payments

(Coming soon)

As a finance ops user, I can cancel a payment in an external payment system, which in turn increases the invoice balance, and creates payment applications to track the reversal of the payments.

When a payment is canceled in the external payment system, the following actions occur in a single atomic operation: 

1. Create payment applications to reverse the payment applications resulting from the payment;
2. Increase the invoice’s balance by the reversed payment amount;
3. Set the payment status of the invoice to 
1. Partially Paid, if the new balance is not $0);
2. Transferred, if the new balance is $0.

Example

Invoice INV-001 has a total amount of $100.  It has received total Payment #1 from an external payment system of $70, including $30 from credit card payments, and $40 from a credit memo application.  A user now cancels the payment in the external payment system.

Upon receiving the notification, the following payment applications will be created: 

After the payment is canceled, the invoice has a new balance of $100 and its Payment Status is set to Transferred.