Bank Allocate Credits And Payments API

Overview: Bank Allocate Credits And Payments API

Zumzum Financials includes a global class called BankAllocateCreditsAndPaymentService which you may call from your own Apex code. Below is information related to how to post a bank allocation and create a Ledger Payment History record with the Bank Allocate Credits And Payments API Service  using Apex code.

The Zumzum Financials Bank Allocate Credits and Payments API Service provides the following capabilities

• Allocate supplier Purchase Credits (PC) to unpaid Purchase Invoices (PI)
• Allocate supplier Payments On Account (PA) to unpaid Purchase Invoices (PI)
• Allocate customer Sales Credits (SC) to unpaid Sales Invoices (SI)
• Allocate customer Payment On Account (SA) to unpaid Sales Invoices (SI)
• Allocate Customer Refund (SP) to an unallocated Sales Credit (SC)
• Allocate Supplier Refund (PR) to an unallocated Purchase Credit (PC)

Bank Allocate Credits and Payments API Description

Automate the allocation of customer and supplier account balances from Payments on Account, Credits or Refunds to transactions in the Zumzum Financials general ledger. Allocating account balances to invoices or credit note transactions will update the Paid Amount and Unpaid Amount on both the source and target transactions.  For example, allocating a credit note to an invoice, will increase the Paid Amount on both transactions and reduce the Unpaid Amount on both too.

You should be aware of the following:

• Each allocation should contain a minimum of two line items, so that:
  • The equation balances Total Amount of Unallocated Lines  = Total Unpaid Lines
  • The Unallocated line items that you wish to apply to an unpaid transaction line items
  • The Unpaid lines will be the transaction you wish to apply the unallocated balance to
• All Bank Allocation Line Item values will need to be provided as a positive number as negative amounts are not supported.
• Bank allocation transactions are automatically posted to the Zumzum Financials general ledger.
• When using the BankAllocateCreditsAndPaymentsService Apex class, you will be creating the Ledger Payment History (Bank Allocation) records.
• You are unable to un post or delete a Ledger Payment History (Bank Allocation) and it’s associated records once you have posted to the ledger.
• The BankAllocateCreditsAndPaymentsService will execute in either synchronous or asynchronous mode depending on the type of input submitted to the service.

The BankAllocateCreditsAndPaymentsService function will accept the list of ‘BankAllocateCreditsAndPaymentsWrapper’ or a single BankAllocateCreditsAndPaymentsWrapper as an input parameter.  Below are the required fields when a Bank Allocation is created.

BankAllocateCreditsAndPaymentsWrapper API Fields

The ‘BankAllocateCreditsAndPaymentsWrapper’ will accept the list of ‘BankAllocateCreditsAndPaymentsLineWrapper’ as an input parameter.  Below are the required fields when creating a Bank Allocation Line.

BankAllocateCreditsAndPaymentsLineWrapper API Fields

Allocate Customer Balances – BankAllocateCustomerBalance Method

The BankAllocateSupplierBalance  method is used to create Ledger Payment History records, which act as a junction object between the ledger record of the Parent Transaction and the Payment Transaction ledger record. The system then creates relationships between the Bank Payment/Receipt Records,  Credit/Invoice records and Accounts.

Sample Code: Allocate Customer Balances

This example is provided to help you begin creating your own custom code.  The code will post an allocation of a customer balance which creates a Ledger Payment History record.

The following steps will be performed:

1. Retrieve the ledger record, of the Debtors Control Account from the unallocated SalesCredit Line Item.  This is the balance you wish to allocate to an unpaid Sales Invoice Line Item.
2. Retrieve the ledger record, of the Debtors Control Account from the unpaid Sales Invoice Line Item. This is the sales invoice line item you wish to allocate the account balance to.
3. Prepare the data required to construct the “BankAllocateCreditsAndPaymentsWrapper” to supply as an input for the BankAllocateCustomerBalance
4. Post the Bank Allocation transaction with the BankAllocateCustomerBalance method in synchronous mode.
5. Return a list of the Ledger Payment History record created with “Ledger_Payment_History__c”

