9 Configuring Payment Suspense Manager

This chapter provides an overview of Payment Suspense Manager and how your Oracle Communications Billing and Revenue Management (BRM) system handles suspended payments. It includes:

A summary of the Payment Suspense Manager functionality.

An overview of how BRM determines the status of a payment and how it suspends payments.

Information on how to set up BRM for Payment Suspense Manager.

Note:

Payment Suspense Manager is available only for externally initiated payments (for example, check payments that are sent from a bank). It does not apply to BRM-initiated payments because the problems that trigger payment suspense cannot occur in BRM-initiated payments.

For background information on payments and payment processing, see "About Payments". For information on the client applications that support Payment Suspense Manager, see the following:

Payment Tool Help

Payment Center Help

About Payment Suspense Manager

Payment Suspense Manager lets you more effectively handle payments that cannot be posted immediately to customer accounts due to insufficient information, account closure, or other criteria, and payments that were posted incorrectly to customer accounts. It is a two-way process between the payment suspense account and a customer account: you can apply suspended payments to customer accounts or suspend payments that have been posted in customer accounts.

With Payment Suspense Manager, BRM automatically suspends payments that exhibit certain problems instead of failing them or wrongly allocating them. It removes the payment from the payment processing stream, postponing it for later investigation. This enables the payment posting process to complete without requiring immediate intervention to fix the errors.

Payment Suspense Manager also enables you to perform the following payment processing tasks:

Manually suspend payments during payment processing. If you find a successful payment in a payment batch that you suspect contains incorrect data or requires special handling, you can manually suspend that payment so that it can be carefully examined before it is posted to the account. Such payments can be processed later, so you can avoid performing the allocations during normal payment collection.

Manually suspend payments after they have been posted to customer accounts. If a payment was posted incorrectly, you can suspend it and then repost it to the correct account: you no longer need to use Payment Tool or a custom CRM application to reverse a posted payment from the BRM database and then resubmit it as a new payment.

Partially allocate a suspended payment so that an amount remains in the payment suspense account. If all or part of a suspended payment cannot be allocated, you can remove the suspended payment or unallocated amount from the BRM system so that you can recognize the unallocated revenue. This enables you to track the unrealized revenue in your general ledger (G/L) system.

Create financial reports on revenue that you have realized but that remains unallocated. Suspended payments are assigned to their own G/L segment, so you can develop reporting facilities that isolate suspended payments and quantify that type of revenue.

Payments can remain suspended indefinitely. This gives you the flexibility of fixing and applying them to the correct accounts at any time. You can move payments back and forth between customer accounts and the payment suspense account any number of times.

Suspended Payment Processing Overview

The payment suspense process begins when you collect payments from a financial institution: whether you use payment clerks to manually post payments from batch files or use a third-party payment gateway to automatically post payments. It is a three-step process:

Validate the payment.

Determines whether there is enough information for BRM to post the payment successfully or if the payment should be suspended.

Submit the suspended payment to the payment suspense account.

Moves a suspended payment into the BRM payment suspense account, a special account you set up to store all suspended payments. You can also suspend payments that have already been validated and posted to customer accounts.

Correct the suspended payment.

Corrects the problem and moves the payment from the payment suspense account to the accounts for which the payment should be made.

You use two client applications to work with suspended payments: Payment Tool and Payment Center. As a general rule, you use Payment Tool to validate incoming payments, manually suspend payments before they get posted to customer accounts, and submit payments to the BRM database. You use Payment Center to manually suspend payments that were incorrectly posted to customer accounts and to correct suspended payments.

How you work with these applications depends on whether you receive the payment as a batch file from the bank or use a payment gateway that has been directly integrated with BRM payment services.

About Setting Up Payment Suspense Manager

Payment Suspense Manager is an optional BRM feature. By default, this feature is disabled. To enable payment suspense, you modify the appropriate /config/business_params storable object. For more information, see "Enabling Payment Suspense in BRM".

After you enable Payment Suspense Manager, you must perform the following tasks:

Set up a BRM payment suspense account.

The payment suspense account is an ownerless account that stores each suspended payment along with details such as credit card number, payment channel, payment method, and so forth.

If, during validation, BRM determines that a payment should be suspended, it performs one of these actions:

If the payment was submitted through a third-party payment gateway, it automatically moves the payment to the payment suspense account.

If you are working with a payment in Payment Tool, it moves the payment to the payment suspense account when your payment clerk submits the payment batch to the BRM database.

If you are working with Payment Center, it moves the payment to the payment suspense account when your payment clerk performs an undo allocation operation on a posted payment.

After a suspended payment is corrected, BRM moves the payment from the payment suspense account to the correct customer account.

The payment suspense account is assigned to a unique G/L segment, and the payments in the payment suspense account will only belong to this G/L segment: not the G/L segment to which the customer accounts belong. Thus, while the items in the payment suspense account are excluded from normal financial reporting, billing, and collection, you can obtain information on the associated revenue by generating financial reports for the G/L segment to which the payment suspense account belongs.

The reason codes and action owner codes provide information on why a payment is suspended and who is assigned to correct the problem. To help payment clerks understand the nature of a suspended payment, BRM displays descriptions associated with reason codes and action owner codes in Payment Tool and Payment Center. In addition, BRM uses reason codes and action owner codes to populate selection lists in these tools.

Note:

You can also create additional search fields in Payment Center and additional batch types in Payment Tool. For information on modifying payment options in these tools, see BRM Developer's Guide.

BRM validates a payment by determining whether the payment has certain mandatory information such as the correct account number and bill number. You can customize BRM such that it considers extra validation criteria like the customer segment. You can also define the conditions under which you submit a suspended payment to the payment suspense account (for example, a minimum payment amount).

About the Payment Suspension Process

Payment suspension begins when you collect payments from a financial institution: whether you use payment clerks to manually post payments from batch files or you use a third-party payment gateway to automatically post payments. When payments are received, BRM validates payments based on the following criteria to determine whether they should be suspended rather than posted immediately to customer accounts:

The account number and bill number are missing or incorrect.

The account number and bill number are correct, but the bill belongs to a different account.

The account is closed.

The payment attributes (for example, the customer segment or payment amount) do not comply with your custom BRM validation rules.

The payment processing phase involves three steps: validation, suspension, and correction. These steps are sequential and rely on the completion of the prior step.

Validation: BRM determines whether a payment meets the validation criteria and assigns a status of successful or ”to be suspended.” BRM takes the following actions:

If the payment is successful, BRM posts the payment to the account.

If the payment does not meet the validation criteria but has enough information to qualify for suspense, BRM marks it as ”to be suspended” and forwards it to the opcodes responsible for suspending the payment.

BRM can suspend both successful and financially failed payments. For example, a payment batch includes two check payments, each with an incorrect account number. The payment information indicates that one check has cleared and the other bounced.

Coming into BRM, the first payment would be considered successful and the second, failed. When BRM validates the payments, both would be marked for suspense because, regardless of the financial success or failure of the payment, neither payment can be posted to the correct account.

If the payment does not meet the validation criteria and also does not qualify for suspense, BRM informs you that the payment cannot be posted. You must create an exception batch to handle payments that fall into this category.

Payment validation is initiated automatically through the payment gateway or manually by a payment clerk.

Suspension: BRM moves the payment to the payment suspense account and creates the associated events and items to store information on the suspended payment.

There are two distinct situations in which payment suspense can occur: during payment processing, when a payment batch is submitted to the BRM database, and during account maintenance, after payments have been saved to the BRM database.

During payment processing, payment suspense is initiated automatically through a third-party payment gateway or manually by using Payment Tool. It is initiated in Payment Tool when you submit a payment batch that includes payments marked for suspense. Such payments can be successful payments that you manually mark for suspense because you suspect they have a problem or you know they require manual allocation. For details on suspending unposted payments, see "About Processing Suspended Payments in a Payment Batch".

During account maintenance, payment suspense is initiated manually by using Payment Center. Payment suspense is initiated when you undo the allocation of a payment from a customer account. For details on suspending posted payments, see "About Processing Suspended Payments in the BRM Database".

Correction: To correct a suspended payment, you use Payment Center to assign it to a correct account number or bill number and apply it to the customer account. You can also create a distribution list for a suspended payment, which enables you to apply the payment to multiple accounts.

After payment analysts correct suspended payments and assign them to one or more accounts, the payments must be validated again. If the payment validation is successful, BRM posts the payments to the correct accounts. If the suspended payment is allocated completely (an amount does not remain in suspense), BRM reverses the suspended payment, removing it from the payment suspense account. While performing this operation, BRM creates the required objects and events.

