Collection Scenarios - Payments

This document outlines the scenarios supported by Nue for processing payments through external payment systems.  

Customers pay invoices using various methods such as credit cards, bank transfers, or online payment platforms. Customers may choose to make partial payments towards an invoice, either as a down payment or installment.

Pay or partially pay invoices

As a finance ops user, when a customer pays an invoice, I can see the invoice’s payment status changed to Paid or Partially Paid in Nue, and the payment applications created for the invoice in Nue.

After a payment is processed for a mirrored invoice in external payment systems, Nue is informed either through webhooks or by retrieving the information from the external systems on a scheduled basis, such as daily.

Use Case #1: Pay invoices containing invoice items with all positive amounts

In this case, Nue creates payment applications containing payment application items by following the business logic below: 

1. Create payment applications where the total transaction amount equals the payment amount.
2. For each invoice item, create a payment application item associated with the payment application to offset the invoice item balances, starting from the smallest invoice item to the largest.
1. The amount of the payment application item will be equal to the invoice item balance if the remaining payment amount is greater than or equal to the invoice item balance.
2. Otherwise, the amount of the payment application item will be the remaining payment amount if the payment amount is not sufficient to offset the invoice item balance. 

Example

Invoice INV-001 includes three invoice items, each with a balance of $20, $30, and $50. Two payments were made, with amounts of $30 and $50, respectively. After issuing the second payment, two payment applications were created with the following details:

Following these two payments, the invoice has a remaining balance of $20. Invoice items II-001 and II-002 have been paid off, while invoice item II-003 still has a balance of $20.

Use Case #2: Pay invoices containing one or more negative invoice items

In this scenario, because there are both positive and negative invoice items within the same invoice, we will first use the negative invoice items to offset the positive ones. This will reduce the balance of the positive invoice items and result in the creation of a zero-amount payment application to track these offsets. Future payments will be used to offset the remaining balance of the invoice, if there is any.

Specifically, Nue creates payment applications containing payment application items by following the business logic below: 

1. Create a zero-amount payment application with the payment source set to Nue. In this payment application, 
1. Create negative payment application items to offset all negative invoice items, one by one.
2. Create payment application items to offset the remaining invoice items by applying the negative payment application items' amounts, starting from the smallest invoice item to the largest.
2. When actual payments occur, create other payment applications where the total transaction amount equals the payment amount. In this payment application, create payment application items associated with the payment application to offset the invoice item balances, starting from the smallest invoice item to the largest (beginning with invoice items not zeroed out in the first payment application).
1. The amount of each payment application item will equal the invoice item balance if the remaining payment amount is greater than or equal to the invoice item balance.
2. Otherwise, the amount of each payment application item will be the remaining payment amount if the payment amount is insufficient to offset the invoice item balance.

Example

Invoice INV-002 contains invoice items, each has -$20, -$30, $40, $50, and $60 in balance.  2 payments are issued with payment amount $30 and $70 respectively.  After the 2nd payment is issued, we have altogether 3 payment application created with the following details: 

The following table shows the payment application item in the Zero-amount payment application PA-001: 

For both scenarios, after the payments occur, the Payment Status of the invoices will be changed from Transferred to Paid if the invoices’ balance is 0; otherwise to Partially Paid if the balance is greater than 0.

Implementation Guide

The Pay Invoices can be used to issue payments for a list of invoices, and generate payment applications accordingly: 

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

curl --location 'https://api.nue.io/billing/invoices:pay' \
--header 'Content-Type: application/json \
--header 'nue-api-key: {nue-api-key}' \
--data '{
        "payInvoices": [
        {
            "invoiceId": "4f163819-178d-470c-a246-d6768476a6ec",
            "customerId": "001QL000006gT2DYAW",
            "transactionAmount": 230,
            "paymentId": "PA-001",
            "paymentSource": "Stripe",
            "paymentNumber": "PA-000001"
        }
    ]
}

"configMap": {"triggerFromNue": false}

Pay or partially pay debit memos

As a finance user, when a customer pays an invoice with a debit memo associated, I can see the debit memo’s payment status changed to Paid or Partially Paid, and the payment applications created for the debit memo in Nue.

When an invoice associated with a debit memo is transferred to an external payment system, the user may choose to pay them together as a single payment transaction, for example, when an invoice includes a certain amount of late fee.

In this scenario, the total payment amount received might exceed the invoice amount. Therefore, when a payment transaction is issued in the external system, Nue will first apply part of the payment to offset the invoice and then apply the remaining balance to offset the debit memo.  Specifically, Nue will

• Apply the payment to the invoice first, and create payment applications associated with the invoice. 
• If the invoice is fully paid, then apply the debit memo with the remaining payment amount, if there is any.  If the balance of the debit memo becomes 0, set the payment status of the debit memo to Paid.  Otherwise, set the payment status to Partially Paid.  

Example

Invoice INV-001 has an outstanding balance of $100. It is linked to Debit Memo DM-001, which has a balance of $10. Two payments have been received: Payment #1 for $30, and Payment P-002 for $80.

In this example, Payment #2 is applied to Invoice INV-001, reducing its balance to $70. Payment P-002 is then applied to both Invoice INV-001, bringing its balance to zero, and Debit Memo DM-001, also bringing its balance to $0. As a result, both the invoice and the debit memo are fully paid. 

The following payment applications are created: 

Implementation Guide

Same as paying invoices, the following API can be used to pay invoices associated with debit memos: 

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