Resolving Failed BRM-Initiated Payment Transactions

9 Resolving Failed BRM-Initiated Payment Transactions

Learn how to resolve failed credit card and direct debit transactions in Oracle Communications Billing and Revenue Management (BRM).

Topics in this document:

For information about the utilities used for resolving BRM-initiated payment transactions, see "pin_clean" and "pin_recover".

About Failed BRM-Initiated Payment Transactions

Failed credit card or direct debit payment transactions occur when BRM connects to a credit card processor, sends a transaction, but does not get confirmation from the credit card processor that the transaction was completed. This is usually caused by a connection loss.

BRM identifies failed transactions by keeping a record of each transaction in the BRM database. If BRM does not get confirmation that the clearing house received the transaction successfully, checkpoint records are left in the database. To resolve failed transactions, you must resolve all checkpoint records. Transactions usually have a checkpoint record for the following reasons:

A transaction batch was received by the credit card processor, but it wasn't processed completely. To resolve this error, you must resubmit the transaction batch.
A transaction was processed by the credit card processor, but the connection was lost before BRM received the results. To resolve this error, you must update the checkpoints in the BRM database.

Note:

If the payment processor is offline or too busy to handle your transactions, BRM records a no-answer (1) record. You do not need to resolve no-answer records.

BRM includes two utilities that you use to resolve failed BRM-initiated payment transactions, "pin_recover" and "pin_clean". To resolve a failed BRM-initiated payment transaction, you first run the pin_clean utility to see if there are any errors. If there are, the method you use for resolving the error depends on the type of transaction. For example, you can delete failed verifications without restoring them, but you usually need to restore failed authorizations.

How BRM Records Transactions

Before BRM connects to the credit card processor, a table row with the value 999 is inserted in the database. This value remains in the row until BRM processes the result from the Paymentech credit card processor. BRM first sets the result field to the number 1000, plus the Paymentech result code. When BRM begins processing the payment, it resets the result value to the Paymentech result code. If the transactions are completed successfully: regardless of whether the credit card charge was successful: the result column will not have any values over 999.

The following Paymentech result codes are used by BRM:

PASS = 0
FAIL_NO_ANS = 1
FAIL_ADDR_AVS = 2
FAIL_ADDR_LOC = 3
FAIL_ADDR_ZIP = 4
FAIL_CARD_BAD = 5
SRVC_UNAVAIL = 6
FAIL_DECL_SOFT = 7
FAIL_DECL_HARD = 8
FAIL_NO_MIN = 9
INVALID_CMD = 10
FAIL_SELECT_ITEMS = 11
CVV_BAD = 12
NO_CREDIT_BALANCE = 13
FAIL_LOGICAL_PROBLEM = 14
FAIL_FORMAT_ERROR = 15
FAIL_INVALID_CONTENT = 16
FAIL_TECHNICAL_PROBLEM = 17
DEPOSIT_PENDING = 777
AUTH_PENDING = 888
CHECKPOINT = 999
OFFSET = 1000

Failed credit card transactions (checkpoint value of 999) are not collected by pin_collect or PCM_OP_BILL_COLLECT to avoid double charges. Such results indicate a communication problem between Paymentech and BRM.

Result values of 1000+, indicate that an exception occurred within BRM. This means that the 999 checkpoint has been cleared; however payment events were not created in BRM. See "Checkpoints are Cleared but Payment Events Are Not Created" to fix these transaction errors.

Note:

If you add result codes to your system, do not assign them the following values, which are reserved by BRM: 0 - 17, 777, 888, 999, 1000 - 1017, 1777, and 1999.

Resolving Transaction Errors

You should check for transaction errors every day. The best way to do this is to create a script that:

Runs the "pin_clean" utility and reports transaction failures.
```
pin_clean -summary
```
Writes the output to a file. The pin_clean utility writes output to stdout.

Afterwards, you run the pin_recover utility manually to resolve the transaction errors.

Note:

Do not delete deposit or conditional deposit records until you know whether the corresponding charge was successful. The length of time for charges to occur depends on the payment processor. Generally, you should only delete records generated more than 7 days previously. Otherwise, you might charge customers twice if you delete records created within the duplicate detection period. Check with your payment processor.

To resolve failed transactions manually:

Go to BRM_home/bin and run this command:
```
pin_clean -summary
```
Note:

If there are a lot of checkpoint records, use the -search_count_limit option to limit the number of records found. For example:
```
pin_clean -summary -search_count_limit n
```

Review the results. This example contains six failures: 1 verification failure, 3 authorization failures, and 2 refund failures.

CheckPoint Log Summary:
PIN_CHARGE_CMD_VERIFY 1
PIN_CHARGE_CMD_AUTH_ONLY 3
PIN_CHARGE_CMD_CONDITION 0
PIN_CHARGE_CMD_DEPOSIT 0
PIN_CHARGE_CMD_REFUND 2

Follow the instructions to review or delete transactions, for example:
```
Choose function by number:
   1) View PIN_CHARGE_CMD_VERIFY
   2) View PIN_CHARGE_CMD_AUTH_ONLY
   3) View PIN_CHARGE_CMD_CONDITION
   4) View PIN_CHARGE_CMD_DEPOSIT
   5) View PIN_CHARGE_CMD_REFUND
   6) Delete All
   7) Done
```
You can delete all verifications, because they are not associated with any charge. For authorizations and refunds, you might need to repeat the transaction. Read the event details to find out if this is a transaction you need to repeat. For example:
```
0 PIN_FLD_SYS_DESCR       STR [0] "Authorization" 
0 PIN_FLD_ACCOUNT_OBJ    POID [0] 0.0.0.1 /account 28456 0
0 PIN_FLD_AMOUNT          NUM [0] 100.000000
0 PIN_FLD_CREATED_T    TSTAMP [0] (827435459) Thu Mar 21 11:10:59 2017
```
Make a note of the amount and the account number so that you can repeat the transaction later.

"Table 9-1" describes how to resolve each type of transaction.

Important:

To resolve batches of failed deposits ("pin_deposit") and conditional deposits ("pin_collect"), run the "pin_recover" utility with the rfr option before you run the pin_clean utility. See "Resolving Failed Deposits and Conditional Deposits".

Note:

You should delete records with a value greater than 999 when you want to recharge an account by using pin_collect. (The pin_clean utility only processes payments with checkpoint records = 999.) This deletes the /event/billing/charge object and the appropriate rows in the EVENT_T, EVENT_BILLING_CHARGE_T, and EVENT_BILLING_CHARGE_CC_T tables.
Use the pin_recover utility to resubmit the batch. See "Resubmitting Transactions".

Table 9-1 Types of Failed Credit Card Transactions

Record Type	Error	Action
verify	The connection was lost during an online transaction such as account creation.	Delete the transaction record from the BRM database. You do not need to resubmit it.
authorize	The connection was lost during an online transaction such as account creation, or a one-time charge to a single account.	Delete the transaction record from the BRM database. If necessary, repeat the transaction. For example, use Billing Care to charge the account again. Because the transaction was for an authorization, not for a payment, the customer cannot be charged twice.
conditional deposit	The connection was lost while running the "pin_collect" utility.	See "Resolving Failed Deposits and Conditional Deposits".
deposit	The connection was lost while running the "pin_deposit" utility.	See "Resolving Failed Deposits and Conditional Deposits".
refund	The connection was lost when a refund was made.	Delete the transaction record from the BRM database. If necessary, repeat the transaction. For example, use Billing Care to charge the account again. Because the transaction was for an authorization, not for a payment, the customer cannot be charged twice.

Resolving Failed Deposits and Conditional Deposits

To resolve failed deposits ("pin_deposit") and conditional deposits ("pin_collect"), run the "pin_recover" utility with the rfr option before you run the pin_clean utility.

Note:

You cannot use the rfr option if the transaction was an online transaction such as a charge or refund made by using Billing Care or Customer Center.

Request an RFR file from the Paymentech customer support service. If there is no RFR file, you cannot complete this procedure. See "Resubmitting Transactions".

Note:

When you request an RFR file, Paymentech does not send you the file. Instead, it posts it so that the "pin_recover" utility can access it at Paymentech.
Run the pin_recover utility with the rfr option:
```
pin_recover -rfr
```
The pin_recover utility is in BRM_home/bin.
After the pin_recover utility has finished, run it again by using the rfr option. Paymentech sometimes posts multiple RFR files, and you must process all of them before continuing.