Note:

Payment correction is always initiated by a payment clerk through Payment Center; this step is never automatic. If, during revalidation, the payment still meets the suspense criteria, BRM again assigns a status of suspended and the payment is resubmitted to suspense.

About Payment Validation

Before payments can be processed and posted by BRM, they must pass validation. BRM uses the PIN_FLD_STATUS value to verify that the PCM_OP_PYMT_VALIDATE_PAYMENT opcode and the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode successfully performed the payment validation and to determine how to handle the payment. When Payment Suspense Manager is enabled, BRM updates the PIN_FLD_STATUS value as follows:

Successful payments that pass the validation process: Retains the original PIN_FLD_STATUS of PIN_PYMT_SUCCESS. These payments are loaded into BRM and allocated to the correct account according to the default BRM payment processing behavior.

Failed payments that pass the validation process: Retains the original PIN_FLD_STATUS of PIN_PYMT_FAILED. These payments are loaded into BRM and posted to the correct account using the default BRM payment processing behavior.

Payments that fail the validation process: Updates PIN_FLD_STATUS to PIN_PYMT_SUSPENSE, PIN_PYMT_FAILED_SUSPENSE (for failed payments that must be suspended), or any other status in the suspense range. These payments require further investigation, which you can perform immediately or defer by submitting the payments to BRM. Upon submission, BRM passes all payments marked for suspense to the PCM_OP_PYMT_POL_SUSPEND_PAYMENT policy opcode, which is responsible for actually directing them to suspense.

About Processing Suspended Payments in a Payment Batch

If you are using Payment Tool and a payment has been marked for suspense, you can:

Investigate and correct the problem before submitting the payment batch to the BRM database. If you do so, the payment is not actually suspended. Instead, it is revalidated and posted to the correct account.

Defer the investigation until later by submitting the payment to the database by using Payment Tool. In this case, the payment is suspended, and BRM moves it to the payment suspense account.

Note:

If you use a payment gateway to process your payments, all payments marked for suspense are automatically submitted to suspense.

Whether you use Payment Tool or a payment gateway, BRM calls the PCM_OP_PYMT_POL_SUSPEND_PAYMENT policy opcode to process any payment submitted with the status PIN_PYMT_SUSPENSE. The opcode places a payment in suspense by enriching the flist so that the payment can be directed to the payment suspense account. It then calls the opcodes that post the payment to this account and create objects to record the suspended payment. The event object contains all information about the payment and its suspense, including the account number, bill number, transaction ID, and any associated reason codes or action owner codes. This information can be used to investigate why the payment failed the validation process and who is responsible for resolving the problem.

About Processing Suspended Payments in the BRM Database

To suspend payments that are posted in customer accounts, you use Payment Center to perform an Undo Allocation operation and to assign a reason for suspense. The PCM_OP_PYMT_RECYCLE_PAYMENT opcode validates that the source account is the account to which the payment was posted and that the destination account is the payment suspense account. If both requirements are true, the payment is recycled to suspense. See "About Recycling Payments to Suspense".

Payment Center sets the payment status to PIN_PYMT_RETURNED_SUSPENSE, indicating that allocation has been undone for this payment at least once. BRM uses this flag to identify the payment when you search for a suspended payment in Payment Center. See "About Payment Status".

When you suspend a payment that was posted to a customer account, the entire payment is reversed from the customer account. You cannot suspend a partial payment amount. For example, a payment is allocated to two correct bills and one incorrect bill. The entire payment allocation must be undone to correct the error, not just the amount allocated to the incorrect bill. To undo the allocation, the payment is suspended. Then, it can be reallocated to the correct account or bills.

Note:

If you do not want to undo the allocation and reallocate the suspended payment to the same account, you can directly transfer the correct amount to the correct item, bill, or account by performing an adjustment. See "Transferring Amounts between Items" in BRM Managing Accounts Receivable.

If you are resuspending a payment that was distributed to multiple accounts, you can resuspend any number of the distributed payments simultaneously.

You use Payment Center to suspend payments that were posted to customer accounts. For more information, see Payment Center Help.

You use Customer Center to perform adjustments, if necessary. For more information, see Customer Center Help.

About Payment Correction

If a payment is suspended, you must correct the problem. If you are working with a payment that was already submitted to the BRM database, you must also resubmit the payment after correcting it.

You investigate and correct suspended payments by using Payment Center. After you update a payment with the corrected information, the action you take depends on how you opened the payment you are working on: from a current payment batch by using Payment Tool or from the BRM database by using Payment Center. If the payment is in a current payment batch in Payment Tool, you must return to Payment Tool to revalidate it and submit the batch.

However, if the payment was already in the BRM database, Payment Center uses PCM_OP_PYMT_RECYCLE_PAYMENT to validate and allocate the corrected payment to the proper account. For valid payments, BRM searches for the original payment details and moves the corrected payment from the payment suspense account to the correct account by:

Posting the payment to the correct account and allocating the payment to the correct bill.

Reversing the original suspended payment stored in the payment suspense account.

If the corrected payment does not pass revalidation, BRM again suspends the payment and assigns a new reason code to describe the problem.

In some cases, you may determine that a suspended payment cannot be fixed; for example, the payment has stayed in suspense after repeated correction attempts. Payments of this nature represent unrealized revenue. To track revenue and report for these payment, you can remove them from suspense as unallocatable. When you do this, BRM uses the PCM_OP_BILL_REVERSE_PAYMENT opcode to reverse the payment in the payment suspense account and create the associated objects in the database. BRM assigns a G/L ID of 112 for the reversal, placing the payment amount in a special G/L bucket so that you can obtain information about how much unallocatable revenue you have.

About Distributing One Payment to Multiple Accounts

You can divide a suspended payment into any number of distributed payments and apply each one to a different customer account. Distributed payments are subpayments that together comprise one larger suspended payment.

In the example shown in Figure 9-2, a $3,000 suspended payment is portioned into three distributed payments of $1000, $450, and $650, each of which is posted to a different customer account:

Each distributed payment can be allocated to specific bills, items, or both, in an account, or left unallocated at the account level. When distributing a suspended payment to a group of accounts, you can mix allocation levels so that some distributed payments are allocated to accounts and some to bills. For underpayments, you can also allocate the payment to specific items in an account.

For example, in the scenario shown in Figure 9-3, Suspended Payment 1 is distributed from the suspense account to three accounts. As indicated by the shaded boxes below, the distributed payment is left unallocated in Account A and allocated to specific bills in Account B. The underpayment to Account C is allocated to specific items.

Figure 9-3 Allocation of Distributed Payments from a Suspended Payment

You can specify only one payment allocation level for each target account in the distribution list. For example, a payment analyst cannot choose to apply a payment to Account A and then try to allocate it to specific bills in Account A. Likewise, if a payment analyst chooses bill-level allocation for Account B, he or she cannot later apply that payment at the account level for Account B.

You use Payment Center to process distributed payments. The procedure involves:

Opening a suspended payment that requires distribution.

Creating a payment distribution list and identifying the customer account, bills, or items to which each distributed payment belongs.

Submitting the payment distribution list to BRM.

If you discover that one or more distributed payments were allocated incorrectly, you can return them to suspense and redistribute them at any time.

About Allocating an Account-Level Payment to Multiple Bill Units

For accounts having multiple bill units, BRM distributes the account-level payment to multiple bill units of the account. Payment Suspense Manager is used to suspend the original payment and recycle it to distribute to multiple bill units. The distribution process is similar to distributing a single suspense payment to multiple accounts. Each distributed payment has the original payment's transaction ID as a subtransaction ID. For accounts with multiple bill units, BRM calls the PCM_OP_PYMT_COLLECT opcode to allocate the payment.

Understanding Payment Recycling

The payment suspension functionality involves payment recycling, which is the method by which BRM reuses payment information. BRM uses payment recycling when distributing suspended payments to customer accounts, returning a payment to suspense, and placing a posted payment into suspense.

Payment recycling is a transactional process consisting of two sequential operations:

Reversing a payment from a source account.

Applying a payment to a target account.

Payment recycling occurs each time you move a payment from a customer account to the payment suspense account or from the payment suspense account to a customer account. When a payment is recycled, the current payment is reversed, and all of the payment information, except for the original payment date, is transferred to the new recycled payment. For more information on payment reversal, see "How Payment Reversals Work with Suspense and Recycling".

