This chapter presents an overview of Oracle Communications Billing and Revenue Management (BRM) payments and payment processing.
Before reading this chapter, you should have a basic understanding of BRM concepts. See ”Introducing BRM” in BRM Concepts.
A payment consists of the amount and method by which customers pay their bills. There are several different payment methods available in BRM, depending on the type of payment processing your company performs: BRM-initiated, or externally initiated.
When payments are received in BRM, a payment event is recorded, and the BRM system creates a payment accounts receivable (A/R) item. Payments can be submitted to BRM automatically, by a payment processor, or manually, by using Payment Tool.
You use Customer Center to search for and review customer payments. You can view the payment amount, payment date, payment method, and other payment attributes.
For information on accounts receivable, see ”About Accounts Receivable” in BRM Managing Accounts Receivable.
There are two types of payment processing in BRM: BRM-initiated and externally initiated. All payments received in BRM fall into one of these categories.
BRM-initiated payment processing is triggered by BRM and requires no action from customers. Payments processed in this way are those for which a customer is automatically charged, such as credit card and direct debit payments.
To begin processing such payments, BRM sends a customer's payment information to your online payment processor. The payment processing service charges the customer's credit card or checking account, and then BRM automatically allocates the payment and updates the customer's account balance. Any outstanding payment items are closed, and no A/R management is required by a customer service representative (CSR).
For more information, see "About BRM-Initiated Payment Processing".
You use the "pin_collect" utility to collect BRM-initiated payments. This utility is typically run automatically by one of the billing scripts. The customer's credit card or checking account is charged by your payment processor, and then the payments are sent to the BRM Payment Data Manager (DM).
You can use multiple payment processors and configure multiple Data Managers to handle payment processing.
For more information on collecting BRM-initiated payments, see "About BRM-Initiated Payment Processing".
The following BRM-initiated payment methods are supported:
Note:Only debit cards that do not require a personal identification number (PIN) are supported in BRM.
For information on creating new payment methods, see ”Customizing Payment Methods” in BRM Managing Customers.
Externally initiated payments, such as cash or check payments, are triggered by an action from a financial institution. They are usually in response to an invoice that was sent to the customer.
Typically, after such payments are received from a customer, they are sent to a bank. The bank then initiates the payment processing by sending you a list of payments that have been received and deposited. If the bank sends the payment information through a directly integrated third-party service (payment gateway), BRM automatically allocates the payments and updates the customer's account balance. If the payment information is not sent through a payment gateway, you use Payment Tool to allocate the payment and update the account. See "Managing Externally Initiated Payments" for more information.
You use Payment Tool or a third-party payment application to collect externally initiated payments and post them in BRM.
For information on processing externally initiated payments, see "Managing Externally Initiated Payments".
The following externally initiated payment methods are supported in BRM:
For information on creating new payment methods, see ”Customizing Payment Methods” in BRM Managing Customers.
A payment method is the mode by which customers pay their bills. The payment method is selected for an account when the account is created, but it can be changed at any time.
Important:You can set up multiple payment methods for an account, and assign a different one to each bill unit in an account, but you can use only one payment method per bill unit.
By default, BRM supports the following payment methods:
When you add a new payment method, you must update the /config/payment storable object.
For a complete list of payment methods defined in your BRM system, see the pin_pymt.h file.
For information on creating custom payment methods, see ”Customizing Payment Methods” in BRM Managing Customers.
Customer payment information contains sensitive data such as account numbers. BRM supports the masking of such data in system responses and logging for protecting customer data. For information on masking payment information, see "About Securing Sensitive Customer Data with Masking" in BRM Managing Customers.
Customers who pay their bills with cash, checks, or postal orders usually have the Invoice payment method defined in their accounts. You handle cash. check, and postal order payments by using Payment Tool.
For more information, see Payment Tool Help.
Credit card payments are BRM-initiated; therefore they are submitted directly to BRM by the Payment DM. Because some credit card payments are made automatically, accounts that pay bills by these methods should always use the balance forward billing type. See ”About Accounting Types” in BRM Configuring and Running Billing.
When a customer registers for a credit card payment method, BRM attempts to validate the card by default. See ”Validating Credit Cards at Registration” in BRM Managing Customers.
When a credit card payment is made, BRM returns a confirmation number that the customer can use to identify the payment. See "About Credit Card Payment Confirmation Numbers".
Important:Debit cards that are controlled by credit card companies, such as Visa and MasterCard, are supported by BRM; debit cards that require a personal identification number (PIN) to make purchases are not.
If a customer uses the direct debit payment, the customer's bank account is debited automatically each billing cycle. Direct debit charges are verified by the bank routing number and the checking account number.
Because some direct debit payments are made automatically, accounts that pay bills by this method should use the balance forward billing type. See ”About Accounting Types” in BRM Configuring and Running Billing.
Direct debit payments are BRM-initiated and are therefore submitted directly to BRM by a payment processor.
Note:BRM supports direct debit only in the United States and Canada.
For information on BRM-initiated payment processing, see "About BRM-Initiated Payment Processing".
Accounts that use the Invoice payment method pay by check, cash, or other externally initiated payment methods. By default, accounts that use an Invoice payment method receive invoices on a monthly basis.
You use Payment Tool to process invoice-generated payments. For more information, see Payment Tool Help.
Customers who use the Prepaid payment method pay for service usage in advance. They send check or cash payments and can also pay by using a prepaid voucher.
With prepaid balances, the customer is always expected to have a credit (negative) balance. For example, when an IP telephony customer pays $10 for 100 minutes of usage, the account currency balance is -10 US Dollars. As the customer makes calls, the balance increases until the credit limit (0) is reached.
Accounts that have prepaid balances should use balance forward accounting because payments are made before there is a due amount. (With open item accounting, you are billed only for open items that are due.)
When you run billing, no collection process is performed on prepaid balances because they are paid in advance of billing.
With prepaid balances, there is no credit risk, because customers cannot use services until they have paid for them.
Accounts that use the Paid by parent account payment method are child accounts. These accounts have a nonpaying (subordinate) bill unit. Their bill is paid by their parent accounts. If a child account has two bill units (and thus two bills), one paying and one nonpaying, the child account can pay one bill and the parent account pays the other. See ”About Account Groups” in BRM Concepts.
Accounts with the Undefined payment method never receive a payment request. When accounting and billing cycles occur, billing utilities that request payments ignore undefined accounts.
Undefined accounts require a login name and password so customers can be authenticated and authorized. You can only assign an undefined payment method to an account during account creation.
Revenue generated from undefined accounts is recorded as general ledger (G/L) data.
You typically use undefined accounts for free trial offers. Creating an undefined account enables a customer to register without having to submit a credit card number.
You can also use undefined accounts for testing BRM and for creating CSR accounts.
Even though accounts that use the Undefined payment method are never billed, credit limits are still enforced. This is because credit limits are enforced by rating, not billing. Because undefined accounts are not billed, the balance is never reduced. When the credit limit is reached, the account is inactivated, or the customer cannot log in due to authorization failure.
To avoid this, create an unlimited credit limit for undefined accounts. You can do this in plans designed specifically for those types of accounts or by adjusting account-specific credit limits in Customer Center.
To provide voucher payments for your customers, you must have Voucher Manager and Voucher Administration Center installed.
By default, vouchers are not a standard payment method that can be assigned to an account; they can only be applied manually. When a customer buys a voucher, either a CSR or the customer enters the voucher ID & PIN into a CRM tool such as Customer Center, and BRM validates the voucher and transfers its prepaid resources to the specified account balance.
Voucher payments cannot be handled by the BRM-initiated payment process or by Payment Tool.
For more information, see ”About Managing Voucher Inventory” in BRM Telco Integration.
Wire transfers include any transfer of money from a customer's bank account to your company or to your company's payment processor through an automated teller machine (ATM), computer, telephone, or the like.
Customers who pay their bills with wire transfer payments usually have the Invoice payment method defined in their accounts.
You handle wire transfer payments by using Payment Tool. For more information, see Payment Tool Help.
For information about how BRM uses payment methods, see "About Payment Methods".
To find /payinfo objects that belong to an account, use the PCM_OP_CUST_FIND_PAYINFO opcode.
This opcode is given the account POID and returns the information from the storable /payinfo object.
This section describes a subset of the payment attributes that help characterize each payment:
The account number identifies the account in BRM to which the payment is applied. If the account number is missing or incorrect, BRM uses the bill number to guide the payment to the correct account. The bill number therefore identifies a specific bill and determines to which bill the payment applies and is typically allocated.
The payment method identifies how customers pay their bill (for example, by credit card or check). See "About Payment Methods".
You use Customer Center to manage the payment method for an account. For more information, see the Customer Center Help.
The payment channel identifies how the payment was sent to your third-party payment processor, such as by the Internet or Voice over IP (VOIP). You can create custom payment rules based on the payment channel ID; for example, you can grant a payment incentive if customers pay their bills over the Internet.
For more information, see "Configuring Payment Channels".
The payment status identifies the success or failure of a payment when it is received. BRM uses the status code to determine how to process each payment. The status description is displayed in Payment Tool to assist payment clerks in handling externally initiated payment batches.
For more information, see "About Payment Status".
All payments in a payment batch contain the same batch ID. This helps you to identify payments that do not contain a payment ID.
BRM uses the payment transaction ID to internally manage A/R and to identify payment transactions that occurred between BRM and the payment processor. All BRM-initiated payments, such as credit card and direct debit payments, contain a transaction ID.
BRM identifies failed transactions by keeping a record of each transaction in the BRM database. For information on resolving failed BRM-initiated payment transactions, see "Resolving Failed BRM-Initiated Payment Transactions".
If unconfirmed payment processing is enabled in your BRM system, when a failed unconfirmed payment is received, BRM identifies the original successful payment by using its transaction ID. For more information on unconfirmed payment processing, see "About Unconfirmed Payment Processing".
Important:The maximum length of a payment transaction ID is 16 characters for BRM-initiated payments and 30 characters for externally initiated payments. If your company generates transaction IDs by appending characters to the payment batch IDs, ensure that the batch IDs are short enough to be within the limit after the additional characters are appended. If the payment transaction ID does not comply with the length restrictions, BRM does not generate an ID for the payment. (BRM-initiated payment transaction IDs are restricted by Paymentech processing requirements.)
The subtransaction ID identifies a payment that was reversed due to suspended payment recycling. BRM uses subtransaction IDs internally to track a recycled payment back to its original payment. The subtransaction ID of a recycled payment is the same as the transaction ID of the payment from which it originated.
Payments that have never been recycled have a SUB_TRANS_ID value of NULL.
For information on Payment Suspense Manager and tracking suspended payments, see "How BRM Tracks Suspended Payments".
Before payments can be processed and posted by BRM, they must pass validation. Payment validation is initiated automatically, through the payment gateway, or manually, by a payment clerk. When a payment arrives in BRM, the PCM_OP_PYMT_COLLECT opcode calls the PCM_OP_PYMT_VALIDATE_PAYMENT opcode to perform the validation. BRM validates the payment information in the input flist and, in the output flist, indicates whether the opcode successfully performed the validation.
The PIN_FLD_STATUS value returned by the opcodes indicates whether the payment arrived in BRM as successful or failed for financial reasons. If you have the Payment Suspense Manager functionality installed, payments can also arrive as suspended. See "About Payment Suspense Manager" for more information on payment suspense.
If the payment is successful and passes the validation process, the PIN_FLD_STATUS value is PIN_PYMT_SUCCESS, and BRM posts the payment to the account.
If the payment meets the validation criteria, but fails for financial reasons, the PIN_FLD_STATUS value is PIN_PYMT_FAILED, and BRM posts the payment to the account as a failed payment.
If the payment status is marked for suspense, the PIN_FLD_STATUS value is PIN_PYMT_SUSPENSE, and PCM_OP_PYMT_COLLECT calls the PCM_OP_PYMT_POL_SUSPEND_PAYMENT policy opcode to process the payment. For more information about suspended payment validation, see "About Payment Validation".
If an account-level payment is made to an account with multiple bill units, the PCM_OP_PYMT_POL_VALIDATE_PAYMENT opcode validates that the payment is an account-level payment and the account has multiple bill units. If the payment is successful and passes the validation process, it adds the reason ID, PIN_REASON_ID_MBI_DISTRIBUTION_REQD to the PIN_FLD_PAYMENT_REASONS array in the output flist. This reason ID helps in later payment processing by distinguishing a normal payment from an account-level payment made to an account with multiple bill units.
If the payment fails the validation, BRM informs you that the payment cannot be posted. For example, if a payment specifies no account number and no bill number, BRM cannot post the payment. You must create an exception batch to handle payments that fall into this category.
For more information on payment status, see "About Payment Status".
For information specific to BRM-initiated payment validation, see "Changing How BRM Handles Paymentech Authorization Return Codes".
BRM uses the PIN_FLD_STATUS field of a payment to validate payments before they are posted in BRM. By default, payments are received with a status of successful, failed, or invalid.
Successful payments are automatically posted to the account to which they belong. The payment amount is removed from the current balance on the account, and any remaining amount is allocated according to your business policies. Failed payments are payments that are declined for financial reasons, such as an overdrawn account or an expired credit card. Invalid payments are payments that cannot be posted correctly for the following reasons:
The account that the payment applies to is closed.
Both the account number and the bill number are incorrect and cannot be found in BRM.
The POID for the account number does not exist in BRM.
If the Payment Suspense Manager feature is enabled, payments can have a status of suspended.
Value ranges for the PIN_FLD_STATUS field:
Successful payments have a value >= PIN_PYMT_SUCCESS and < PIN_PYMT_SUSPENSE. The numeric range for successful payments is 0-14.
Suspended payments have a value >= PIN_PYMT_SUSPENSE and < PIN_PYMT_FAILED. This range includes payments that arrive in BRM as failed for financial reasons, but that also meet the criteria for suspending a payment. The numeric range for suspended payments is 15-29.
Failed payments have a value >= PIN_PYMT_FAILED and < PIN_PYMT_STATUS_MAX. The numeric range for financially failed payments is 30-44.
Payments with a status >= PIN_PYMT_STATUS_MAX are not supported by BRM.
If a payment is invalid, you must manually fix it before it can be posted in BRM, unless the Payment Suspense Manager feature is enabled. In such cases, invalid payments might be received as suspended.
The following values described in Table 1-1 are assigned by default:
The payment was automatically posted to the account to which it belongs. The payment amount is removed from the current balance on the account, and any remaining amount is allocated according to your business policies.
Status codes 1 through 14 are configurable. If you have the Payment Suspense Manager feature enabled, they can also be used for payments successfully recycled from suspense to a customer account.
The payment was successfully applied to a written-off account.
The write-off reversal feature must be enabled. See ”Configuring Write-off and Write-off Reversals” in BRM Managing Accounts Receivable.
This status code is not used for recycled payments.
The Payment Suspense Manager feature must be enabled. See "Configuring Payment Suspense Manager".
The payment arrived in BRM as failed for financial reasons but meets the criteria for suspending a payment. Failed suspended payments are saved to the payment suspense account.
This status code is used only for payments that originally post to the suspense account. It is not used for recycled payments.
The Payment Suspense Manager feature must be enabled. See "Configuring Payment Suspense Manager".
The payment was generated for an amount that remains in the payment suspense account after an original payment has been partially distributed to customer accounts. You can continue to generate distributed payments until this remaining suspended payment is used up.
For example, an original payment fails validation and enters BRM as a suspended payment with a payment status of PIN_PYMT_SUSPENSE. The original payment is then partially distributed and a new suspended payment is generated for the remainder. This new suspended payment is assigned a status of PIN_PYMT_RECYCLED_SUSPENSE.
The payment was distributed to a customer account from the payment suspense account but was then resuspended.
The payment does not comply with the financial practices of your company because, upon collection, it has been dishonored or rejected by the bank. For example, payments can fail due to expired credit cards, incorrect account details, or insufficient funds.
Payments with a value equal to or greater than 45 are not supported by BRM.
Payment allocation is the process of applying a payment toward an account's open items, balancing all credits and debits, and then closing all balanced items.
Payments are allocated automatically by BRM or manually by a payment clerk. BRM-initiated payments for credit card or direct debit accounts are automatically allocated during the collection process; externally initiated payments for invoice accounts are allocated by a clerk or CSR through Payment Tool or Customer Center.
The allocation level determines how the funds are applied:
When a payment is made at account-level (without specifying bill or item), the payment can be allocated to accounts with single bill unit or multiple bill units.
Payment allocated to accounts with single bill unit: Payment is allocated to the items of the bill unit that contains the default balance group for the account and update the account balance accordingly. When a payment is applied to an account as unallocated, the account balance is updated but the open bills and bill items are not closed. Unallocated payments can be allocated to specific bills and items at any time by using Customer Center or your CRM application.
Payment allocated to accounts with multiple bill units: Payment is distributed to different bill units of the account based on distribution logic implemented in the PCM_OP_PYMT_POL_MBI_DISTRIBUTE policy opcode.
Payments allocated to one or more bills close the bills and the account balance is updated accordingly.
By default, bill allocation is determined during payment validation. BRM uses the bill number to find the correct bill. If the bill number is missing or cannot be found, BRM uses the bill amount to find the correct bill. If neither the bill number nor the bill amount can be determined, BRM allocates the payment to the oldest bills first, because they are collected first.
Note:You cannot allocate a payment to a nonpaying (subordinate) bill unit of a child account.
Payments allocated to one or more items close each item and update the balance accordingly. If all items in a bill are closed, the bill is also closed. Item-level allocation also updates the account balance.
Underpayments and overpayments may also require allocation. See "Handling Overpayments and Underpayments".
An account-level payment applied to an account with multiple bill units may also require allocation. See "Allocating Account-Level Payments to Multiple Bill Units".
For information on how to allocate payments in Payment Tool, see "About Allocating Payments".
If an account-level payment is made to an account having multiple bill units, you can allocate the payment to multiple bill units of the account.
Note:The Payment Suspense Management feature must be enabled in your BRM system for you to allocate account-level payments to multiple bill units. For more information, see "Enabling Payment Suspense in BRM".
To allocate an account-level payment to multiple bill units of an account, BRM calls the PCM_OP_PYMT_COLLECT opcode. PCM_OP_PYMT_COLLECT performs the following operations:
Opens a transaction.
Calls the PCM_OP_PYMT_VALIDATE_PAYMENT opcode to validate the payment.
PCM_OP_PYMT_VALIDATE_PAYMENT invokes the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode to validate the payment. This policy opcode:
Checks the appropriate /config/business_params objects to find out if Payment Suspense Manager is enabled.
Checks that the payment is an account-level payment and that the account has multiple bill units.
If the payment is successful and passes the validation process, adds the reason ID, PIN_REASON_ID_MBI_DISTRIBUTION_REQD to the PIN_FLD_PAYMENT_REASONS array in the output flist.
Note:For failed or suspended payments, the PCM_OP_PYMT_POL_VALIDATE_PAYMENTpolicy opcode does not add the PIN_REASON_ID_MBI_DISTRIBUTION_REQD reason ID.
Calls the PCM_OP_PYMT_MBI_DISTRIBUTE opcode to distribute the payment to multiple bill units. The PCM_OP_PYMT_MBI_DISTRIBUTE opcode invokes the PCM_OP_PYMT_POL_MBI_DISTRIBUTE policy opcode if the following conditions are true:
The PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode returns the PIN_REASON_ID_MBI_DISTRIBUTION_REQD reason ID.
The PIN_FLD_SELECT_STATUS field in the input flist of PCM_OP_PYMT_COLLECT is not PIN_SELECT_STATUS_MBI_DISTRUBUTED.
PCM_OP_PYMT_POL_MBI_DISTRIBUTE distributes the payment according to the default distribution logic. You can customize how payments are distributed by using the PCM_OP_PYMT_POL_MBI_DISTRIBUTE policy opcode. This policy opcode searches for all the open /bill objects of all the /billinfo objects for the given /account object, sorted by the bill due date.
PCM_OP_PYMT_POL_MBI_DISTRIBUTE returns the PIN_FLD_BILLINFO array that contains an array of PIN_FLD_BILLS having the distributed payment amount for each bill. The PIN_FLD_BILLINFO array is added to the output flist of PCM_OP_PYMT_MBI_DISTRIBUTE, which is passed to the PCM_OP_PYMT_SELECT_ITEMS opcode to get item-level distribution.
Calls the PCM_OP_PYMT_SELECT_ITEMS opcode for item-level payment distribution for each bill unit.
If the reason ID in the output flist of PCM_OP_PYMT_SELECT_ITEMS is PIN_REASON_ID_MBI_DISTRIBUTION_REQD, PCM_OP_PYMT_COLLECT detaches the distribution part from the output flist to use later while recycling payment.
If the reason ID in the output flist of PCM_OP_PYMT_SELECT_ITEMS is PIN_REASON_ID_MBI_DISTRIBUTION_REQD and the PIN_FLD_STATUS value is successful (value in the range of 0 to 14), PCM_OP_PYMT_COLLECT changes the status to PIN_PYMT_SUSPENSE to suspend the payment before calling the PCM_OP_PYMT_POL_PRE_COLLECT policy opcode.
Calls the PCM_OP_PYMT_POL_PRE_COLLECT policy opcode to perform policy checks before the payment occurs.
Calls the PCM_OP_PYMT_POL_SUSPEND_PAYMENT policy opcode to get the suspense account.
Calls the PCM_OP_BILL_RCV_PAYMENT opcode to record the payment and create the payment item.
Prepares the input flist of the PCM_OP_PYMT_RECYCLE_PAYMENT opcode by using the distribution detached from PCM_OP_PYMT_SELECT_ITEMS.
Calls PCM_OP_PYMT_RECYCLE_PAYMENT to distribute the suspended payment to multiple bill units.
Prepares the output flist for PCM_OP_PYMT_COLLECT such that the output flist contains all the payment events created as a result of the recycle payment.
Payment reversals are necessary when a payment is recorded in the BRM database, but the payment is not deposited. Reversing the payment enables BRM to treat the payment as if it never happened.
Payments are reversed in BRM for a variety of reasons, the most common of which is that the funds for a payment are never actually deposited (for example, when a check does not clear).
When a payment is reversed, any bills or items previously closed by the payment are reopened, and the payment is deactivated in the BRM system.
There are three types of reversals in BRM:
The last two reversal types are related to payment suspense. For more information on reversals related to payment suspense, see "How Direct Reversals and Refunds Relate to Suspense".
Direct reversals occur when you use Payment Tool or a third-party application to manually reverse a payment that was recorded in the BRM database but never actually deposited. They remove an active payment completely from the system and reopen any bills and items so the payment can be made again.
Direct reversals are the most frequent type of reversal in BRM, and they occur outside of the suspense and recycling processes. Unlike reversals that occur during recycling, direct reversals are not initiated by the creation of a new recycled payment.
BRM uses the PCM_OP_BILL_REVERSE opcode to process direct reversals. For more information, see "How BRM Reverses Payments".
Indirect reversals occur when you transfer a suspended payment to a customer account or from a customer account to suspense. With an indirect reversal, the payment is removed from the source account and moved to the target account, resulting in a complete reversal of the payment in the source account so that the payment information can be transferred to the destination account as a recycled payment. If the payment being recycled had been posted in a customer account, any bills and items that were closed due to the payment are reopened.
Note:To reverse a batch of payments from the BRM system, use Payment Tool. For more information, see "How BRM Reverses Payments".
Indirect reversals are assigned a G/L ID of 113, placing the payment amount in a special G/L bucket so that you can keep a separate record of these reversals. For more information on G/L IDs and reversals, see "Working with Suspense Reason Codes and Action Owner Codes".
If a suspended payment cannot be fixed but you want to track revenue for these payments and generate reports on how much unallocatable revenue you have, you can remove them from suspense as unallocatable. When you do this, BRM reverses the payment in the payment suspense account and assigns it to a special G/L ID bucket. These reversals are rare in BRM. Even though they are part of suspense, they occur outside of the recycling process.
For more information about removing payments as unallocatable, see "About Removing Unallocatable Payments from Suspense".
When payments are received in BRM, they are posted as successful or failed by default. Failed payments are those that have been dishonored or rejected by the bank for financial reasons. For example, payments can fail due to expired credit cards, incorrect account details, and insufficient funds. You can charge customers a fee for sending payments that fail.
For more information, see "Configuring Payment Fees".
You can provide payment incentives for customers who pay their bills early and in full. Incentives can include currency resources such as monetary credit (for example, a 5% reduction in the monthly bill amount) or non-currency resources (for example, 20 free minutes).
For more information, see "Configuring Payment Incentives".
When a credit card payment completes successfully, BRM returns a confirmation number that the customer can use later to identify the payment. BRM uses the payment item number as the confirmation number.
The PCM_OP_PYMT_COLLECT opcode returns the confirmation number in the PIN_FLD_ITEM_NO output flist field of the PIN_FLD_RESULTS array.
The BRM top-up features enable your customers to top up: add currency or non-currency resources to: balances in their own accounts or in other customer accounts. For example, a customer can top up her account balance with a $50 payment from her credit card, or she can top up her teenage son's account with a $50 payment from her account.
BRM supports two types of top-ups:
For information, see "About Topping Up Accounts".
Payment Suspense Manager is an optional payment feature that lets you more effectively handle the following payment scenarios:
Payments that fail the BRM validation process.
A payment may fail validation because it contains a missing or incorrect account number and bill number or because the payment attributes do not comply with your custom BRM validation rules. If Payment Suspense Manager is enabled in your BRM system, such payments are saved to a payment suspense account so that your payment processing can continue without having to fix the payments, allocate them manually, or save them to an exception batch.
Payments that were posted incorrectly to customer accounts.
If a payment was posted incorrectly, you can suspend it and then repost it to the correct account: you do not need to use Payment Tool or a custom CRM application to reverse the payment from the BRM system and then resubmit it in a new payment batch.
Payments that pay the bills for multiple accounts.
You can subdivide a suspended payment into a list of distributed payments and apply each payment to an individual customer account.
Account-level payments allocated to accounts with multiple bill units.
You can allocate an account-level payment to multiple bill units of an account. See "Allocating Account-Level Payments to Multiple Bill Units".
For more information about Payment Suspense Manager, see "Configuring Payment Suspense Manager".
By default, BRM requires acknowledgment from a bank or payment processor before BRM-initiated payments are posted. In some cases, such as nontransactional payments, the response from the bank or payment processor does not occur immediately with the request for funds.
To avoid the possible delay in posting payments, you can configure a new payment Data Manager (DM) to post payments immediately: before the funds are confirmed by the bank or payment processor. The DM requires an input flist of payments from BRM and must return the results to BRM in the output flist.
If the payment processor later sends a failure notification (for example, due to insufficient funds or an expired credit card), BRM reverses the initially successful payments and posts the failed payments.
Important:Only credit card and debit card payment methods can be posted before they are confirmed.
For information on reversing failed unconfirmed payments, see "Handling Failed Unconfirmed Payments".
A write-off is an accounts receivable transaction that removes an uncollectable balance from a customer's account so it is not considered as an asset for accounting purposes. If a CSR writes off a balance in an account, and later a payment for that account is received, you can reverse the write-off so that the payment can be allocated. You can perform the write-off reversal manually by calling the reversal opcodes, or you can configure BRM to automatically reverse the write-off during the payment collection process.
For more information about write-offs and write-off reversals, see ”Configuring Write-offs and Write-off Reversals” in BRM Managing Accounts Receivable.
You use payment processors to collect payments. The BRM system supports the following payment processors and middleware.
An automated clearing house (ACH) is a secure system that connects banks with financial institutions and enables the electronic transfer of funds to and from checking and savings accounts. For example, you use an ACH to handle check payments and direct debit payments.
When using an ACH, it may take a couple of days before the money is transferred because the ACH waits until it has received confirmation that the transaction was valid.
ACHs do not handle credit card or debit card transactions.
BRM supports the Paymentech credit card and debit card processor.
For information on using the Paymentech processing service with BRM, see "Configuring BRM-Initiated Payment Processing".
A payment gateway is any third-party payment transaction application that is integrated with BRM. Payment gateways are designed by software development companies for enterprise merchants who already have a BRM billing system in place. A payment gateway provides a way for merchants to receive and process external payment data seamlessly with BRM. A payment gateway receives payment files from multiple sources (such as banks, credit card processors, and automated clearing houses), preprocesses them, formats the files for BRM, and calls BRM opcodes to record the payments in the database.
Before you can load payments into BRM, you must configure your payment gateway with the same payment information you defined in the BRM database.
The main payment collection opcode is PCM_OP_PYMT_COLLECT. This opcode communicates with Payment Tool or a payment processor to perform payment collections, refunds, and reversals. It processes payments according to the payment processing type: BRM-initiated, or externally initiated.
By default, BRM allocates payments automatically. You can prevent allocation by using the PIN_BILLFLG_DEFER_ALLOCATION flag (0x1000000) in the PCM_OP_PYMT_COLLECT input flist PIN_FLD_CHARGES array.
For BRM-initiated payment processing, the normal flow of PCM_OP_PYMT_COLLECT is as follows:
Creates a batch checkpoint.
Calls the PCM_OP_PYMT_POL_PRE_COLLECT policy opcode, to perform policy checks before the charge, payment, or refund occurs after allocating the PIN_FLD_CHARGE array elements to open items. See ”Setting the Minimum Amount to Charge” in BRM Configuring and Running Billing.
Calls the PCM_OP_PYMT_SELECT_ITEMS opcode, to identify the items to which the payments are applied. See "Selecting the Items to Which Payments Are Applied".
Calls the PCM_OP_PYMT_CHARGE opcode, to perform a BRM-initiated payment transaction. This opcode checks the /config/payment object to determine which opcode to call to retrieve the payment information from the Payment DM and to create the charge: PCM_OP_PYMT_CHARGE_CC or PCM_OP_PYMT_CHARGE_DD.
For SEPA payments, creates the SEPA Direct Debit payment requests (/sepa/dd).
Calls the PCM_OP_BLL_RCV_PAYMENT opcode. This opcode:
Calls the PCM_OP_ACT_USAGE opcode to update the /event/billing/payment/payment type object.
Calls the PCM_OP_BILL_ITEM_TRANSFER opcode to allocate each payment to open items for each bill unit (/billinfo object) specified for the account.
Calls the PCM_OP_PYMT_APPLY_FEE opcode, to apply payment fees. If a payment fee is applied, the POID of the payment fee event is added to the output flist for PCM_OP_PYMT_APPLY_FEE.
Calls the PCM_OP_PYMT_POL_COLLECT policy opcode, to process the result of a credit card transaction for a specified account bill unit. This opcode sends the charge result to the policy opcode which specifies both the result to be returned to the caller and the actions to be performed on the account's bill unit.
For BRM-initiated payments, the PCM_OP_PYMT_POL_COLLECT policy opcode calls the PCM_OP_CUST_SET_STATUS opcode if the operation requires a status change.
By using checkpoints, finalizes the batch.
For externally initiated payment processing, the normal flow of PCM_OP_PYMT_COLLECT is as follows:
Calls the PCM_OP_PYMT_VALIDATE_PAYMENT opcode, to determine the status of the payment records. See "About Validating Payments".
Calls the PCM_OP_PYMT_POL_PRE_COLLECT policy opcode, to perform policy checks before the charge, payment, or refund occurs after allocating the PIN_FLD_CHARGE array elements to open items. See ”Setting the Minimum Amount to Charge” in BRM Configuring and Running Billing.
Calls the PCM_OP_PYMT_SELECT_ITEMS opcode to identify the items to which the payments in the batch are applied. See "Selecting the Items to Which Payments Are Applied".
If necessary, this opcode then calls the PCM_OP_PYMT_POL_OVER_PAYMENT policy opcode and the PCM_OP_PYMT_POL_UNDER_PAYMENT policy opcode, to allocate overpayment and underpayment of funds, respectively.
Calls the following standard opcodes:
Calls PCM_OP_BLL_RCV_PAYMENT to create the /event/billing/payment/pay_type object.
If the payment status is marked as a failed unconfirmed payment, the PCM_OP_BILL_REVERSE_PAYMENT opcode reverses the unconfirmed successful payments that have a value of PIN_PYMT_FAILED in the PIN_FLD_STATUS field. The PIN_FLD_AMOUNT value in the input flist CHARGES array is set to the value of PIN_FLD_AMOUNT_ORIGINAL_PAYMENT, and the value of PIN_FLD_AMOUNT is set to 0.
Calls PCM_OP_PYMT_ITEM_TRANSFER to allocate the payment to open items.
Calls PCM_OP_PYMT_APPLY_FEE to record failed payments and apply payment fees. If a payment fee is applied, the POID of the payment fee event is added to the output flist for the PCM_OP_PYMT_APPLY_FEE opcode.
If the cease_billing action was received, calls PCM_OP_CUST_SET_BILLINFO to change the status of the bill unit.
If mandated by the policy FM, calls the PCM_OP_PYMT_POL_COLLECT policy opcode to perform the following actions listed in Table 1-2, which are based on the payment result:
Apply the payment to reduce the pending receivable of the bill unit by the amount specified.
Change the bill unit's status to that given, using the reasons indicated by the flags.
Apply a refund by crediting the bill unit with the refund amount specified.
Discontinue billing an account after a determined period of inactivity by marking the given bill unit as no longer billed.
Creates the final batch.
The PCM_OP_PYMT_COLLECT opcode calls the PCM_OP_PYMT_SELECT_ITEMS opcode to identify the items to which the payment is applied. PCM_OP_PYMT_SELECT_ITEMS is also called by Payment Tool.
PCM_OP_PYMT_SELECT_ITEMS does the following:
Selects open items based on the input fields and the accounting type of the account. For more information, see "How Items Are Selected for Payments".
If the amount passed in on the input flist is not in the primary account currency, PCM_OP_PYMT_SELECT_ITEMS attempts to convert it to the primary account currency.
One of the following actions is taken:
If called by PCM_OP_PYMT_COLLECT, PCM_OP_PYMT_SELECT_ITEMS returns the PIN_FLD_AMOUNT and the list of selected items.
If called by Payment Tool, PCM_OP_PYMT_SELECT_ITEMS compares the sum of the amount due from all the selected items to the PIN_FLD_AMOUNT value to see if the payment is an exact payment, an overpayment, or an underpayment. If it is an overpayment, it calls the PCM_OP_PYMT_POL_OVER_PAYMENT policy opcode. If it is an underpayment, it calls the PCM_OP_PYMT_POL_UNDER_PAYMENT policy opcode.
Returns the list of selected items.
Items are selected by PCM_OP_PYMT_SELECT_ITEMS based on the fields in the input flist.
The contents of the PIN_FLD_BILLS array is examined. For BRM-initiated payments, the contents of the PIN_FLD_BILLINFO array is also examined.
The PIN_FLD_BILLS array indicates which /bill storable object PCM_OP_PYMT_SELECT_ITEMS is collecting or paying off. If one or more bills are included, all items belonging to those bills are selected. If none are specified, the default /billinfo storable object is used to apply the payment.
The PIN_FLD_BILLINFO array specifies the /billinfo object to select items for. If none are specified, the items are retrieved based on the bills in the PIN_FLD_BILLS array. If neither a bill unit POID or bill is included, the items are selected from the account's default /billinfo object. This is the /billinfo object that contains the default balance group for the account.
Note:For account-level payments to accounts with multiple bill units, there are multiple PIN_FLD_BILLINFO arrays corresponding to each bill unit that contain the bill unit-level distribution.
If the accounting type is PIN_ACTG_TYPE_OPEN_ITEMS or if the accounting type is PIN_FLD_ACTG_TYPE_BALANCE_FORWARD and the PIN_FLD_BILLS array is passed in, there are two options for items to be eligible for the selection criteria:
If the PIN_FLD_INCLUDE_CHILDREN field is not specified or is specified and set to 1, items that belong to the A/R bill unit (including nonpaying child bill items) are selected.
If the PIN_FLD_INCLUDE_CHILDREN field is specified and set to 0, items that belong only to the specified bill are selected.
Note:PIN_FLD_INCLUDE_CHILDREN applies only when the PIN_FLD_BILLS array is specified.
If PIN_FLD_ACTG_TYPE is PIN_FLD_ACTG_TYPE_BALANCE_FORWARD and PIN_FLD_BILLS is not specified, PCM_OP_PYMT_SELECT_ITEMS selects all the open items for this bill unit and sums up the amount due from all the open items selected.
The PIN_FLD_AMOUNT field determines whether the overpayment or underpayment policy opcodes are called. If PIN_FLD_AMOUNT is not specified, the payment amount is based on the charges of the bill unit's open items.
If the PIN_FLD_AMOUNT field is passed:
The payment is not allocated to other open items and the deferred allocation flag is set.
The payment must be allocated manually.
If the PIN_FLD_BILLINFO array contains bill unit level payment distribution, the PCM_OP_PYMT_SELECT_ITEMS opcode finds out the item-level distribution for the selected bill units.
By default, BRM-initiated payments, such as payments made by credit card or direct debit, are collected on the date that bills are finalized. Alternatively, you can configure BRM to collect a BRM-initiated payment on the date a bill is due or on a specified number of days before the bill is due. See "Configuring Payment Collection Dates for Automatic Payments".
To support configurable payment collection dates, the PCM_OP_BILL_POL_CALC_PYMT_DUE_T policy opcode calculates a bill's payment collection date after calculating its due date.
Note:Although configurable payment collection dates are used only for BRM-initiated payments, they are calculated and stored for bills associated with all payment methods.
To calculate payment collection dates, the PCM_OP_BILL_POL_CALC_PYMT_DUE_T policy opcode performs these tasks:
Finds the /payinfo object that is linked to the /billinfo object with which the bill is associated.
Reads the value of the PIN_FLD_PAYMENT_OFFSET field in the /payinfo object.
Does one of the following:
If the value is -1, sets the payment collection date to the date the bill is finalized.
If the value is 0, sets the payment collection date to the date the bill is due.
If the value is any positive integer (x), sets the payment collection date to x days before the bill is due.
Note:If x makes the payment collection date earlier than the date the bill is finalized, the PCM_OP_BILL_POL_CALC_PYMT_DUE_T policy opcode uses the finalization date instead.
Stores the payment collection date in the PIN_FLD_COLLECTION_DATE field of the /billinfo object.
Note:By default, the "pin_collect" utility collects BRM-initiated payments for all bills associated with /billinfo objects whose PIN_FLD_COLLECTION_DATE is the day the utility is run or the day before the utility is run.
When payments are received in BRM, they are processed by the PCM_OP_PYMT_COLLECT opcode. To record the payments, PCM_OP_PYMT_COLLECT calls the PCM_OP_BILL_RCV_PAYMENT opcode. This opcode records the payment items and events and updates account balances by calling the PCM_OP_BILL_ITEM_TRANSFER opcode. If there is excess money after paying the item list off, PCM_OP_BILL_RCV_PAYMENT adds that amount to the sub-balance as a credit. If there is no sub-balance, one is created.
When posting a suspended payment, PCM_OP_BILL_RCV_PAYMENT stores the reason code, action owner code, and original reason code for the payment in the payment event's PIN_FLD_EVENT_MISC_DETAILS array. The reason codes are passed in from the PCM_OP_PYMT_COLLECT input flist's PYMT_REASONS array.
The PIN_FLD_EVENT_MISC_DETAILS array uses specific element IDs as follows:
Array Element 0: Stores the reason code used to determine the G/L ID of the payment being moved to the payment suspense account.
Array Element 1: Stores the action owner code for suspended or failed payments.
Array Element 2: Stores the original reason code for failed payments that BRM suspended. This ensures that the reason initially associated with the financial failure is not lost if BRM places the payment in suspense. Element 2 is used only for Payment Suspense Manager; if payment suspense is not enabled, only element 0 will be present.
When the failed payment leaves suspense and PCM_OP_BILL_RCV_PAYMENT creates new payment objects to record the corrected payment, Elements 0 and 1 are no longer needed. The object does not contain the elements 0 and 1 recorded for suspense, and Element 2 becomes the new Element 0.
When processing multiple resource voucher top-ups that include non-currency resources, PCM_OP_BILL_RCV_PAYMENT retrieves the non-currency balance impacts from the PIN_FLD_TOPUP_RESOURCE_INFO substruct in the PCM_OP_PYMT_COLLECT input flist and passes them to the PCM_OP_ACT_USAGE opcode so that they are recorded in the corresponding /event/billing/payment/voucher object. See "How BRM Performs Top-Ups".
PCM_OP_BILL_RCV_PAYMENT uses the PIN_FLD_SESSION_OBJ field in the input flist to reference the type of session in which the event occurred: either /event/billing/batch/refund or /event/billing/batch/payment, depending on the batch.
Payments are directly reversed from BRM by using Payment Tool. To process a payment reversal batch, the PCM_OP_BILL_REVERSE opcode performs the following operations:
Note:PCM_OP_BILL_REVERSE is a wrapper for the PCM_OP_BILL_REVERSE_PAYMENT opcode, and it is the recommended opcode to use. Custom client applications should not directly call PCM_OP_BILL_REVERSE_PAYMENT.
Opens a transaction and checks the appropriate /config/business_params objects to find out if Payment Suspense Manager is enabled.
Validates that the PIN_FLD_FLAGS field is not present in the input flist or, if the flag is present, that it is not set to PIN_REVERSE_FLAG_REVERSE_AS_UNALLOCATED (1). If the flag is set, the operation fails because payments that were removed already from BRM as unallocatable cannot also be reversed.
Checks the PIN_FLD_STATUS field of each reversal associated with the payment being reversed.
Calls the PCM_OP_PYMT_RECYCLED_PAYMENTS_SEARCH opcode, which performs the following operations:
Validates that the payment does not have a SUB_TRANS_ID value, and is therefore the original payment. If the payment has a SUB_TRANS_ID value, the operation will fail.
Finds all distributed payment events that have the same SUB_TRANS_ID value as this payment's TRANS_ID value, and have not been reversed already due to the recycling process.
Assigns a reversal TRANS_ID value to each payment returned by the search and populates the reversal flist with each TRANS_ID value.
Checks the PIN_FLD_STATUS field of each /event/billing/reversal object associated with the payment being reversed to ensure that no part of the payment has been removed from suspense as unallocatable.
Calls PCM_OP_BILL_REVERSE_PAYMENT to reverse the list of payments.
If the payment was originally made to a customer account, the list includes any recycled payment generated if the payment was moved into the suspense account after it posted to the customer account.
If the payment was originally made to the suspense account, the list contains all payments generated from the original payment, including distributed payments and any payment remaining in the suspense account.
In both cases, the sum of all the payments reversed in this operation should equal the amount of the original payment.
If the reversal is called for a SEPA payment transaction, the opcode creates the /sepa/dd/reversal object only if the original payment request is in the REQUESTED status. If the charge event, /event/billing/charge/sepa, does not exist, it records the reversal only (the /sepa/dd/reversal object is not created assuming that the payment request has not been sent to the bank).
PCM_OP_BILL_REVERSE_PAYMENT verifies that the reversal operation was successful for all of the payments. It uses the PIN_FLD_SESSION_OBJ field in the input flist to reference the reversal batch event.
It also checks the /config/business_params object to determine whether payment incentives are enabled. If so, PCM_OP_BILL_REVERSE_PAYMENT calls the PCM_OP_PYMT_REVERSE_INCENTIVE opcode, which removes the payment incentive trigger in the /billinfo object, thus eliminating the payment incentive.
Populates the payment batch with the sum of the reversal flist.
Returns the reversal information for all the payments in the PIN_FLD_MULTI_RESULTS array.
The PIN_FLD_RESULTS field of the output flist indicates whether the reversal was successful. Direct reversal is not allowed if either of the following conditions is true:
The payment has a SUB_TRANS_ID value and, therefore, is not an original payment.
PCM_OP_BILL_REVERSE is called from the PCM_OP_PYMT_RECYCLE_PAYMENT opcode. In this case, a reversal takes place, but it is not a direct reversal. See "How Payments Are Reversed".
To customize how written off payments are reversed, use the PCM_OP_BILL_POL_REVERSE_PAYMENT policy opcode. See ”Customizing Reversal of Payments Allocated to Written-Off Accounts” in BRM Managing Accounts Receivable.
If you have Payment Suspense Manager enabled, you can reverse only original payments. For information on payment reversals that occur during payment suspense processing, see "How Payments Are Reversed".
For information on processing a payment reversal batch by using Payment Tool, see "About Reversing Payments".
Refunds are accounts receivable actions. For more information, see "Managing Refunds with Your Custom Application".
The PCM_OP_BILL_ITEM_REFUND opcode is used to create a refund item for a /bill or /billinfo object. After the refund items are created, BRM uses the PCM_OP_PYMT_COLLECT opcode to refund the payment amount to the account. For BRM-initiated payments, use the "pin_collect" utility to refund payments based on the payment method. For externally initiated payments, use Customer Center to perform the refund operation.
The following opcodes are used for writing off payments:
Write-offs and write-off reversals are accounts receivable actions. For more information, see ”Writing off Debts and Reversing Write-Offs with Your Custom Application” in BRM Managing Accounts Receivable.