Note:

Regardless of the number of times you run the pin_recover utility with the rfr option, accounts are charged only once for each transaction.
Run the pin_clean utility in summary mode again. If you still find transaction errors, see "Resubmitting Transactions".

Resubmitting Transactions

Note:

If you use a payment processor other than Paymentech, ensure that it uses duplicate transaction detection. If not, using the "pin_recover" utility with the resubmit option can cause customers to be billed twice. The duplicate transaction detection offered by Paymentech eliminates this problem.

If running the pin_recover utility with the rfr option does not resolve all transactions, run the pin_recover utility with the resubmit option to resubmit the same batch and process the transactions that didn't go through.

Note:

Resubmit your transactions promptly, or the authorizations might need to be redone. VISA authorizations, for example, last only seven days.

To run the "pin_recover" utility with the resubmit option, you must find the batch ID for the batch you are resubmitting. To do so, run the "pin_clean" utility in summary mode again:

pin_clean -summary

The pin_clean utility is in BRM_home/bin.

A summary of transaction errors appears, followed by a choice of commands. For example:

CheckPoint Log Summary:
  PIN_CHARGE_CMD_VERIFY      1
  PIN_CHARGE_CMD_AUTH_ONLY   3
  PIN_CHARGE_CMD_CONDITION   1
  PIN_CHARGE_CMD_DEPOSIT     1
  PIN_CHARGE_CMD_REFUND      2

Choose function by number:         
  1) View PIN_CHARGE_CMD_VERIFY         
  2) View PIN_CHARGE_CMD_AUTH_ONLY         
  3) View PIN_CHARGE_CMD_CONDITION         
  4) View PIN_CHARGE_CMD_DEPOSIT         
  5) View PIN_CHARGE_CMD_REFUND         
  6) Delete All         
  7) Done

Do one of the following:
- Enter 3 to display transactions made by running the "pin_collect" utility.
- Enter 4 to display transactions made by running the "pin_deposit" utility.
A list of batches appears.
Make a note of the batch ID that you want to resubmit (for example T,2f).

Note:

When resubmitting deposits, each transaction has two transaction IDs, one for the original authorization, and one for the deposit batch sent by the pin_deposit utility. Use the batch ID that was used by the pin_deposit utility.
Enter 3 to quit the pin_clean utility.
Run the "pin_recover" utility with the resubmit option to resubmit the unprocessed transactions. The pin_recover utility is in BRM_home/bin.
```
pin_recover -resubmit batch_ID
```
For example:
```
pin_recover -resubmit T,2f
```
Run the pin_clean utility in summary mode again. If you still find transaction errors, delete them.

Checking for Transactions in Paymentech Send Files

If there are still checkpoint records after using the "pin_recover" utility with the rfr and resubmit options, you can search the Paymentech send files to find out if the transaction was sent to Paymentech, located by default in /fusa_temp. (You define the location of the send files in the temp_dir Paymentech Data Manager (DM) configuration file entry.)

There will probably be multiple files. Find the file that matches the date of the transaction. Open the file in a text editor and search for the batch ID that was reported by the "pin_clean" utility. If the batch ID is not present in any file, the connection was broken between the Connection Manager (CM) and the DM, and the transaction was never sent.

If the transaction is a deposit, you should search the database to find outstanding deposits. To do so, use the testnap utility to search for authorization records with no matching deposit record. See "Testing Your Applications and Custom Modules" in BRM Developer's Guide.

If the transaction is a payment, see "Resolving Payments".

Checking Paymentech Transmission Log Files

The pin_collect utility creates transmission log files to record the billing transactions sent to and received from Paymentech. The files for information sent have the prefix fusas (Paymentech), and the files for information received have the prefix fusar (Paymentech).

The Paymentech transmission log files are stored in the system temporary directory. If that directory is not defined or does not exist, BRM looks for a different folder, in the following order:

The Directory defined by the temp_dir entry in the Paymentech DM configuration file (BRM_home/sys/dm_fusa/pin.conf)
/var/tmp
/tmp

You must delete or archive billing transmission logs periodically to prevent the file system from overflowing. If data security is an issue, delete or archive the files to a secure location immediately after you run billing. Good business practice suggests archiving the files for at least 30 days before discarding them.