BRM uses the PIN_FLD_STATUS field of a payment to validate payments before they are recycled and submitted to an account. The status code is returned by Payment Center and can be configured. For a complete list of default payment status codes and descriptions, see "About Payment Status".

Payments can be recycled any number of times; however, each recycled payment can be traced back to only one original payment. BRM uses the payment's transaction ID and subtransaction ID to track their origin and descendants. For more information, see "About Original Payments" and "How BRM Tracks Suspended Payments".

When performing reversals during recycling, the PCM_OP_BILL_REVERSE opcode must be called by PCM_OP_PYMT_RECYCLE_PAYMENT. This ensures that only payments with a SUB_TRANS_ID value of NULL can be reversed directly.

About Original Payments

An original payment is the first instance of a payment that is saved to BRM, either through Payment Tool or a payment processor. Original payments can be saved initially to the suspense account or to a customer account. The distinguishing characteristic of an original payment is that it has never been recycled.

Because an original payment is the first instance of a payment, it does not have a subtransaction ID, which is an ID used to trace a recycled payment back to its original payment.

An original payment can be the ancestor of one or more recycled payments, but a recycled payment can be traced back to only one original payment. Both suspended payments and those posted in customer accounts can be original payments.

About Payment Transfer Direction and Verification

When PCM_OP_PYMT_RECYCLE_PAYMENT receives a distribution list from Payment Center, it uses the information in the CHARGES array of the input flist to determine the direction of the payment transfer: from the payment suspense account to a customer account, or to the payment suspense account from a customer account. The CHARGES array contains two fields that determine the direction of the transfer:

PIN_FLD_EVENT_OBJ: This field identifies the payment event. The event, in turn, identifies the source account, the account that owns the payment. This is the account from which the opcode transfers payments.

PIN_FLD_ACCOUNT_OBJ: This field identifies the target account, the account to which the opcode transfers payments.

If a payment is being moved from suspense, the PIN_FLD_EVENT_OBJ field establishes the payment suspense account as the source account, and the PIN_FLD_ACCOUNT_OBJ field contains one or more POIDs of valid customer accounts. If a payment is being moved to suspense, the PIN_FLD_EVENT_OBJ field establishes a valid customer account as the source account, and the PIN_FLD_ACCOUNT_OBJ field contains the POID of the payment suspense account.

Before recycling a payment, BRM verifies that there are no conditions present that prevent the transfer. These conditions include:

The currency for the source account and all target accounts is different.

The source and target accounts are both customer accounts.

Multiple suspended payments are recycled in the same operation.

You attempt to partially suspend a payment originally posted to a customer account. You can only perform this action if you suspend the entire payment.

You attempt to distribute a failed payment from the suspense account into a customer account.

You attempt to return a distributed payment from a customer account to the suspense account, but the suspended payment is also a failed payment. This can happen when you distribute a suspended payment to customer accounts and, afterward, the payment fails for financial reasons (for example, the bank will not honor the check). In this case, you cannot return the distributed payment to suspense.

About Recycling Payments from Suspense

When you post a suspended payment to a customer account, the following operations occur if validation and transfer verification are successful:

The suspended payment is reversed (an /event/billing/reversal object is created).

The payment item for the suspended payment is closed.

A recycled payment is posted in the customer account. The payment status reflects that the payment was successfully recycled. See "About Payment Status".

Bills, bill items, or both in the account might be closed, depending on the payment allocation level.

A new suspended payment is created for any unallocated amount (partially allocated payments).

You do not have to fully allocate a suspended payment. If you partially allocate a suspended payment and an amount remains in suspense, you can apply the remaining amount to any account at any time.

About Recycling Payments to Suspense

When you suspend a payment that has been posted in a customer account, the following operations occur if validation is successful:

The posted payment is reversed (an /event/billing/reversal object is created).

Any accounts receivable items (/item/payment) that were previously closed by the payment are reopened.

A recycled payment is created in the payment suspense account. The payment status reflects that the payment was successfully recycled. See "About Payment Status".

A new billable item for the recycled suspended payment is created.

How Payment Reversals Work with Suspense and Recycling

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). Payments also can be reversed as part of the suspense process.

When a payment is reversed, two things happen:

Any bills or items previously closed by the payment are reopened.

The payment is deactivated in the BRM system.

There are three types of reversals in BRM. The first two, indirect reversal and reversal to remove an unallocatable suspended payment, are related to the suspense process. The third, direct reversal, is not.

Reversals that occur indirectly during the recycling process

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.

If a suspended payment cannot be fixed but you want to track revenue for these payments and get 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.

Reversals that you perform directly by using Payment Tool or a third-party application

Direct reversals occur when you use Payment Tool or a third-party application to reverse a payment that was recorded in the BRM database but never actually deposited. Direct reversals are the most frequent type of reversal in BRM, and they occur outside of the suspense and recycling processes.

Direct reversals reverse an active payment completely and reopen any bills and items so the payment can be made again. Unlike reversals that occur during recycling, direct reversals are not initiated by the creation of a new recycled payment.

How BRM Tracks Suspended Payments

All payments and payment reversals contain a transaction ID (TRANS_ID field), which is a unique identifier that enables you to track each payment and reversal in BRM:

For payments, the transaction ID identifies the payment transaction from the third-party payment processor. If a payment is submitted to BRM without a transaction ID, one is assigned to it.

For reversals, the transaction ID is generated by BRM.

In addition to having a transaction ID, payments and reversals have another ID that is used to track all actions performed on a specific payment: a subtransaction ID (SUB_TRANS_ID field) for payments, and a paytransaction ID (PAYMENT_TRANS_ID field) for reversals. These ID values are used to find all payments and reversals that occur due to the recycling of an original payment.

The SUB_TRANS_ID value of an original (never-recycled) payment is NULL.

The SUB_TRANS_ID value of a recycled payment is equal to the transaction ID of its original payment.

The PAYMENT_TRANS_ID value of a payment reversal is equal to the transaction ID of the payment it reversed.

In the example shown in Figure 9-4, a $3000 payment is suspended when it first arrives in BRM so that it can be posted to individual accounts within the corporation. The original payment is represented in white.

The payment analyst first partially distributes the original suspended payment to two accounts. The first distributed payment is for $1000 to Account A and the second is for $700 to Account B. The remaining $1300 is resuspended. The results of this operation are represented in Phase 1.

Later, the payment analyst realizes that the distributed payment made to Account B was erroneous and puts the $700 payment back into suspense, leaving $1000 in Account A and $2000 in the suspense account. The results of this operation are represented in Phase 2.

In this figure, all payments except the original payment are recycled payments. Notice that:

Both distributed payments have the same subtransaction IDs (s1). The SUB_TRANS_ID value is the same as the TRANS_ID value of the original payment.

All of the recycled payments have SUB_TRANS_ID values that match the original payment's TRANS_ID values.

Each reversal has a PAYMENT_TRANS_ID value that is equal to the TRANS_ID value of the payment it reversed.

When an original suspended payment is applied to a customer account, the following operations occur:

The suspended payment is reversed, and an /event/billing/reversal object is created. The reversal object's PAYMENT_TRANS_ID value is equal to the TRANS_ID value of the suspended payment.

A new payment (event/billing/payment/pay_type object) is applied to the customer account and contains the following information:

The original suspended payment's details, including a value for any amount remaining in suspense.

A SUB_TRANS_ID value that is equal to the suspended payment's TRANS_ID value.

If an amount remains in suspense, a new suspended payment is created for that amount; the original payment is not adjusted with a new amount. Instead, the new suspended payment receives a SUB_TRANS_ID value that is equal to the original payment's TRANS_ID value.

Likewise, when a suspended payment is partially allocated to one or more accounts, and then an allocated payment is resuspended, the current suspended payment that was partially allocated is reversed and a new suspended payment containing the new amount is created.

Note:

An original payment does not have to be a suspended payment. For example, if a payment was posted successfully to a customer account when it was received by BRM, it is an original payment. If it is later suspended and then reposted to customer accounts, both the suspended payment and the posted payment will have SUB_TRANS_ID values that match the TRANS_ID value of the original successful payment as shown in Figure 9-5:

How Direct Reversals and Refunds Relate to Suspense

BRM distinguishes between original payments, suspended payments, and recycled payments when processing direct reversals and refunds. Depending on the state of the payment, BRM may or may not be able to perform these activities.

About Directly Reversing Payments from BRM