Sample Code:

/*********************Allocate sales credit to sales invoice*************************************/

// Initiate the BankAllocateCreditsAndPayments API Service

zumzum.BankAllocateCreditsAndPaymentsService objAllocateCreditsAndPaymentService = new zumzum.BankAllocateCreditsAndPaymentsService();

// Create a new wrapper to hold the Bank Allocation details and Bank Allocation Lines

zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsWrapper objAllocateCreditWrapper = new zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsWrapper();

// Provide the supplier Account ID for processing supplier allocations

objAllocateCreditWrapper.AccountId = '0013H000003sPCoQAM';

// Provide the Date for the allocation.

objAllocateCreditWrapper.PostingDate = Date.Today();

// Create the wrapper to hold the bank allocation lines

List<zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper> BankAllocateCreditsAndPaymentsLines = new 

List<zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper>();

// Add the allocation line of the unallocated Purchase Credit Line Item ledger record

zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper objPaymentLine = new zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper();

objPaymentLine.LedgerName = '0000056193';

objPaymentLine.Amount = 100;

BankAllocateCreditsAndPaymentsLines.add(objPaymentLine);

// Add the allocation line of the unpaid Purchase Invoice Line item ledger record

objPaymentLine = new zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper();

objPaymentLine.LedgerName = '0000056191';

objPaymentLine.Amount = 100;

// Add the allocation lines variable to the BankAllocateCreditsAndPaymentWrapper variable

BankAllocateCreditsAndPaymentsLines.add(objPaymentLine);

objAllocateCreditWrapper.BankAllocateLines = BankAllocateCreditsAndPaymentsLines 

// Execute the BankAllocateSupplierBalance method in the API Class

zumzum.BankAllocateCreditsAndPaymentsService.Response objResponse = objAllocateCreditsAndPaymentService.BankAllocateCustomerBalance(objAllocateCreditWrapper);

// Handle the response, error message or successful list of Ledger Payment Records

system.debug('Response>>' + objResponse.ResponseMessage);

Bulk Allocate Customer Balances 

The Zumzum Financials Bank Allocate Credits and Payments Service will accept a list of wrappers, with each wrapper containing a customer allocation wrapper, each with multiple allocation line items within the wrapper.

/*********************Bulk Allocate Sales Credit to Sales Invoice*************************************/

// Initiate the BankAllocateCreditsAndPayments API Service

BankAllocateCreditsAndPaymentsService objAllocateCreditsAndPaymentService = new BankAllocateCreditsAndPaymentsService();


// Create a new wrapper to hold the Bank Allocation details and Bank Allocation Lines

BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsWrapper objAllocateCreditWrapper = new BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsWrapper();


// Provide the supplier Account ID for processing supplier allocations

objAllocateCreditWrapper.AccountId = '00126000016gCX1';


// Provide the Date for the allocation.

objAllocateCreditWrapper.PostingDate = Date.Today();


// Create the wrapper to hold the bank allocation lines

List<BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper> BankAllocateCreditsAndPaymentsLines = new List<BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper>();


// Add the allocation line of the unallocated Purchase Credit Line Item ledger record

BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper objPaymentLine = new BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper();

objPaymentLine.LedgerName = '0000000042';

objPaymentLine.Amount = 2;

BankAllocateCreditsAndPaymentsLines.add(objPaymentLine);


// Add the allocation line of the unpaid Purchase Invoice Line item ledger record

objPaymentLine = new BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper();

objPaymentLine.LedgerName = '0000000045';

objPaymentLine.Amount = 2;


// Add the allocation lines variable to the BankAllocateCreditsAndPaymentWrapper variable

BankAllocateCreditsAndPaymentsLines.add(objPaymentLine);




objAllocateCreditWrapper.BankAllocateLines = BankAllocateCreditsAndPaymentsLines;




BankAllocateCreditsAndPaymentsService.Response objResponse = objAllocateCreditsAndPaymentService.BankAllocateCustomerBalance(objAllocateCreditWrapper);

