2 Processing Credit Card and Debit Card Payments with Paymentech

Learn how Oracle Communications Billing and Revenue Management (BRM) uses Paymentech to process your customers' credit card and direct debit payments.

Topics in this document:

Note:

The initials FUSA are sometimes used to represent Paymentech in BRM file names. For example, the Paymentech Data Manager (DM) is named dm_fusa.

About Credit Card Validation and Authorization

Credit card validation validates a customer's address by checking the ZIP code and street address. Credit card validation occurs during account creation, and when customers change their credit card number. If you use the Address Verification System (AVS), Paymentech gives you a discount for each credit card transaction charge.

Note:

AVS supports addresses in the United States and Canada only. For information about changing the AVS validation results, see "Changing How BRM Handles Paymentech Address Validation Return Codes".

Credit card authorization validates the customer's credit card by checking the card number, expiration date, credit limit, and so forth. Authorization occurs at the following times:

  • At account creation, or when customers change their payment method to a credit card payment.

    This type of authorization does not charge the customer's account balance. The payment is recorded in the BRM database, and the balance in the account is adjusted, but the deposit is made later by the "pin_deposit" utility.

  • During billing, the pin_collect utility authorizes payments and deposits them.

  • If there are charges during account creation, such as a purchase fee.

Credit card validation and authorization occur in the same transaction, but BRM handles one at a time.

  1. BRM sends a validation request with an authorization to charge $1.00.

    Note:

    The validation process requires a monetary charge. BRM issues an authorization for $1.00 so that only $1.00 is reserved on the customer's credit card if the AVS request passes.

    The credit card processor returns a validation code and an authorization code. BRM ignores the authorization code and uses the validation code to determine whether the address validation passed. For example, by default an address validation fails if the 5-digit ZIP code is wrong.

    Note:

    Because BRM ignores the authorization, the customer is not charged $1.00.

    If the address validation fails, the next step, authorization, does not occur.

    Note:

    If the Paymentech DM detects non-ASCII data in the address fields during the validation step, the result of the validation request is ignored. This has the same effect as not performing the validation check. This can occur when characters from another language are sent.

  2. BRM sends another validation request with an authorization to charge for an actual amount, such as a purchase fee.

    The credit card processor returns a validation code and an authorization code. This time, BRM ignores the validation code and uses the authorization code to determine whether the authorization passed.

About Setting Up Payment Processing with Paymentech

To enable BRM-initiated payment processing for Paymentech:

  1. Install the Paymentech Manager software. You typically install this at the same time as the rest of the BRM software. If you did not, see "Installing Individual BRM Components" in BRM Installation Guide.

  2. Contact Paymentech to establish a link with Paymentech. See "Exchanging Connection Information with Paymentech".

  3. Configure dm_fusa to send batch payment transactions to Paymentech through SFTP or TCP/IP.

  4. Configure dm_fusa to send online transactions to Paymentech through TCP/IP. See "Configuring Online Payment Transactions".

  5. Configure merchant accounts. See "Setting Up Merchant Accounts".

  6. Set up BRM to process PINless debit payments. See "Configuring PINless Debit Payment Processing".

  7. Set up the Paymentech HeartBeat application. See "Monitoring the Paymentech Connection".

  8. Specify Paymentech configuration options; for example, enabling direct-debit processing and enabling fraud protection. See "Paymentech Configuration Options".

  9. Configure performance options. See "Configuring Paymentech Processing Performance".

  10. Test the installation. See "Testing Paymentech Credit Card Processing".

Exchanging Connection Information with Paymentech

Before you can connect BRM to Paymentech, you need to exchange connection information.

Note:

Even if you already use Paymentech for credit card processing, you must plan for a setup and testing period for Paymentech direct debit.

Information You Need from Paymentech

You need the following information from Paymentech:

  • The IP address and port for the Paymentech online server (the server used for creating accounts) and batch server (the server used for handling regular payments).

  • The presenter ID and password, and the submitter ID and password.

  • Merchant account numbers for each currency you support. The same sets of merchant account numbers can be used for both credit card and direct debit. See "Setting Up Merchant Accounts".

Information Paymentech Needs from You

Table 2-1 lists the information that Paymentech needs from you.

Table 2-1 BRM Default Values for Paymentech

Paymentech Information BRM Default

The IP address and port number for the machine running the Paymentech Data Manager (dm_fusa).

None.

This is required only to use the Paymentech HeartBeat application, which is integrated with the Paymentech Data Manager. For more information, see "Monitoring the Paymentech Connection".

Is this for an existing Presenter ID (PID)?

No

What is the application software that formats the file?