Payment reversals are necessary when a payment is recorded in the BRM database but the payment is not deposited. You create payment reversal batches by using Payment Tool.

When you have Payment Suspense Manager enabled, payments may be reversed due to payment recycling, which is different from directly reversing the payment from the BRM database. Reversals that occur due to recycling happen automatically, and the funds are transferred from a source account to a target account: they are not removed completely from BRM.

The type of payment reversal discussed here is different from recycled payment reversals. Here, you manually reverse a payment to remove it from the system. A recycled payment reversal is a consequence of transferring a payment to a target account.

The following restrictions apply when reversing payments from BRM:

You cannot directly reverse recycled payments: you can reverse only original (non-recycled) payments with a SUB_TRANS_ID value of NULL. Therefore, when creating the payment reversal batch for a payment that entered the database as suspended, you must identify the original suspended payment rather than the active recycled payment. When the reversal batch is submitted to BRM, all active recycled payments that are descended from the original payment will be internally reversed.

When directly reversing a payment, you can reverse only original payments. If you reverse an original suspended payment, PCM_OP_BILL_REVERSE reverses all of the active recycled payments that were distributed to customer accounts from that payment. See "About Directly Reversing Payments from BRM".

BRM uses PCM_OP_BILL_REVERSE to process manual reversals and PCM_OP_PYMT_RECYCLE_PAYMENT to process payment reversals during recycling. For more information, see "How Payments Are Reversed".

About Refunding Payments

You create payment refunds by using Customer Center or calling the PCM_OP_BILL_ITEM_REFUND opcode. You can only refund a payment that has been posted in a customer account; you cannot refund a suspended payment.

Before it refunds a payment, PCM_OP_BILL_ITEM_REFUND determines whether Payment Suspense Manager is enabled. If so, it checks the account POID in the input flist against the account POID in the /config/psm object to see whether the account is the suspense account. If the two POIDs match, the opcode generates an error.

If you suspend a payment that has been refunded (the /item/refund object was closed), the due amount on the account is increased by the same amount that was removed by the refund adjustment.

For more information on payment refunds, see "About Refunds" in BRM Managing Accounts Receivable.

About Removing Unallocatable Payments from Suspense

In some cases, you may determine that a suspended payment cannot be allocated, and should be removed from the system. Payments of this nature represent unrealized revenue. To track revenue and report for these payments, you can remove them from the payment suspense account as unallocatable.

Note:

When removing an unallocatable payment from suspense, only the active suspended payment is reversed. You cannot reverse any distributed payments or payments that have been reversed due to recycling. After you remove a payment as unallocatable, you cannot return it to the BRM system.

You use Payment Center to remove unallocatable payments from suspense. BRM assigns a G/L ID of 112 for the reversal, placing the payment amount in a special G/L bucket so that you can obtain information about how much unallocatable revenue you have. This amount was a credit that your company could not recognize toward a debit on any account. It is removed from the system and tracked for accounting purposes.

You can remove an original or recycled payment from suspense as unallocatable. Removing unallocatable payments from suspense does not generate any recycled payments.

In some cases, you may must partially distribute a suspended payment and remove the remaining suspended amount as unallocatable. If you then resuspend one of the distributed payments, BRM creates a new suspended payment for the distributed payment's amount, and you can later remove this new amount as unallocatable if necessary.

Note:

If one or more distributed payments have been removed as unallocatable, you cannot directly reverse the original payment from the BRM database.

About Payment Suspense Manager and Client Applications

The payment suspense process is initiated in one of three ways:

Through original payments, suspended payments, and Payment Tool when payment analysts work with a payment batch.

Through a payment gateway when it processes a payment file.

Note:

For the full range of Payment Suspense Manager functionality to work with a payment gateway, the payment gateway must be directly integrated with BRM payment services.

Through Payment Center when payment analysts work with payment batches that contain suspended payments or after payments have been posted in customer accounts.

There are two BRM client applications that are used in the payment suspense process: Payment Tool and Payment Center. Payment Tool is used to determine whether any payments should be suspended and Payment Center is used to investigate and correct suspended payments. Depending on how you initiate the payment suspense process, you use one or both of these applications.

If a payment clerk loads payment batches into BRM, you use a combination of Payment Tool and Payment Center.

If the payment gateway loads payment batches into BRM, you use only Payment Center.

If payments are already posted to customer accounts, you use only Payment Center.

How you use these client applications differs depending on how the payment process is initiated.

Figure 9-6 shows how the payment suspense process works when you use Payment Tool to load payments:

When you receive externally initiated payment batches, you perform all validation and suspense tasks by using Payment Tool and all correction tasks by using Payment Center.

Use Payment Tool for the following tasks:

Validate a batch of payments.

Manually suspend a payment that passed validation but requires special handling. Or, change the status of a manually suspended payment back to validated.

Submit validated payments to BRM.

Use Payment Center for the following tasks:

Investigate and correct suspended payments.

Apply corrected payments to the appropriate account.

Remove a payment from suspense if you cannot correct it within a reasonable time.

Typically, when you use Payment Tool to process a batch of payments, you import the batch and validate the payments. The results of validation show the status of payment, indicating whether the payment was successful or suspended.

You can then do one of three things:

Submit the batch to BRM, which posts all successful payments to the correct accounts and posts any suspended payments to the payment suspense account. In this case, you would later open Payment Center to investigate and correct the suspended payments and resubmit the corrected payments to BRM.

Correct the suspended payments before submitting the batch. In this case, you would immediately launch Payment Center from Payment Tool and correct the payments. Then, you must return to Payment Tool to revalidate the payments and submit the payment batch to BRM.

Save the payment batch as a PMT file for later processing. In this case, you would open the PMT file in Payment Tool and begin the validation process again.

When you use automated payment processing, like that provided by a payment gateway, there is no need for payment personnel to handle a payment batch, validate payments, or submit payments to BRM. These steps are all performed automatically by the payment gateway working in concert with BRM.

Figure 9-7 shows how the payment suspense process works if you use a payment gateway to process payments.

In this case, the payment gateway directs BRM to perform the validation and suspense tasks you would otherwise perform by using Payment Tool. After BRM determines payment status, it submits the payments to the BRM database and moves any suspended payments to the payment suspense account. Then you use Payment Center to review the contents of the payment suspense account, investigate the suspended payments, correct any problems, and submit the corrected payments to BRM.

When you suspend payments that were successfully submitted to customer accounts, you use Payment Center to undo the allocation of the payments in the customer accounts and save them to the payment suspense account. You can then investigate the suspended payments, correct any problems, and resubmit them to the correct accounts.

For detailed information on Payment Tool, see Payment Tool Help. For information on Payment Center, see Payment Center Help.

Summary of Payment Suspension Guidelines and Restrictions

This section provides a review of guidelines and restrictions that apply to Payment Suspense Manager.

General Guidelines

The following guidelines and restrictions apply to suspended payment processing.

Only externally initiated payments can be suspended and managed by using Payment Center.

The currency of a recycled payment must match the currency of its original payment.

Payments can be recycled any number of times, but a recycled payment can have only one original payment.

You cannot change the properties of a payment after it has been directly reversed, removed as unallocatable, or recycled completely.

You cannot directly reverse a suspended payment if any portion of the payment has been removed from suspense as unallocatable.

You cannot distribute failed payments. These payments are stored in BRM as /event/billing/payment/failed objects and have a status of PIN_PYMT_FAILED. They are created to handle unconfirmed payment processing. For more information, see "Handling Failed Unconfirmed Payments".

To directly reverse a payment outside of the recycling process, you must reverse the original payment. If you reverse a suspended payment that was applied to one or more customer accounts, all posted payments will be reversed before the suspended payment is reversed.

Suspended Payment Guidelines

The following guidelines apply to suspended payments.

You can process only one suspended payment at a time; you cannot apply multiple suspended payments to customer accounts in the same allocation. Similarly, you cannot return two distributed payments that originated from different suspended payments in the same operation.

If you change the properties (for example, the action owner) of a suspended payment, it will be reversed and a new payment event is created to contain the updated information.

You cannot change the action owner or any other properties of a suspended payment after it has been completely distributed to customer accounts. However, if you return any of the distributed payments to suspense, you can change the properties of the resulting suspended payment.

You cannot refund a suspended payment; you can refund only a payment that has been applied to a customer account. You create payment refunds by using Customer Center or by calling PCM_OP_BILL_REFUND_ITEM.

