Collections - 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 docid\ ae3ba64996a0091d21301039784e1144fb6f3a2f 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 create payment applications where the total transaction amount equals the payment amount 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 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 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 process payment jpg 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 invoice ($100) payment application pa 001 payment application pa 002 invoice item ii 001 $20 payment application item pai 001 $20 invoice item ii 002 $30 payment application item pai 002 $10 payment application item pai 003 $20 invoice item ii 003 $50 payment application item pai 004 $30 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 docid\ ae3ba64996a0091d21301039784e1144fb6f3a2f 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 create a zero amount payment application with the payment source set to nue in this payment application, create negative payment application items to offset all negative invoice items, one by one 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 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) 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 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 invoice ($100)(invoice items sorted by the smallest amount to the largest) payment application pa 001(zero amount payment application with payment source nue) payment application pa 002 payment application pa 002 invoice item ii 001 $ 30 payment application item pai 001 $ 30 invoice item ii 002 $ 20 payment application item pai 002 $ 20 invoice item ii 003 $40 payment application item pai 003 $30 payment application item pai 004 $10 invoice item ii 004 $50 payment application item pai 005 $10 payment application item pai 006 $30 payment application item pai 007 $10 invoice item ii 005 $60 payment application item pai 008 $60 the following table shows the payment application item in the zero amount payment application pa 001 payment application item invoice item id record type payment source payment type payment application item pai 001 $ 30 invoice item ii 001 $ 30 payment nue payment payment application item pai 002 $ 20 invoice item ii 002 $ 20 payment nue payment payment application item pai 003 $30 invoice item ii 003 $40 payment nue payment payment application item pai 004 $10 invoice item ii 003 $40 payment nue payment payment application item pai 005 $10 invoice item ii 004 $60 payment nue payment 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 docid\ ae3ba64996a0091d21301039784e1144fb6f3a2f implementation guide the pay invoices https //api docs nue io/#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" } ] } note if the request payload includes a specified paymentsource and there is an existing connected payment system, the pay invoices api cannot be directly triggered from nue the standard connector with the payment system will process it automatically to maintain data integrity to override this behavior, you can add the following parameter to the payload (use with caution) "configmap" {"triggerfromnue" false} docid\ ae3ba64996a0091d21301039784e1144fb6f3a2f 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 payment application invoice id debit memo id transaction amount payment type record type payment id pa 001 inv 001 $30 payment payment p 001 pa 002 inv 001 $70 payment payment p 002 pa 003 dm 001 $10 payment payment p 002 docid\ ae3ba64996a0091d21301039784e1144fb6f3a2f 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 docid\ ae3ba64996a0091d21301039784e1144fb6f3a2f