system.debug('Response>>' + objResponse.ResponseMessage);

/**********************************************************/

Allocate Supplier Balances – BankAllocateSupplierBalance Method

The BankAllocateSupplierBalance  method is used to create Ledger Payment History records, which act as a junction object between the ledger record of the Parent Transaction and the Payment Transaction ledger record. The system then creates relationships between the Bank Payment/Receipt Records,  Credit/Invoice records and Accounts.

Sample Code: BankAllocateSupplierBalance

This example is provided to help you begin creating your own custom code.  The code will post an allocation of a supplier balance which creates a Ledger Payment History record.

Do not execute this inside of a batch processing routine, since this function will take care of the batch processing internally.

The following steps will be performed:

1. Retrieve the ledger record, of the Debtors/Creditors Control Account from the unallocated Sales/Purchase Credit Line Item.  This is the balance you wish to allocate to an unpaid Sales/Purchase Invoice Line Item.
2. Retrieve the ledger record, of the Debtors/Creditors Control Account from the unpaid Sales/Purchase Invoice Line Item. This is the sales/purchase invoice line item you wish to allocate the account balance to.
3. Prepare the data required to construct the “BankAllocateCreditsAndPaymentsWrapper” to supply as an input for the  BankAllocateSupplierBalance/BankAllocateCustomerBalance
4. Post the Bank Allocation transaction with the BankAllocateSupplierBalance/BankAllocateCustomerBalance method in sycnhrounous mode.
5. Return a list of the Ledger Payment History record created with “Ledger_Payment_History__c”

Sample Code :

/*********************Allocate Purchase credit to Purchase invoice*************************************/

// Initiate the BankAllocateCreditsAndPayments API Service

zumzum.BankAllocateCreditsAndPaymentsService objAllocateCreditsAndPaymentService = new zumzum.BankAllocateCreditsAndPaymentsService();

// Create a new wrapper to hold the Bank Allocation details and Bank Allocation Lines

zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsWrapper objAllocateCreditWrapper = new zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsWrapper();

// Provide the supplier Account ID for processing supplier allocations

objAllocateCreditWrapper.AccountId = '0013H000003sPCoQAM';

// Provide the Date for the allocation.

objAllocateCreditWrapper.PostingDate = Date.Today();

// Create the wrapper to hold the bank allocation lines

List<zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper> BankAllocateCreditsAndPaymentsLines = new List<zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper>();

// Add the allocation line of the unallocated Purchase Credit Line Item ledger record

zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper objPaymentLine = new zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper();

objPaymentLine.LedgerName = '0000056193';

objPaymentLine.Amount = 100;

BankAllocateCreditsAndPaymentsLines.add(objPaymentLine);

// Add the allocation line of the unpaid Purchase Invoice Line item ledger record

objPaymentLine = new zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper();

objPaymentLine.LedgerName = '0000056191';

objPaymentLine.Amount = 100;

// Add the allocation lines variable to the BankAllocateCreditsAndPaymentWrapper variable

BankAllocateCreditsAndPaymentsLines.add(objPaymentLine);

objAllocateCreditWrapper.BankAllocateLines = BankAllocateCreditsAndPaymentsLines;

 // Execute the BankAllocateSupplierBalance method in the API Class

zumzum.BankAllocateCreditsAndPaymentsService.Response objResponse = objAllocateCreditsAndPaymentService.BankAllocateSupplierBalance(objAllocateCreditWrapper);

// Handle the response, error message or successful list of Ledger Payment Records

system.debug('Response>>' + objResponse.ResponseMessage);

/**********************************************************/

/*********************Start Sample Bulk Allocate Purchase Credit to Purchase Invoices Script*************************************/

// Create a wrapper to hold the list of Bank Supplier Allocate Purchase Credit to Purchase Invoice wrappers

List<zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsWrapper> ListOfAllocationWrappers = new List<zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsWrapper>();