If you suspend a payment that was previously refunded (the /item/refund object was closed), the due amount on the account is increased by the same amount that was removed by the refund adjustment. For more information on adjustments, see "About Adjustments" in BRM Managing Accounts Receivable.

Distributed Payment Guidelines

The following guidelines apply to distributed payment processing.

If the entire list of distributed payments does not pass validation, it is rolled back to suspense.

You cannot recycle a payment directly from one customer account to another customer account; first you must suspend the payment and then apply it to the target account.

When recycling a distributed payment to suspense, the entire payment is recycled; you cannot recycle a partial payment amount.

If one or more distributed payments have been removed as unallocatable, you cannot reverse the original payment from the BRM database.

Enabling Payment Suspense in BRM

By default, Payment Suspense Manager is disabled in BRM. You can enable this feature by modifying a field in the ar instance /config/business_params object created during BRM installation.

With the feature enabled, BRM categorizes a payment as successful, suspended, or failed whenever it validates a payment.

With this feature disabled, BRM determines only whether a payment is successful or failed; it does not determine whether a payment should be suspended. Any payment that would normally be suspended and moved to the payment suspense account for investigation is, instead, considered a failed payment.

You modify the /config/business_params object using the pin_bus_params utility. For information on this utility, see pin_bus_params.

To enable Payment Suspense Manager:

Use the following command to create an editable XML file for the BusParamsAR parameter class:

pin_bus_params -r BusParamsAR bus_params_AR.xml

This command creates the XML file named bus_params_AR.xml.out in your working directory. If you do not want this file in your working directory, specify the full path as part of the file name.

Search the XML file for following line:

<PaymentSuspense>disabled</PaymentSuspense>

Change disabled to enabled.

Caution:

BRM uses the XML in this file to overwrite the existing /config/business_params object for the ar instance. If you delete or modify any other parameters in the file, these changes affect the associated aspects of BRM's billing configuration.

Use the following command to load the change into the /config/business_params object:

pin_bus_params bus_params_AR.xml

You should execute this command from the BRM_Home/sys/data/config directory, which includes support files used by the utility. To execute it from a different directory, see pin_bus_params.

Read the object with the testnap utility or Object Browser to verify that all fields are correct.

(Multischema systems only) Run the pin_multidb script with the -RCONFIG parameter. For more information, see "pin_multidb" in the BRM System Administrator's Guide.

Creating a Payment Suspense Account

When BRM determines that a payment should be suspended, it stores the suspended payment and all information available for the payment in the payment suspense account.

By default, BRM supports only one payment suspense account. For more information about supporting multiple payment suspense accounts, see "Customizing Payment Guidance to Suspense". You create payment suspense accounts by using Customer Center and base them on the default customer service representative (CSR) plan.

On the Contact page, create a suspense account. Enter the First Name with prefix payment_value and the Last Name with prefix suspense_value, where value is any string to distinguish a payment suspense account. The value can be same or different for payment and suspense. This information is not case sensitive.

For example, payment_USDsuspense_USD or payment_USDsuspense_country.

On the Plan page, select the CSR plan for your BRM system.

Important:

The CSR plan you select must comply with these rules:

The admin_client service should have been used when setting up the plan.

There can be absolutely no deals or charges attached to the plan.

On the Payment page, select Undefined for Payment Method.

For all other required fields in the Account Creation wizard, select the defaults.

Click Finish to create the account.

When BRM creates a payment suspense account, the PCM_OP_CUST_POL_PREP_NAMEINFO policy opcode first prepares the contact information for validation and then determines whether Payment Suspense Manager is enabled. If it is enabled and the account being checked is the payment suspense account, this opcode retrieves the POID of the /config/psm object if that object exists. BRM references the /config/psm object to locate payment suspense accounts whenever it suspends a payment or you correct a payment.

A payment suspense account POID is then passed to the PCM_OP_CUST_SET_NAMEINFO opcode. This opcode stores the account POID in the /config/psm object.

Working with Suspense Reason Codes and Action Owner Codes

Suspense reason codes explain why a payment was moved into or out of suspense or why an unallocatable payment is removed from the system. Action owner codes indicate who is responsible for correcting the problem or taking other action on the payment. For example, a reason code could indicate that an account number is wrong or that a payment must be removed from suspense because it could not be allocated in a reasonable amount of time. An action owner code could indicate that Sally Brown is responsible for investigating the suspended payment.

Note:

Action owner codes are typically used to assign payment analysts to particular suspended payments and enable them to search for all the payments they must correct. However, you can customize action owner codes to provide different types of information such as an action that you took regarding a suspended payment.

Reason codes and action owner codes are used in various ways by the different tools you use to process payments:

Payment Tool: Provides reason lists that payment personnel can choose from as they suspend a payment.

Payment Center: Provides action owner lists that payment personnel can choose from when assigning a person to correct a payment or use as a criteria when searching for a suspended payment. It also provides reason lists that payment personnel choose from when correcting a payment, suspending a payment, or removing an unallocatable payment from the system.

Payment Gateway: Automatically assigns reasons to payments processed through a payment gateway provided you implement a preprocessing application to map reason codes in the payment file to reason codes you have created in BRM.

To ensure that BRM can assign the full range of reason codes and action owner codes suitable for your business needs, you customize BRM by:

Creating and loading a reasons.locale file that lists each reason code and action owner code.

About the Reasons.locale File

The reasons.locale file defines each reason code domain, the reason codes or action owner codes that belong to the domain, and the event G/L ID. A reason code domain is a unique identifier, or version, used to organize reason codes according to the activities they are used for. For example, all reason codes that describe why you are removing an unallocatable payment from suspense would be defined within the reason code domain dedicated to that purpose. The domain and reason code information is used to build the /strings object and the event G/L ID is used to build the /config/map_glid object.

Payment suspense reason codes and action owner codes use the following domains:

The following ranges are reserved for default BRM reason codes related to payment suspense and payment status:

0: Default reason code.

1 to 1000: Reason codes for successful payments.

1001 to 2000: Reason codes for failed payments.

2001 to 3000: Reason codes for suspended payments.

3001 to 4000: Action owner codes.

4001 to 5000: Reason codes for reversals generated when a payment is moved from a source account to a target account during recycling and for removing unallocatable payments from suspense.

To add reason codes of your own, use values above 100,000.

You must assign G/L IDs for all reason codes you create for the following payment processes:

Removing unallocatable payments from suspense.

This enables BRM to map these payments to the G/L bucket used to store a record of payments that were removed from suspense because they were not correctable. You can then create reports and applications to help you track this form of unrealized revenue. The G/L ID assigned to the /event/billing/reversal event, which occurs when payments are removed from BRM as unallocatable, is 112.

Recycling payments to or from suspense. You can use information in this bucket to help determine how much revenue is recovered from suspense. This G/L bucket is reserved for distributed payments, distributed payments returned to suspense, and original payments to a customer account that are manually suspended, is 113. G/L ID bucket 113 stores both the recycled payment and its corresponding payment reversal. Storing both the payment and reversal in the same G/L ID bucket ensures the correct balance of debits to credits when generating reports.

Note:

You should not assign G/L IDs for action owner codes, and there is no need to assign G/L IDs for the reason codes for suspended payments.

The following example shows a reasons.locale file segment defining a payment suspense reason code domain. Some reason codes are BRM defaults, and some are defined by a user (ID >= 100,000).

Loading Reason Codes into the BRM Database

To define reason codes and action owner codes for Payment Suspense Manager, you edit the reasons.en_US sample file in the BRM_Home/sys/msgs/reasoncodes directory. You then use the load_localized_strings utility to load the contents of the file into the /strings and /config/map_glid objects.

When you run the load_localized_strings utility, use this command:

load_localized_strings reasons.locale

Note:

If you are loading a localized version of this file, use the correct file extension for your locale. For a list of file extensions, see "Locale Names" in BRM Developer's Guide.

Caution:

The load_localized_strings utility overwrites the /config/map_glid object. If you are updating this object, you cannot load new G/L ID maps only. You must load complete sets of data each time you run the load_localized_strings utility. This is also true when using the /strings object, but only if you specify the -f parameter. Otherwise, the load_localized_strings utility appends the new data to the object.

How Payments Are Suspended during Payment Processing

During payment processing, the PCM_OP_PYMT_COLLECT opcode calls the PCM_OP_PYMT_VALIDATE_PAYMENT opcode, to determine the status of the payment records. For information about PCM_OP_PYMT_COLLECT, see "How BRM Collects Payments".