Written by in-house programmers

What is the communications software that sends the file?

Customized by the software vendor

What is the online data communications protocol used to send the online authorization transaction?

TCP/IP Berkley Socket Interface

What is the batch data communications protocol used to send the batch file?

TCP/IP Berkeley Socket Interface

What online format to use for sending online authorizations?

For information about compatible Paymentech online processing format specifications, see "Additional BRM Software Requirements" in BRM Compatibility Matrix.

Will you load balance online authorizations between Paymentech's data centers, or will you use one data center as primary and one as backup?

Primary and Backup

What batch format to use for sending batch files?

For information about compatible Paymentech batch processing format specifications, see "Additional BRM Software Requirements" in BRM Compatibility Matrix.

Will you receive the batch reply file by sending an RFR (Request For Response) record or not?

1 Call (IA) - No RFR record sent to pick up the reply file.

Will you send authorizations separately from deposits OR will you send conditional deposits that will result in a deposit upon authorization approval?

Separate authorizations and deposits and conditional deposits.

What is the average size of your files be in production?

(How many records/transactions?)

None.

This number should be based on your company's projected customer account creation growth and billing rate.

What is the projected submission schedule?

Daily.

Number of times per day?

Once.

What Paymentech functionality do you intend to test?

This list reflects a typical prepaid services company.

  • Online Credit Card Authorization

  • Online Electronic Check Processing (ECP) Verification

  • PINless Direct Debit Purchase Authorizations

  • Batch Electronic Check Processing (ECP) Validate & Deposit

  • Batch Deposits

  • Batch Conditional Deposits (for authorization & settlement)

  • Batch Refunds

  • Full AVS (Address Verification Service)

  • Zip only AVS

  • No AVS

  • Visa CVV2

  • Amex CID

  • MasterCard CVC2

  • Discover CID

  • ECI Indicator (also called Transaction Type)

  • International Currencies (specify)

  • Merchant Descriptor (requires Risk approval)

  • Switch/Solo Cards

Using SFTP for Batch Payment Transactions

You can configure the Paymentech Data Manager (dm_fusa) to use SFTP for sending batch payment transactions to the Paymentech payment processor. Batch payment transactions include batch payments, multiple verifications, multiple authorizations, deposits, and refunds.

To send batch payment transactions through SFTP, follow these steps:

Setting Up Authentication Between dm_fusa and Paymentech

Set up authentication between dm_fusa and Paymentech by generating a public key on the dm_fusa machine and copying it to the Paymentech server. To test payment processing with the Paymentech Simulator, also copy the public key to your Paymentech Simulator server.

To setup up authentication between dm_fusa and Paymentech:

  1. Generate an RSA public key.

    For example, this command generates an RSA public key with a key length of 4096 bits:

    ssh-keygen -t rsa -b 4096

  2. Copy the RSA public key to the Paymentech SFTP server:

    ssh-copy-id -i pathPublicKey  userName@hostNamePaymentech

    where:

    • pathPublicKey is the path and file name of the public key generated in step 1.

    • userName is name of the dm_fusa user.

    • hostNamePaymentech is the host name of the Paymentech SFTP server.

  3. Copy the RSA public key to the Paymetech Simulator server:

    ssh-copy-id -i pathPublicKey  userName@hostNameSimulator

    where hostNameSimulator is the host name of the Paymentech Simulator server.

  4. Verify the connection:

    sftp -i pathPublicKey  userName@hostName

    where hostName with the appropriate server host name (Paymentech or the Simulator).

Configuring Your SSH Client Configuration File

Connect dm_fusa to the Paymentech SFTP server by setting parameters such as server, port, algorithms, and ciphers in the SSH client configuration file, located at ~/.ssh/config.

On your dm_fusa machine, add entries to the SSH file to meet your business requirements. For example: 

Host CServer   
   HostName SftpHost      
   User UserName   
   Port PortNumber    
   IdentityFile pathPrivateKey  
   #KexAlgorithms kexAlgorithms    
   #Ciphers cipherNames  
   #HostKeyAlgorithms hostKeyAlgorithms  
   #MACs macAlgorithm  
   #LogLevel DEBUG3  
   #LogLevel VERBOSE

where:

  • sftpHost:Host name of the Paymentech's SFTP server.

  • userName: User name for accessing the Paymentech SFTP server.

  • portNumber: SFTP port number for the Paymentech server.

  • pathPublicKey: Path and file name of the private key that matches the public key you generated in "Setting Up Authentication Between dm_fusa and Paymentech".

  • kexAlgorithms: List of key exchange algorithms, in order of preference, separated by commas.

  • cipherNames: List of encryption algorithms for data transfer, separated by commas.

  • hostKeyAlgorithms: List of public key algorithms the SSH server uses to authenticate itself to the client, separated by commas.

  • macAlgorithm: List of MAC algorithms for data verification, separated by commas.