zumzum.BankAllocateCreditsAndPaymentsService objAllocateCreditsAndPaymentService = new zumzum.BankAllocateCreditsAndPaymentsService();

/*---------Example Supplier Account 1 - Create a Payment Allocation Wrapper 1 ----------------------------*/

// Create a new wrapper to hold the Bank Allocation details and Bank Allocation Lines

zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsWrapper objAllocateCreditWrapper1 = new zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsWrapper();

// Provide the supplier Account ID for processing supplier allocations

objAllocateCreditWrapper1.AccountId = '0013H000003sPCoQAM';

// Provide the Date for the allocation.

objAllocateCreditWrapper1.PostingDate = Date.Today();

// Create a Bank Allocate Credits and Payment Line Wrapper 1, for Payment Allocation Wrapper 1

List<zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper> BankAllocateCreditsAndPaymentsLines1 = new List<zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper>();

zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper objPaymentLine1 = new zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper();

// Provide the Ledger Name of the Purchase Invoice Ledger record which requires allocation

objPaymentLine1.LedgerName = '0000056195';

objPaymentLine1.Amount = 100;

// Add the allocation lines variable to the BankAllocateCreditsAndPaymentWrapper variable

BankAllocateCreditsAndPaymentsLines1.add(objPaymentLine1);

// Add the allocation line of the unpaid Purchase Invoice Line item ledger record

objPaymentLine1 = new zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper();

objPaymentLine1.LedgerName = '0000056197';

objPaymentLine1.Amount = 100;

// Add the allocation lines variable to the BankAllocateCreditsAndPaymentWrapper variable

BankAllocateCreditsAndPaymentsLines1.add(objPaymentLine1);

objAllocateCreditWrapper1.BankAllocateLines = BankAllocateCreditsAndPaymentsLines1;

ListOfAllocationWrappers.add(objAllocateCreditWrapper1);

/*---------Example Supplier Account 2 - Create a Payment Allocation Wrapper 2 ----------------------------*/

// Create a new wrapper to hold the Bank Allocation details and Bank Allocation Lines

zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsWrapper objAllocateCreditWrapper2 = new zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsWrapper();

// Provide the supplier Account ID for processing supplier allocations

objAllocateCreditWrapper2.AccountId = '0013H000004eI2XQAU';

// Provide the Date for the allocation.

objAllocateCreditWrapper2.PostingDate = Date.Today();

// Create a Bank Allocate Credits and Payment Line Wrapper 2, for Payment Allocation Wrapper 2

List<zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper> BankAllocateCreditsAndPaymentsLines2 = new List<zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper>();

zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper objPaymentLine2 = new zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper();

// Provide the Ledger Name of the Purchase Invoice Ledger record which requires allocation

objPaymentLine2.LedgerName = '0000056199';

objPaymentLine2.Amount = 100;

// Add the allocation lines variable to the BankAllocateCreditsAndPaymentWrapper variable

BankAllocateCreditsAndPaymentsLines2.add(objPaymentLine2);

// Add the allocation line of the unpaid Purchase Invoice Line item ledger record

objPaymentLine2 = new zumzum.BankAllocateCreditsAndPaymentsService.BankAllocateCreditsAndPaymentsLineWrapper();

objPaymentLine2.LedgerName = '0000056201';

objPaymentLine2.Amount = 100;

// Add the allocation lines variable to the BankAllocateCreditsAndPaymentWrapper variable

BankAllocateCreditsAndPaymentsLines2.add(objPaymentLine2);

objAllocateCreditWrapper2.BankAllocateLines = BankAllocateCreditsAndPaymentsLines2;

ListOfAllocationWrappers.add(objAllocateCreditWrapper2);

// Execute the BankAllocateSupplierBalance method in the API Class

zumzum.BankAllocateCreditsAndPaymentsService.Response objResponse = objAllocateCreditsAndPaymentService.BankAllocateSupplierBalance(ListOfAllocationWrappers);

// Handle the response, error message or successful list of Ledger Payment Records

system.debug('Response>>' + objResponse.ResponseMessage);