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. Checkpoint records have a Paymentech result code of 888 or 999. 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 results from the Paymentech credit card processor (which are provided in a Paymentech RFR file).

After BRM retrieves the Paymentech RFR file, it sets the table row's value to 1000. 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

Unsuccessful transactions (result code 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 Cleared but Payment Events 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.

Checking for Transaction Errors

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

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

Afterward, you can manually resolve the transaction errors. See "Resolving Transaction Errors Manually".

Resolving Transaction Errors Manually

To resolve failed transactions manually:

Retrieve the list of transactions that failed. See "Checking for Transaction Errors".
If there are many checkpoint records, limit the number of records found by running the following command:
```
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 you can repeat the transaction later.

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

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.	See "Resolving Failed Refund Transactions".

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 to Paymentech and BRM".

Resolving Failed Deposits and Conditional Deposits

To resolve failed deposits ("pin_deposit") and conditional deposits ("pin_collect"):

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

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.
Go to the BRM_home/bin directory and run the pin_recover utility:
```
pin_recover -rfr
```
Note:

You cannot use the -rfr option for online transactions such as a charge or refund made using Billing Care or Customer Center.
After the pin_recover utility has finished, run it again. 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.
```
pin_recover -rfr
```
Run the pin_clean utility to check for any remaining transaction errors:
```
pin_clean -summary
```
If you still find transaction errors, resubmit the same batch and process the transactions that didn't go through. See "Resubmitting Transactions to Paymentech and BRM".

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.

Resolving Failed Refund Transactions

If the network goes down while processing a refund, verify whether the refund was processed successfully in Paymentech and BRM:

If the refund failed in both BRM and Paymentech, 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.
If the refund was successful in Paymentech but not in BRM, reprocess the RFR file in BRM. See "Reprocessing Failed Transactions in BRM".
If there is no RFR file, ensure the credit card number used is the same in the failed transaction and the account's current payment method. Resubmit the batch to Paymentech and BRM. See "Resubmitting Transactions to Paymentech and BRM".

Note:

If the credit card details used in the failed transaction are not used in the account's current payment method, running the pin_recover -resubmit command will fail.

Reprocessing Failed Transactions in BRM

If a transaction batch was processed successfully by Paymentech but one or more payment transactions failed in BRM, reprocess the RFR file in BRM.

To reprocess failed transactions in BRM:

Go to the BRM_home/bin directory and run the following command:
```
pin_recover -rfr
```
Note:

You cannot use the -rfr option for online transactions such as a charge or refund made using Billing Care or Customer Center.
Run the pin_clean utility to check for any remaining transaction errors:
```
pin_clean -summary
```
If you still find transaction errors, resubmit the same batch and process the transactions that didn't go through. See "Resubmitting Transactions to Paymentech and BRM".

Resubmitting Transactions to Paymentech and BRM

If reprocessing an RFR file in BRM does not resolve all transactions in a batch, resubmit the batch to Paymentech so it can process the transactions that didn't go through. However, it's important that you resubmit transactions to Paymentech promptly, as any delay might lead to the need for reauthorization. VISA authorizations, for example, last only seven days.

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.

To resubmit transactions to Paymentech and BRM:

Find the batch ID for the batch you are resubmitting. To do so, run the "pin_clean" utility 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.
Resubmit the unprocessed transactions to Paymentech:
```
pin_recover -resubmit batch_ID
```
For example:
```
pin_recover -resubmit T,2f
```
Run the pin_clean utility in summary mode again:
```
pin_clean -summary
```
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, 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.

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.

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.

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
```

Troubleshooting Unresolvable Credit Card Transactions

The following details some problems you might encounter while trying to resolve failed credit card transactions and provides information on how to fix them:

Cannot Remove Checkpoints After Using an RFR File

If checkpoints still exist after running the pin_recover utility, resubmit the batch. See "Resubmitting Transactions to Paymentech and BRM" 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:

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

Checkpoints Cleared but Payment Events Not Created

A credit card number can be reported as charged in BRM and Paymentech but not be recorded as paid in BRM. This uncommon scenario can occur when the network connection drops after Paymentech responds but before BRM allocates the payment.

To see if this has occurred, use the testnap utility to search the database for Paymentech result codes with a value of 1000. For information about testnap, see "Testing Your Applications and Custom Modules" in BRM Developer's Guide.

Note:

You cannot use the pin_clean utility to search for these records because the utility searches for result codes of 999 or less.

If the database contains result codes of 1000, you must create payment events for those credit card charges. To do so, run the following command:

Note:

Because the charge has been made, this command does not affect the customer's credit card.

pin_recover -recover_payment

The payment event (/event/billing/payment) objects are inserted into rows in the EVENT_T and EVENT_BILLING_PAYMENT_CC_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, BRM allocates the money to open items. However, you may need to allocate the payment manually.

When a payment recovery is successful, the EVENT_BILLING_PAYMENT_CC_T value is set to 0.

Paymentech Doesn't 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 to Paymentech and BRM" 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.