When PCM_OP_PYMT_VALIDATE_PAYMENT receives a payment to validate, it determines whether the payment should be suspended and prepares it for posting by enriching the flist with any missing information.

It begins by evaluating the input flist to determine whether it contains the channel ID for the payment. If not, it gets the channel ID from the /config/ach object and adds it to the flist.

Then, PCM_OP_PYMT_VALIDATE_PAYMENT calls the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode to validate the payment and further enrich the flist with any missing payment information.

After PCM_OP_PYMT_VALIDATE_PAYMENT receives the results from the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode, it returns the flist to PCM_OP_PYMT_COLLECT for use when the payment is posted.

Flags are not used directly by PCM_OP_PYMT_VALIDATE_PAYMENT. They are passed in from PCM_OP_PYMT_COLLECT for the PCM_OP_PYMT_SELECT_ITEMS opcode. For example, Payment Tool can set the PCM_BILLFLG_DEFER_ALLOCATION flag to indicate which payments should be left unallocated.

Note:

When you submit payments by using Payment Tool, payments that have a valid account number but a missing bill number are not marked for suspense by default. To enable Payment Tool to return such payments as suspended, see "Customizing Suspense Criteria for Payment Tool".

How Payments Are Recycled to and from Suspense

The PCM_OP_PYMT_RECYCLE_PAYMENT opcode removes a payment from a source account and posts it to a target account. It is called when one or more payments in Payment Center are submitted to the BRM database.

Caution:

It is not recommended to have more than one payment suspense account in the /config/psm object.

When a payment is recycled from suspense to a customer account, the input flist generated for the submission includes the corrected account number, corrected bill number, and the transaction ID of the original payment. It can also contain other corrected information if you customized BRM to include additional validation criteria.

When a transaction is opened, PCM_OP_PYMT_RECYCLE_PAYMENT handles all of the activities required to move each payment in the CHARGES array from the source account to the target account. The transaction ID is recorded in all the event objects created when this opcode processes a payment.

In general, to recycle the payment, PCM_OP_PYMT_RECYCLE_PAYMENT uses the source account referenced in the input flist's PIN_FLD_EVENT_OBJ field and the destination account POID in the PIN_FLD_ACCOUNT_OBJ field to determine the operation it will perform.

For example, if the account referenced in PIN_FLD_EVENT_OBJ is the suspense account and the account referenced in PIN_FLD_ACCOUNT_OBJ is a customer account, the opcode distributes all or part of the suspended payment to the customer account.

The source and target accounts, combined with the number of payments in the CHARGES array, determine the operation that PCM_OP_PYMT_RECYCLE_PAYMENT performs, as shown in the following table.

Recycled Payment Results

PCM_OP_PYMT_RECYCLE_PAYMENT performs the following operations when recycling payments:

Opens a transaction.

Determines the direction of the payment recycling: to or from a payment suspense account. The transfer direction is determined by the active payment's account POID and the target account POID.

Determines if multiple distributed payments are being handled.

Checks that the currency is the same for every charges element.

If it is returning an entire distribution to suspense, calls PCM_OP_PYMT_RECYCLED_PAYMENTS_SEARCH to retrieve the active suspended payment information, including the amount remaining in the suspended payment after recycling, and adds it to the CHARGES array.

Chooses a course of action based on the source account/target account combination plus the information in the CHARGES array.

Calls PCM_OP_PYMT_COLLECT to apply the payments to the target accounts, prepares the payment batch, and enriches the input flist of PCM_OP_PYMT_COLLECT with the following information:

The total charge amount.

Total reversal amount, for posted payments that are being suspended.

Total original payment amount, for payments that are being posted from a payment suspense account to a customer account.

This opcode, in turn, calls PCM_OP_PYMT_VALIDATE_PAYMENT to validate the information in the CHARGES array. If an invalid scenario exists, the payment is guided to suspense.

Note:

For payments guided to suspense due to validation failures, PCM_OP_PYMT_RECYCLE_PAYMENT rolls back the entire transaction after PCM_OP_PYMT_COLLECT completes.

Prepares the reversal batch, creating new elements and setting a new reason code.

If PCM_OP_PYMT_RECYCLE_PAYMENT is being called for a distribution and the total of the charges in the input flist does not equal the amount to be distributed, the opcode determines whether the input flist specifies an amount to be placed in suspense.

If the input flist does not specify an amount to be placed in suspense, the opcode posts the remaining amount to the suspense account.

If the input flist specifies an amount to be placed in suspense, the opcode generates an error.

Calls PCM_OP_PYMT_COLLECT to:

Create the payment batch.

Create a suspended payment if an amount remained in the suspended payment after it was applied to one or more accounts.

Update the /event/billing/payment/pay_type object with the SUB_TRANS_ID value specified in the PIN_FLD_CHARGES array of the flist.

If the payment batch was successful, updates the input flist for the PCM_OP_BILL_REVERSE opcode with the following information:

The reason code for the reversal

The PAYMENT_TRANS_ID value

Calls PCM_OP_BILL_REVERSE to create the reversal batch.

PCM_OP_BILL_REVERSE updates the /event/billing/reversal/pay_type object with the PAY_TRANS_ID, the POID of the payment suspense account, and the reversal total.

If PCM_OP_PYMT_COLLECT fails or if any information is invalid, PCM_OP_PYMT_RECYCLE_PAYMENT rolls back the entire transaction, leaving the suspended payment in its original state.

Records the success or failure of the entire operation in the PIN_FLD_RESULTS field of the output flist.

How Recycled Payments Are Retrieved

The PCM_OP_PYMT_RECYCLED_PAYMENTS_SEARCH opcode retrieves payment information such as the payment amount, transaction ID, subtransaction ID, account and bill number, payment types, and payment status. If you specify that more information be returned, this opcode can return additional payment information such as the action owner and the date suspended.

This opcode is called by:

Payment Center to provide additional information on the payments returned by a search (for example, allocated amount and unallocated amount).

PCM_OP_BILL_REVERSE when it reverses a payment that was posted to the suspense account when it entered the BRM database. This opcode uses PCM_OP_PYMT_RECYCLED_PAYMENTS_SEARCH to find all active payments associated with the original suspended payment so that those payments also can be reversed. For more information, see "How Payments Are Reversed".

PCM_OP_PYMT_RECYCLE_PAYMENT when it returns an entire set of distributed payments to the suspense account.

As input, this opcode receives the transaction ID of the payment it is to search for. It also receives an optional PIN_FLD_RESULTS array, which, with the PCM_OP_FLAG_READ_RESULT flag, determines the type of information returned by the opcode.

PCM_OP_PYMT_RECYCLED_PAYMENTS_SEARCH performs the following operations when searching for payments:

Verifies that the transaction ID in the PIN_FLD_TRANS_ID field is for an original suspended payment. To do this, the opcode checks the PIN_FLD_SUB_TRANS_ID field. If this field is not NULL, the payment is not an original payment, and the opcode returns an error.

Searches for all payments whose subtransaction ID matches the PIN_FLD_TRANS_ID field of the payment in the input flist.

Checks to see whether the PIN_FLD_RESULTS array in the input flist and the PCM_OP_FLAG_READ_RESULT flag are present. The opcode returns payment information based on these presence of the flag and array, as follows:

If neither the flag nor the array is present, the opcode returns only the fields in the output flist.

If the flag is present, the opcode returns all the fields in the /event/billing/payment object.

If the flag is not present but the array is, the opcode returns the fields in specified in the PIN_FLD_RESULTS array plus the payment information fields normally included in the output flist.

If the both the flag and array are present, the opcode ignores the array and returns all the fields in the /event/billing/payment object.

PCM_OP_PYMT_RECYCLED_PAYMENTS_SEARCH does not retrieve payment states for payments that have been reversed and are no longer active. If the search results are NULL, PCM_OP_PYMT_RECYCLED_PAYMENTS_SEARCH searches for reversal events related to a suspended payment. If a reversal event is found, the suspended record is filtered and not returned.

How Payments Are Reversed

The PCM_OP_BILL_REVERSE opcode prepares information for PCM_OP_BILL_REVERSE_PAYMENT to perform reversals. PCM_OP_BILL_REVERSE reverses payments during the following payment suspense operations:

A payment is recycled to or from suspense.

A suspended payment is removed from BRM as unallocatable.

Payments can also be reversed directly from BRM by submitting a payment reversal batch from Payment Tool. For information on how direct reversals are performed, see "How BRM Reverses Payments".