Sending Batch Payment Transactions Through SFTP

You can configure the Paymentech DM (dm_fusa) to send batch payment transactions to the Paymentech payment processor using SFTP. Batch payment transactions include batch payments, multiple verifications, multiple authorizations, deposits, and refunds. By default, dm_fusa uses TCP/IP for batch payment transactions.

To send batch payment transactions through SFTP:

  1. Open the Paymentech DM configuration file (BRM_home/sys/dm_fusa/pin.conf).

  2. Set the connection type between dm_fusa and Paymentech for batch payment transactions: 

    - dm_fusa batch_proto sftp

  3. If using SFTP for batch transactions, uncomment and configure the following entries:

    - dm_fusa sftp_host hostName
- dm_fusa sftp_pkey_pwd passPhrase
- dm_fusa sftp_indir inputPath
- dm_fusa sftp_outdir outputPath
- dm_fusa sftp_rfrfile rfrFileName
- dm_fusa sftp_proc_pat pattern
- dm_fusa sftp_retrys retryValue
- dm_fusa sftp_retry_interval intervalValue

    Table 2-2 describes the values to use with the pin.conf entries.

    Table 2-2 Variables for the pin.conf Entries

    Parameter Description

    hostName

    The host section name in the SSH client configuration file.

    passPhrase

    The SFTP private key passphrase. If omitted, the passphrase is retrieved from the wallet.

    inputPath

    The absolute path to the input directory where batch files are uploaded using SFTP.

    outputPath

    The absolute path to the output directory where response files are downloaded using SFTP.

    rfrFileName

    		 The name of the RFR file to retrieve from the output directory. If this parameter is not specified, dm_fusa downloads any unprocessed file found in remote output directory.

    pattern

    		 The extension appended to response files.

    retryValue

    		 The number of times to check for a response file in the remote output directory.

    intervalValue

    The time interval, in seconds, to check for a response or RFR file in the remote output directory.

  4. Save your changes.

  5. Stop and restart the Paymentech DM for the settings to take effect.

Using TCP/IP for Batch Payment Transactions

To send batch payment transactions through TCP/IP, follow these steps:

To connect dm_fusa to the Paymentech payment processor:

  1. Open the Paymentech DM configuration file (BRM_home/sys/dm_fusa/pin.conf).

  2. Enable or disable TLS connections from dm_fusa to Paymentech: 

    - dm_fusa fusa_tls_enabled 0|1

    where 0 disables TLS, and 1 enables TLS. The default is 1.

  3. Specify the connection type between dm_fusa and Paymentech for batch payment transactions: 

    - dm_fusa batch_proto socket

  4. Specify the Paymentech host name and port for batch payment transactions:

    - dm_fusa batch_srvr batchSrvr
- dm_fusa batch_port batchPort

    where batchSrvr and batchPort are the Paymentech TCP/IP server and port.

  5. Save your changes.

  6. Stop and restart the Paymentech DM for the settings to take effect.

Configuring Online Payment Transactions

You configure the Paymentech Data Manager (dm_fusa) to send online payment transactions to the Paymentech payment processor using TCP/IP. Online payment transactions include single authorization transactions and verification transactions.

To configure dm_fusa to send online payment transactions through TCP/IP, follow these steps:

  1. Open the Paymentech DM configuration file (BRM_home/sys/dm_fusa/pin.conf).

  2. Enable or disable TLS connections from dm_fusa to Paymentech: 

    - dm_fusa fusa_tls_enabled 0|1

    where 0 disables TLS, and 1 enables TLS. The default is 1.

  3. Specify the server status for online payment transactions:

    - dm_fusa online_proto socket|linkdown

    where socket specifies that the online server is running, and linkdown specifies that the online server is offline. The default is socket.

  4. Specify the Paymentech host name and port for online payment transactions:

    - dm_fusa online_srvr onlineSrvr
- dm_fusa online_port onlinePort

    where:

    • onlineSrvr is the IP address or host name of the Paymentech server for online payment transactions.

    • onlinePort is the port where Paymentech receives online payment transactions.

  5. Save your changes.

  6. Stop and restart the Paymentech DM for the settings to take effect.

Configuring Paymentech Processing Performance

Configure the following options:

To improve performance during account creation, see "Increasing Account Creation Speed When Paymentech Is Offline" in BRM Managing Customers.

