Bank Customer Receipt API

Overview

The Zumzum Financials Bank Customer Receipt API service provides the following capabilities

• Create a Bank Customer Receipt in the system and allocate payment to Sales Invoice line items.
• Post a Bank Customer Receipt as a customer Payment On Account.
• Bulk create Bank Customer Receipt in the system and allocate payment to Sales Invoice line items.
• Bulk create Bank Customer Receipt as a customer Payment On Account.

Bank Customer Receipt Description

The Bank Customer Receipt Service provides the capability to allocate Bank Receipts to Sales Invoice Line Items in Zumzum Financials.  The system will take care of  tracking paid and unpaid amounts against Sales Invoices.  You should be aware of the following:

• Bank Receipts are automatically posted to the Zumzum Financials general ledger.
• When using the BankCustomerReceiptService Apex class, you will be creating the following records
  • Batch Bank Receipt
  • Bank Receipt
  • Bank Receipt Line Item
  • Ledger
  • Ledger Payment History (Allocations to Sales Invoice Line Items)

• All Bank Receipt Line Item values will need to be provided as a positive number as negative amounts are not supported.
• If you wish to reverse a Bank Customer Receipt  then you will need to post an alternative transactions, e.g. a Sales Credit and Bank Customer Refund (both should be included in your Bank Reconciliation process)
• You are unable to un post or delete a Bank Receipt and it’s associated records once you have posted to the ledger.
• The Bulk Create Bank Customer Receipt and Bulk Create Bank Customer Payment on Account methods support a maximum of 40 accounts per API call.

The BankCustomerReceiptService function will accept the list of ‘BankCustomerReceiptWrapper’ as an input parameter.  Below are the required fields when a Bank Receipt is created.

BankCustomerReceiptWrapper API Fields

The BankCustomerReceiptService function will accept the list of ‘BankReceiptLine’ as an input parameter.  Below are the required fields when allocating a Bank Customer Receipt line to a Sales Invoice Line item.

Note:  You would query your unpaid Sales Invoice Line items and then find the Ledger record of the Debtors Control Account so that you may pass the Ledger Name as a variable to the BankReceiptLine list.

BankReceiptLine API Fields

The BankCustomerReceipt Service will accept the list of ‘APICustomFieldWrapper’ as an input parameter.  Once you have created your custom fields on this object, you would be able to pass those as variables to the API for creating and updating records.  Below are the required fields when creating adding custom fields to your API call.

APICustomFieldWrapper API Fields

Create a Bank Customer Receipt – CreateBankCustomerReceipt Method

Below is information related on how to allocate customer receipts to Sales Invoice Line Items with the Bank Customer Receipt API service using Apex code.  Zumzum Financials includes a global class called BankCustomerReceiptService which you may call from your own Apex code. The CreateBankCustomerReceipt method is used to insert a Batch Bank Receipt record, with a  Bank Receipt, Bank Receipt Lines, ledger records and Ledger Payment History (Payment Allocations). The service returns a list of Bank Receipt records created.

Sample Code: Create Bank Customer Receipt

This example is provided to help you begin creating your own custom code.

The code will post a single Batch Bank Receipt record, with a Bank Receipt Line, two ledger records and one Ledger Payment History (Payment Allocations).

The following steps will be performed:

1. Prepare the list collection “List<BankCustomerReceiptWrapper>” to supply as an input for the CreateBankCustomerReceipt function.
2. Prepare the list collection “List<BankReceiptLine>” to supply as an input for the CreateBankCustomerReceipt function.
3. Create the Bank Customer Receipt
4. Return a list of the Bank Receipt created with “Bank_Receipt__c”

Sample Code :

/**************Create Bank Customer Receipt*****************************/

// Initiate A New Bank Customer Receipt 

zumzum.BankCustomerReceiptService objCustomerReceiptService = new zumzum.BankCustomerReceiptService();

// Create Bank Customer Receipt Wrapper 

zumzum.BankCustomerReceiptService.BankCustomerReceiptWrapper objReceiptWrapper = new zumzum.BankCustomerReceiptService.BankCustomerReceiptWrapper();

// Provide the Customer Account ID

objReceiptWrapper.AccountId = '0013H000002bIDHQA2';

// Provide the Customer Payment Transaction Date

objReceiptWrapper.PostingDate = Date.Today();

// Provide the Bank Account ID

objReceiptWrapper.BankAccountId = 'a0K3H000000ExmXUAS';

// Create a wrapper to contain the Custom API Fields

objReceiptWrapper.WrapperAPICustomFields = new List<zumzum.APICustomFieldWrapper>();

// Add the custom fields to the WrapperAPICustomFields

objReceiptWrapper.WrapperAPICustomFields.add(new zumzum.APICustomFieldWrapper('Zumzum__Bank_Receipt__c','Zumzum__Cheque_Number__c','bank receipt created using api service'));