How Payments Are Reversed During Recycling

If PCM_OP_BILL_REVERSE is called from PCM_OP_PYMT_RECYCLE_PAYMENT, the reversal is due to recycling, and PCM_OP_BILL_REVERSE performs the following operations:

Assigns the reversal TRANS_ID value for each recycled payment.

Opens a transaction and checks the appropriate /config/business_params object to verify that Payment Suspense Manager is enabled.

Calls PCM_OP_BILL_REVERSE_PAYMENT to perform the reversal and create the associated objects in the database. For each /event/billing/reversal object created, PIN_FLD_PAYMENT_TRANS_ID is set to the transaction ID of the recycled payment. This opcode populates the reversal flist with each recycled payment's TRANS_ID value.

Populates the payment batch with the sum of the reversal flist.

If the reversal was performed as part of recycling multiple distributed payments back into suspense, returns the recycled payments' reversal information in the PIN_FLD_MULTI_RESULTS array.

How Payments Are Removed As Unallocatable

PCM_OP_BILL_REVERSE performs the following operations to remove payments from BRM as unallocatable:

Assigns the reversal event a TRANS_ID value.

Opens a transaction and checks the appropriate /config/business_params object to verify that Payment Suspense Manager is enabled.

Checks to see whether the following criteria are met:

The payment is a suspended payment. To do so, it compares the account POID in the flist with the account POID of the payment suspense account in the /config/psm object.

The payment is active.

The value of the PIN_FLD_FLAGS field is set to PIN_REVERSE_FLAG_REVERSE_AS_UNALLOCATED (1).

Calls PCM_OP_BILL_REVERSE_PAYMENT to reverse the payment in a payment suspense account and create the associated objects in the database. For the /event/billing/reversal object, PIN_FLD_PAYMENT_TRANS_ID is set to the transaction ID of the suspended payment. This opcode populates the reversal flist with the payment's TRANS_ID value.

Populates the payment batch with the sum of the reversal flist.

Validates the reverse payment operation and creates the reversal batch event in the database.

The result of the reversal is returned in the PIN_FLD_RESULTS field of PCM_OP_BILL_REVERSE. The reversal will not be allowed if either of the following conditions is true:

The payment is not a suspended payment.

The payment is not an active payment.

Customizing Payment Suspense Validation

The PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode validates payments to determine whether they can be successfully posted or whether a failed, unconfirmed payment needs reversal. If automatic write-off reversals are enabled, it also determines whether BRM should perform a write-off reversal.

In default implementations, BRM considers two questions when determining whether a payment should be suspended:

Is the account number present and valid?

Is the account closed?

By default, the bill number is not initially used to suspend payments. It is used only when the account number is missing.

A payment is suspended in the following situations:

The account is closed.

The account number is missing and the bill number is missing.

The account number and the bill number are invalid.

The account number does not match the account number from the bill.

A payment is posted if the account is not closed and the following is true:

The account number is present and valid. If the bill number is missing, the payment is posted at the account level.

The account number is missing but the bill number is present and valid. Such payments are posted at the bill level.

You can broaden this scope by customizing the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode to perform validation using additional criteria (for example, customer segment, payment amount, and so on). BRM uses these criteria to determine whether the payment validation logic should mark a payment for suspense.

Note:

If you include additional criteria in the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode that is not already part of the objects created by payment processing, you must also extend these objects by adding these fields so that the object records all the criteria considered by payment validation.

If neither the bill number nor bill POID was submitted with the payment, you can configure BRM to find the bill based on the due amount. See "Finding Bills by Due Amount".

Customization Example: Suspending Large Payments

As an example, if you want a payment analyst to always examine suspiciously large cash payments or cash payments that appear to arrive from the Internet, you can customize BRM to suspend any payments that meet these conditions. If a cash payment is suspiciously large, there may be a customer error or recording error that must be investigated. Because the Internet is not a likely source of cash payments, you may want to obtain extra confirmation on how this payment was made.

This type of customization includes the following tasks:

Modify the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode to include logic that checks the PIN_FLD_PAYMENT_TYPE field to determine if this is a cash payment and also checks PIN_FLD_CHANNEL_ID to see whether the payment was made over the Internet. If both conditions are met, have the opcode set PIN_FLD_STATUS to PIN_PYMT_SUSPENSE.

Also modify the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode to include logic that checks the PIN_FLD_AMOUNT field to see whether the payment amount is greater than the amount you establish as the threshold for suspiciously large payments (for example, $10,000). If this is a cash payment and the payment amount exceeds the threshold, have the opcode set PIN_FLD_STATUS to PIN_PYMT_SUSPENSE.

Customization Example: Threshold for Suspending Payments

You can customize the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode to enforce business practices related to suspense. For example, if you find that having payment analysts review suspended payments for very small amounts costs you more than the payments are worth, you can customize BRM so that it does not move any payment of less than a certain amount into the payment suspense account.

To create a suspense threshold, you customize the opcode to check the PIN_FLD_AMOUNT field to see whether the payment amount is less than the threshold amount (for example, $1). You check this condition for any payment whose status is set to PIN_PYMT_SUSPENSE. For each payment that meets these conditions, you set the account POID to a special account you set up for this type of unallocatable payment. You also set PIN_FLD_STATUS to PIN_PYMT_SUCCESSFUL so that PCM_OP_PYMT_COLLECT can post the payment.

Note:

When you implement any of the customizations just discussed, you modify the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode. This opcode validates only externally initiated payments; it does not validate BRM-initiated payments. Therefore, none of the customizations you implement through this opcode affect BRM-initiated payments.

Customization Example: Finding Unconfirmed Payments

In the case of failed unconfirmed payment, if the payment processor is not able to send a transaction ID with each payment, you can modify the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode to find the original unconfirmed payment by using other payment properties that are sent from the payment gateway, such as the original unconfirmed payment amount. When the original unconfirmed payment is found, the item object to which the payment was applied can be loaded into the input flist for the PCM_OP_PYMT_APPLY_FEES opcode.

Note:

If you used failed payment properties to locate the payment, you must also update the /event/billing/payment/failed object to contain the same properties that you are using to locate the original unconfirmed payment.

Customization Example: Error Handling

You can modify the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode to handle errors that occur because the original unconfirmed payment cannot be found or the transaction IDs do not match.

Default Payment Validation Process

The PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode processes payments in three phases:

Payment suspense phase: Receives a list of payments from PCM_OP_PYMT_VALIDATE_PAYMENT and checks the /config/business_params object to determine whether Payment Suspense Manager is enabled. If so, it checks the payments to determine whether any payments must be suspended and updates the PIN_FLD_STATUS field accordingly.

Failed unconfirmed payment phase: For all payments with a PIN_FLD_STATUS in the failed range, uses the payment method value to determine whether a failed payment has an associated unconfirmed successful payment or if it is a failed confirmed payment.

The input flist contains the POID of the original payment item, the transaction ID, and the amount of the original payment to properly handle unconfirmed failed payments.

Write-off reversal phase: Checks the /config/business_params object to determine whether automatic write-off reversals are enabled. If so, it determines whether the payment is for an account, bill, or bill item that has been written off. If so, it sets PIN_FLD_STATUS accordingly.

In this phase, the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode first checks the PIN_FLD_STATUS field to determine whether the payment has a status in the suspense range, indicating that the payment has already been marked for suspense. In this case, the opcode passes the output flist and associated status back to PCM_OP_PYMT_VALIDATE_PAYMENT. BRM will then use PCM_OP_PYMT_COLLECT to direct the payment to the payment suspense account.

If the payment is not already marked for suspense, the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode does the following:

Validates the account number specified by the PIN_FLD_ACCOUNT_NO or PIN_FLD_ACCOUNT_OBJ field in the input flist or searches for the corresponding account POID.

Validates the bill number specified by the PIN_FLD_BILL_NO field in the input flist and searches for the corresponding bill POID, /billinfo POID, and account POID.

If neither a bill POID nor a bill number was submitted with the payment, BRM uses the bill amount to find the bill.

If the account and bill numbers supplied in the input flist are both invalid or the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode cannot find the account or bill POIDs (or bill amount), it marks the payment for suspense. It also compares the account POID from the /bill object with the account POID found in step 1. If they do not match, the opcode marks the payment for suspense.

Checks the PIN_FLD_STATUS field in the /account object to determine whether the account is closed. If the account is closed, the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode marks the payment for suspense.