Resolving Payments

In rare cases, a credit card charge is made and the checkpoint record is cleared, but the /event/billing/payment object is not recorded in the BRM database. This might happen because of a network or hardware failure.

To find charge events in your database that have no matching payment events, use the testnap utility. See "Testing Your Applications and Custom Modules" in BRM Developer's Guide.

If you are missing payment events, use the "pin_recover" utility with the recover_payment option. Because the charge has been made, this option has no effect on the customer's credit card.

pin_recover -recover_payment

This creates the payment item (if necessary) and payment event objects.

Note:

To create the objects, rows are inserted into the EVENT_T and EVENT_BILLING_PAYMENT_T database tables. If the payment item does not exist for the bill, a row is also inserted into the ITEM_T database table. If possible, the money is allocated to open items; however, you may need to manually allocate the payment.

When a payment recovery was successful, the EVENT_BILLING_PAYMENT_CC_T value = 0.

Resolving Payments for Custom Pay Types

To resolve payments for custom pay types, you must perform additional configuration steps before you run the pin_recover utility with the recover_payment option for the first time.

To resolve payments for custom pay types:

Customize the PCM_OP_PYMT_POL_CHARGE policy opcode to perform the following when it processes your custom pay type:
1. In the policy opcode's output flist, set the PIN_FLD_BATCH_INFO.PIN_FLD_RESULT field to PIN_CHARGE_RES_OFFSET.
2. Update your custom /event/billing/charge/* subclass by setting its PIN_FLD_CHARGE.PIN_FLD_RESULT field to 1000 (PIN_CHARGE_RES_OFFSET).
Go to the BRM_home/apps/pin_billd directory.
Open the pin.conf file in a text editor.
Add the following line for each custom pay type:
```
- pin_recover config_payment paymentPOID
```
where paymentPOID is the POID of your /config/payment object. For example:
```
- pin_recover config_payment 0.0.0.1 /config/payment 200
```

Configuring Delay Intervals for Resolving Payments

If the pin_recover utility is running in parallel with your custom payment application, duplicate transaction IDs can occur. To prevent this, configure the utility to search through charge events (/event/billing/charge/cc) whose creation date is older than a specified delay interval.

To configure a delay interval for resolving payments:

Open the billing utility configuration file (BRM_home/apps/pin_billd/pin.conf) in a text editor.
Search for the event_search_delay entry.
Specify the delay interval:
```
pin_recover event_search_delay value
```
where value is the delay interval in seconds. For example, if you set it to 300, pin_recover searches only through events that are older than 5 minutes.
Save and close the file.

Troubleshooting Unresolvable Credit Card Transactions

This section lists problems you might encounter while trying to resolve failed credit card transactions and provides information on how to fix them.

Unable to remove checkpoints when using an RFR file

If checkpoints still exist after running the pin_recover utility, resubmit the batch. See "Resubmitting Transactions" for more information.

Note:

Paymentech has duplicate transaction detection, which prevents a customer from being charged twice.

If resubmitting the batch does not clear the checkpoints, do the following:

Delete the transactions.
Run the pin_recover utility with the -resubmit option.
Run the pin_clean utility with the -summary option to select and delete batches. Be sure to note the batch ID.
Run the pin_recover utility with the -resubmit option and provide the batch ID.

Checkpoints are Cleared but Payment Events Are Not Created

Look in the database for checkpoints with a value of 1000. If they exist, run the pin_recover utility with the -recover_payment option.

Note:

The pin_clean utility does not show charges that have checkpoint values greater than 999.
You should only use this option when a credit card number is reported as charged in both BRM and Paymentech, but it has not been recorded as paid in BRM. This is an uncommon scenario that can occur when the network connection is dropped after Paymentech responds and before BRM allocates the payment.

This creates the payment item (if necessary) and payment event objects.

Note:

When a payment recovery was successful, the EVENT_BILLING_PAYMENT_CC_T value = 0.

Paymentech does not have an RFR file and never received the payment batch

If you requested an RFR file from Paymentech and one does not exist, run the pin_recover utility with the -resubmit option and provide the batch ID. See "Resubmitting Transactions" for more information.

If Paymentech confirms they received the batch but checkpoints still exist, request an RFR file and run the pin_recover utility with the rfr option.