// Create a list of Bank Receipt Line items for the Bank Customer Receipt.

List<zumzum.BankCustomerReceiptService.BankReceiptLine> listPaymentLines = new List<zumzum.BankCustomerReceiptService.BankReceiptLine>();

// Add a bank receipt line item 1

zumzum.BankCustomerReceiptService.BankReceiptLine objPaymentLine = new zumzum.BankCustomerReceiptService.BankReceiptLine();

// Add the Ledger Name and Amount to the Bank Receipt Line item

objPaymentLine.LedgerName = '0000056131';

objPaymentLine.Amount = 28.80;

// Create a wrapper to add customer API fields to the Bank Receipt Line item 

objPaymentLine.WrapperAPICustomFields = new List<zumzum.APICustomFieldWrapper>();

// Add the Bank Receipt Line item to the list of bank receipt line items

listPaymentLines.add(objPaymentLine);

//Add the bank receipt line items to the list of bank receipt line items

listPaymentLines.add(objPaymentLine);

objReceiptWrapper.BankReceiptLines = listPaymentLines;

// Execute the command to create the Bank Customer Receipt.

zumzum.BankCustomerReceiptService.Response objResponse = objCustomerReceiptService.CreateBankCustomerReceipt(objReceiptWrapper);

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

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

/**************Start Create Bank Customer Payment On Account Sample Script*****************************/

// Initiate A New Bank Customer Receipt 

zumzum.BankCustomerReceiptService objBankCustomerReceiptService = new zumzum.BankCustomerReceiptService();

// Create Bank Customer Receipt Wrapper

zumzum.BankCustomerReceiptService.BankCustomerReceiptWrapper objReceiptWrapper = new zumzum.BankCustomerReceiptService.BankCustomerReceiptWrapper();

// Provide the Customer Account ID

objReceiptWrapper.AccountId = '0013H000002bIDHQA2';

// Provide the Customer Payment Transaction Date

objReceiptWrapper.PostingDate = Date.Today();

// Provide the Bank Account ID

objReceiptWrapper.BankAccountId = 'a0K3H000000ExmXUAS';

// Provide the Bank Customer Receipt Tax Rate

objReceiptWrapper.TaxRate = 'a173H0000008OciQAE';

// Provide the Customer Payment On Account Amount

objReceiptWrapper.BankReceiptAmount = 1000;

// Execute the command to post the Bank Customer Payment On Account

zumzum.BankCustomerReceiptService.Response objResponse = objBankCustomerReceiptService.PostBankCustomerPaymentOnAccount(objReceiptWrapper);

// Receive a response of the Bank Receipt records created

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

/**************End Create Bank Customer Payment On Account Sample Script********************************************/

/*****Start Sample Code Bulk Create Bank Customer Receipts For Multiple Accounts With Multiple Lines (with IgnoreError=true)**************/

// Declare the ID of the Bank Account to process the payments.

Id bankAccountID = 'a0K3H000000ExmXUAS';

// (Optional) Declare the ID of the Tax Rate to process the payments.

Id taxrate = 'a173H0000008OciQAE';

// Declare the variable to hold a unique Set of Account IDs

Set<string> salesInvoiceIds = new Set<string>();

// Query the system to retrieve a list of Sales Invoices/Lines to be paid.

for(Sales_Invoice__c pi : [Select id,name,Account__c FROM Sales_Invoice__c Where Status__c='Posted' order by createddate desc limit 2]){

salesInvoiceIds.add(pi.id);

}

// Create a new instance of the Bank Customer Receipt Object.

zumzum.BankCustomerReceiptService objCustomerReceiptService = new zumzum.BankCustomerReceiptService();

// Create the Bank Customer Receipt Wrapper to hold the list of Bank Customer Receipts.

List<zumzum.BankCustomerReceiptService.BankCustomerReceiptWrapper> listOfBankReceiptWrapper = new List<zumzum.BankCustomerReceiptService.BankCustomerReceiptWrapper>();

// Add a map to store the list of Sales Invoices and ledger Records

map<id,List<Ledger__c>> mapOfLedgersBySI = new map<id,List<Ledger__c>>();

map<id,Sales_Invoice__c> mapOfsI = new map<id,Sales_Invoice__c>([Select id,name,Account__c FROM Sales_Invoice__c Where ID IN: salesInvoiceIds]);

// Query the system to retrieve a list of ledger records per sales invoice line item

for(Ledger__c ldgr : [Select id,Name,Foreign_Gross_Total__c,Sales_Invoice__c,Customer_Supplier_Account_Name__c From Ledger__c Where Sales_Invoice__c IN: salesInvoiceIds AND Customer_Supplier_Account_Name__c <> '' AND Show_On_Transaction__c = 1 AND Paid__c = 'N']){

List<Ledger__c> lstLedger = mapOfLedgersBySI.get(ldgr.Sales_Invoice__c);

if(lstLedger == null){

lstLedger = new List<Ledger__c>();

}

lstLedger.add(ldgr);

mapOfLedgersBySI.put(ldgr.Sales_Invoice__c,lstLedger);

}