Checks any custom validation criteria and marks the payment for suspense if appropriate.

Writes the status of the payment in the PIN_FLD_STATUS field, and includes this field in the output flist. If the payment must be suspended, it sets this field to one of the values in the suspense range, as appropriate.

Note:

When an /event/billing object is created for a suspended payment, it stores the original reason code associated with a failed payment that has been flagged for suspense. This ensures that the reason initially associated with the failed payment is not lost if BRM places the payment in suspense.

When the /event/billing/payment object is created, it stores the original account number provided for the payment being suspended, the original bill number, and the original transaction ID.

Failed Unconfirmed Payments Phase

In this phase, the opcode considers only payments whose status is marked as failed: those whose PIN_FLD_STATUS value is in the financially failed range. These payments are ones that the opcode was able to validate, but were marked by the payment processor as failing for financial reasons. In default implementations, the opcode requires the transaction ID and result of each payment to prepare the failed unconfirmed payments for reversal.

If the failed payment is an unconfirmed payment, PCM_OP_PYMT_VALIDATE_PAYMENT:

Searches the /event/billing/payment object for an unconfirmed payment with the transaction ID passed in with the failed payment.

Does one of the following:

If an unconfirmed payment is found, sets PIN_FLD_RESULT to PIN_PAY_TYPE_SUCCESS.

If the transaction ID of the unconfirmed payment is not found, it checks the /config/business_params object to determine whether Payment Suspense Manager is enabled.

If so, it sets PIN_FLD_STATUS to PIN_FLD_FAILED_SUSPENSE and BRM posts the payment to the payment suspense account.

If not, it sets PIN_FLD_RESULT to PIN_FLD_PAYMENT_RESULT_FAIL, and a reversal does not occur. The subsequent steps do not occur and manual allocation is required.

Loads the following unconfirmed payment information from the /event/billing/payment storable class into the PIN_FLD_FAILED_PAYMENT_FEE substruct in the PIN_FLD_EXTENDED_INFO substruct of the output flist:

Payment channel ID

Payment method

Transaction ID

Original payment amount

Customer segment

Note:

For unconfirmed payments, the customer segment value is also retrieved from PIN_FLIST_CUSTOMER_SEGMENT_LIST in the input flist of this policy.

Passes the POID of the successful unconfirmed payment in the output flist to PCM_OP_BILL_REVERSE_PAYMENT so it can be reversed.

The output flist sends the array of reversal events and tax events (if created) that were passed in by the PCM_OP_AR_WRITEOFF_REVERSAL opcode.

Write-off Reversal Phase

In this phase, PCM_OP_PYMT_VALIDATE_PAYMENT considers only payments whose status is marked as successful: those whose PIN_FLD_STATUS value is in the successful range. The opcode determines which of these payments is for an account, bill, or bill item that has been written off. It performs the following operations:

Checks the /config/business_params object to determine if automatic write-off reversal functionality for payment processing is enabled.

If this is enabled, checks the /profile/writeoff object to verify that the write-off flag is set for the account.

If both checks are successful, sets the PIN_FLD_STATUS field in the output flist to PIN_PYMT_WRITEOFF_SUCCESS.

Payment Validation Flags

Flags are not used directly by the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode. They are passed in from PCM_OP_PYMT_COLLECT for PCM_OP_PYMT_SELECT_ITEMS. For example, Payment Tool can set the PCM_BILLFLG_DEFER_ALLOCATION flag to indicate which payments should be left unallocated.

Customizing Payment Guidance to Suspense

The PCM_OP_PYMT_POL_SUSPEND_PAYMENT policy opcode enables you to define custom rules for handling payments that are being guided into suspense. For example, you can modify this policy opcode to track the number of times the same payment is guided back to suspense after being applied to the wrong customer account.

In addition, if your company processes distributed payments, you can implement rules to distribute a payment directly to the proper accounts, without first saving the payment to the suspense account. For example, by using the account number associated with the original payment, the original payment amount, and the account number associated with each subpayment amount, you can automatically divide the payment into distributed payments and allocate them to the designated accounts.

For multiple suspense accounts, the PCM_OP_PYMNT_POL_SUSPEND_PAYMENT policy opcode must be modified to select a payment suspense account that matches the criteria specified while creating the account. Otherwise, the policy opcode selects a payment suspense account that matches the login schema.

Customizing Payment Failure Reason Codes

To customize payment failure reason codes, use the PCM_OP_PYMT_POL_CHARGE policy opcode. This policy opcode provides the ability to map the online and offline payment result to the payment status and the reason IDs defined in the /strings object.

In the output flist PIN_FLD_PAYMENT_REASONS array, the array of PIN_FLD_REASON_ID fields contains the failure reasons sent by the payment processor. You can configure this policy opcode to apply fees for failed credit card and direct debit transactions based on the reason for failure.

The input flist contains a results array for a payment batch, including reasons for payment failures.

The output flist contains the payment method, transaction ID, and an array of reason IDs for failed payments.

Customizing Payment Tool

The procedures in this section describe how to add a cash reversal batch to Payment Tool and how to extend Payment Tool to automatically suspend payments that have a missing bill number.

Adding a Cash Reversal Batch

You can add a cash reversal batch to Payment Tool to handle any cash payments that were posted incorrectly and must be reversed from your BRM system. For example, if the currency a customer used to make a payment was later found to be counterfeit, you can remove the payment. This restores the customer's previous account balance and removes the payment from your company's G/L system.

The /event/billing/reversal/cash storable class exists in the BRM database; therefore, there is no need to create one. You only need to add the cash reversal entry to the /config/paymenttool object.

Note:

When you install BRM, a default /config/paymenttool object is created from data in the init_objects.source file.

Use the PCM_OP_WRITE_FLDS opcode to add the cash reversal entry to the /config/paymenttool class. Call the opcode using flag 32. For example:

The PIN_FLD_BATCH_TYPE value determines the batch type: 0 indicates a payment batch and 1 indicates a reversal batch. In this example, PIN_FLD_BATCH_TYPE is set to 1 for reversal.

The PIN_FLD_PURPOSE value determines the field type: 0 indicates the field is read-only and 1 indicates that data can be entered into the field. In this example, the Receipt Date and Reason Code. columns in the reversal batch are read-only. For more information on entry values, see "Creating an Object Definition for a New Payment or Reversal Event".

All changes you make in /config/paymenttool are reflected in the Payment Tool UI when you restart BRM.

Customizing Suspense Criteria for Payment Tool

When you submit payments by using Payment Tool, payments that have a valid account number and a missing bill number are not marked for suspense by default.

To enable Payment Tool to return such payments as suspended, customize the fm_pymt_pol_validate_payment_bill function in the PCM_OP_PYMT_VALIDATE_PAYMENT opcode. Use the &validation_result value to set the PIN_FLD_STATUS value.

Handling Custom Payment Methods

If you create custom payment methods for your BRM system, you must customize Payment Suspense Center to handle them. This overview procedure describes how to create custom classes and fields and enable Payment Center to handle them.

Storable Class Editor creates a C header file called cust_flds.h, a Java properties file called InfranetPropertiesAdditions.properties, and a Java source file for each custom field.

In the directory where Storable Class Editor created the Java source files, compile the source files:

javac -d . *.java

Package the new class files into a JAR file. For example:

jar cvf customfields.jar *.class

Copy the contents of the InfranetPropertiesAdditions.properties file and paste it into the Payment Suspense Center Infranet.properties file. By default, this file is located in:

C:\Program Files\Portal Software\PymtSuspCenter\PaymentCenter

Append the location of the JAR file to the PAYCTRCP environment variable path. For example:

;.;C:\Program Files\Portal Software\PymtSuspCenter\customfields.jar;

Adding Multischema Support in Payment Processing

You can use Payment Center and Payment Tool in a multischema environment.

The multischema support for payment processing enables you to:

Create and submit a single payment batch containing payments made to customer accounts residing in multiple schemas.

Create and submit a single reverse or refund payment batch containing payments made to customer accounts residing in multiple schemas.

Move the suspended payments to the payment suspense account set up for the connected schema.

Recycle the suspended payments to one or more customer accounts residing in multiple schemas by using Payment Center. For example, if you are connected to schema 1, you can use Payment Center to recycle payments from the payment suspense account set up for schema 1 to customer accounts residing in different schemas.

Important:

The multischema support for payment processing is applicable only for Oracle Data Manager (DM) and is not applicable for Oracle IMDB Cache DM.