Handling Concurrent Online Paymentech Requests

You can increase billing performance by using the fusamux program. Because Paymentech allows only a single connection per customer, the fusamux program takes multiple DM backends and bundles them into a single connection. This enables BRM to process multiple transactions and send them to Paymentech in a single connection.

Without fusamux, the Paymentech DM connects directly to Paymentech. When you use fusamux, the Paymentech DM connects to the fusamux application, which in turn connects to Paymentech. When you use fusamux, you must change entries in the Paymentech DM to point to fusamux instead of pointing to Paymentech.

To configure the fusamux daemon:

  1. Open the Paymentech DM configuration file (BRM_home/sys/dm_fusa/pin.conf).

  2. Edit the fusamux entries:

    • Set the fusamux online_port and fusamux online_srvr entries to point to the Paymentech online server IP address and port number.

    • Set the fusamux_port entry to the port on which the fusamux daemon listens.

    • Set the dm_fusa online_port entry to the port on which fusamux listens.

    • Set the dm_fusa online_srvr entry to point to the fusamux IP address.

    • Set the dm_fusa qm_n_be entry to a number between 4 and 8.

  3. Save the file.

  4. Stop and restart the Paymentech DM.

Setting the Connection Timeout Length and Retries

If you have problems connecting to Paymentech, increase the connection timeout length and number of retries:

  1. Open the Paymentech DM configuration file (BRM_home/sys/dm_fusa/pin.conf).

  2. Increase the number of times that dm_fusa retries a connection to Paymentech: 

    - dm_fusa connect_retrys value

    The default is 2, but you can enter any number.

  3. Change the amount of time, in seconds, that dm_fusa waits for a response from Paymentech for online authorizations: 

    - dm_fusa fusa_timeout value

    The default is 600.

  4. Change the amount of time, in seconds, that dm_fusa waits for a response from Paymentech for batch scripts: 

    - dm_fusa fusa_batch_timeout value

    The default is 600.

  5. Save the file.

  6. Stop and restart the Paymentech DM.

Monitoring the Paymentech Connection

The Paymentech HeartBeat application is a background process that checks the connectivity between BRM and Paymentech. When the Paymentech DM successfully connects to Paymentech, Paymentech acknowledges the connection by sending a HeartBeat message. The Paymentech DM responds by sending back a HeartBeat message to Paymentech.

If Paymentech does not receive a response message from BRM within 120 seconds of sending a request message, or if the response message is incorrect, Paymentech resets the connection to a listen state. BRM handles this as a socket disconnect and recovers accordingly. Errors are written to the BRM_home/sys/dm_fusa/dm_fusa.pinlog file.

Note:

If BRM stops receiving HeartBeat messages and is in the middle of a transaction, the connection does not disconnect.

To initialize the HeartBeat application, provide Paymentech with the IP address and port number of the machine running the Paymentech Data Manager (dm_fusa). The HeartBeat application runs automatically each time you process BRM-initiated payments.

The following entry is a typical HeartBeat request and response pair:

Received (20) chars: Heartbeat request [HO19999999813123258^M]
Sending Heartbeat response [HI19999999813123300^M]

If these entries are missing or are not continuous for the duration of the connection with Paymentech, work with Paymentech to troubleshoot why the connection was lost or the HeartBeat application was not enabled from their end.

Note:

If a connection is made between the DM and Paymentech, and Paymentech does not initiate the HeartBeat messages, BRM assumes there is no HeartBeat application support and continues with payment processing as normal.

If an error occurs with the HeartBeat application during payment simulation, an error message similar to the following is written to the BRM_home/apps/fusa_server/answer_s.pinlog file: 

Received (20) chars: Heartbeat response Validation failed in process_it() : HI19999999813123300^M

For this message to be logged, the payment processing simulator configuration file (BRM_home/apps/fusa_server/pin.conf) must contain the following entries: 

- answer_s loglevel 3
- answer_s logfile answer_s.pinlog

For more information, see "Testing Paymentech Credit Card Processing".

If a socket disconnect occurs with the payment processing simulator and no online transactions are occurring, errors similar to the following are written to the answer_s.pinlog file: 

E Tue Aug 08 10:51:24 2006  elm  dm_fusa:2994  qbe_fusa.c(1.13):645 1:elm:dm_fusa:2991:1:0:1155059471:0
Socket read error in dm_fusa_respond_heartbeat() recv() returned (0)
E Tue Aug 08 10:51:24 2006  elm  dm_fusa:2994  qm_back.c(7):299 1:elm:dm_fusa:2991:1:0:1155059471:0
Error(7) processing heartbeat monitor fd(5)