Integer indx=1;

for(Sales_Invoice__c salesInvoice : mapOfSI.values()){

List<Ledger__c> lstLedger = mapOfLedgersBySI.get(salesInvoice.id);

if(lstLedger == null || lstLedger.isempty()){

continue;

}

// Add the list of Customer Accounts to the Bank Customer Receipt Wrapper.

zumzum.BankCustomerReceiptService.BankCustomerReceiptWrapper objReceiptWrapper = new zumzum.BankCustomerReceiptService.BankCustomerReceiptWrapper();

objReceiptWrapper.AccountId = '0013H000002bIDHQA2';

objReceiptWrapper.PostingDate = Date.Today();

objReceiptWrapper.BankAccountId = 'a0K3H000000ExmXUAS';

if(indx > 1){

objReceiptWrapper.AccountId = '0013H000002bIDHQA2';

}

// Add the list of ledger records to be included in the Bank Receipt Lines to be paid.

List<zumzum.BankCustomerReceiptService.BankReceiptLine> listPaymentLines = new List<zumzum.BankCustomerReceiptService.BankReceiptLine>();

zumzum.BankCustomerReceiptService.BankReceiptLine objPaymentLine;

for(Ledger__c l : lstLedger){

objPaymentLine = new zumzum.BankCustomerReceiptService.BankReceiptLine();

objPaymentLine.LedgerName = l.name;

objPaymentLine.Amount = 100;

listPaymentLines.add(objPaymentLine);

}

objReceiptWrapper.BankReceiptLines = listPaymentLines;

listOfBankReceiptWrapper.add(objReceiptWrapper);

indx++;

}

// Execute the command to process the list of Bank Customer Receipts.

zumzum.BankCustomerReceiptService.Response objResponse = objCustomerReceiptService.CreateBankCustomerReceipt(listOfBankReceiptWrapper,true);

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

system.debug('BankReceipts>>' + objResponse.BankReceipts);

/****End Sample Code Bulk Create Bank Customer Receipts For Multiple Accounts With Multiple Lines (with IgnoreError=true)***************************************************/

1. Prepare the list collection “List<BankCustomerPaymentWrapper>” to supply as an input for the PostBankCustomerPaymentOnAccount function.
2. Post the Bank Customer Payment On Account
3. Return a list of the Bank Receipt created with “Bank_Receipt__c”

Sample Code :

/*******Start Sample Post Bank Customer Payment on multiple account (with IgnoreError=true)**********/

// Declare the ID of the Bank Account to process the payments.  

Id bankAccountID = 'a037E00000AupT8';

//Declare the ID of the Tax Rate to process the payments.  

Id taxrate = 'a1H7E000001pFha';

zumzum.BankCustomerReceiptService objCustomerReceiptService = new zumzum.BankCustomerReceiptService();

// Declare the variable to hold a unique Set of Account IDs 

Set<string> acctIds = new Set<string>();

// Query the system to retrieve a list of Customer Accounts to process payments on account. 

for(Account acc : [Select id,name from account where Type='Customer' limit 2]){

acctIds.add(acc.id);

}

// Create the Bank Customer Receipt Wrapper to hold the list of Bank Customer Payment On Account. 

List<zumzum.BankCustomerReceiptService.BankCustomerReceiptWrapper> listOfBankReceiptWrapper = new List<zumzum.BankCustomerReceiptService.BankCustomerReceiptWrapper>();

decimal amt = 1;

integer indx=1;

for(string accId : acctIds){

// Initiate a new instance of the Bank Customer Receipt Object

zumzum.BankCustomerReceiptService.BankCustomerReceiptWrapper objReceiptWrapper = new zumzum.BankCustomerReceiptService.BankCustomerReceiptWrapper();

// Add the data to the each Customer payment on account to the wrapper

objReceiptWrapper.AccountId = accId;

objReceiptWrapper.PostingDate = Date.Today();

objReceiptWrapper.BankAccountId = bankAccountID;

objReceiptWrapper.TaxRate = taxrate;

objReceiptWrapper.BankReceiptAmount = amt;

if(indx > 1){

objReceiptWrapper.TaxRate = null;       

}

// Add each Customer payment on account to the list of bank receipts to process

listOfBankReceiptWrapper.add(objReceiptWrapper);

amt++;

indx++;

}

// Execute the command to create Bank Customer Payments on Account with IgnoreErrors as true

zumzum.BankCustomerReceiptService.Response objResponse = objCustomerReceiptService.PostBankCustomerPaymentOnAccount(listOfBankReceiptWrapper,true);

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

system.debug('BankReceipts>>' + objResponse.BankReceipts);

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

Below are a list of error codes that are returned by the Bank Customer Receipt Service.