Billing and Invoicing Integration Guide
Credit Card Transactions
The Credit Card message format is for whole track, Track I or Track II magnetic stripe read credit card data, or key-entered credit card data available for all supported market segments. Magnetic stripe data cannot be sent in the Mail Order/Telephone Order, eCommerce environments, or for recurring transactions.
Card On File Transaction
A Card On File transaction is a transaction where a cardholder authorizes a merchant to store his payment details and process any outstanding payments with his card. A cardholder can initiate one of these transactions or it can be a recurring transaction.
Card On File Transaction Requirements
Every transaction authorized by Converge will return two new variables associated with Card On File transactions.
You must store these with the payment details from the transaction to make future Card On File transactions.
For all future Card On File transactions using Token or Card Number, you must include these fields in the transaction request.
You must pass one of the following fields:
Track data in
ssl_track_datafor swiped or Contactless (MSD) transactions.
The encrypted track data for swiped or Contactless transactions:
Track 1 data in the
Track 2 data in the
ssl_encrypted_track2_datafield, extracted from the Magtek readers. (Refer to the Encryption section for more information.)
All Track data in the
ssl_enc_track_datafield captured from the Ingenico device (3DES DUKPT encryption). (Refer to the Encryption section for more information.)
The card number in the
ssl_card_numberfor hand keyed transactions.
The token in the
ssl_tokenfrom a previously tokenized card number, the expiration date and AVS data is not needed if token is stored in Card Manager.
Indicates that the track data was extracted from a Contactless device when consumers wave or tap their cards or phones (Example: ApplePay), the integrated application must pass the Contactless Indicator in the
ssl_pos_mode of 03 (proximity capable) and
ssl_entry_mode of 04 (proximity read). Those values default to swiped when track data is sent alone.
An integrated application should pass the Address Verification Service (AVS) data on hand key transactions to qualify for better rates by using the Address Verification Service (AVS). AVS captures ZIP codes and the cardholder‘s billing address. AVS information is compared to the cardholder‘s ZIP code and address that the card issuer has on file. Address and ZIP code mismatches help the merchant to decide whether or not to complete the transaction. Refer to the AVS Response Codes section for complete list of AVS Response Codes.
An integrated application should pass the Card Verification Value (CVV) on hand key transactions for fraud protection. The CVV field can be set as optional or required based on the merchant’s business needs. When CVV data is passed, it is compared to the cardholder‘s CVV data that the card issuer has on file, a CVV Response Code is then returned. Refer to the CVV2/CVC2 Response Codes section for complete list of CVV2/CVC2 Response Codes.
If the CVV value is set to required:
A valid CVV value must be passed along with a CVV indicator of present (1) at the time of the authorization.
If a CVV value isn't passed, Converge will default the indicator to present if no indicator is passed and a CVV value is present.
If the CVV value is set to optional:
A CVV value along with the appropriate CVV indicator may be passed to indicate if the CVV is present, bypassed, illegible or not present.
The Converge application will set the indicator to present (1) if the CVV value is passed or Bypassed (0) if the CVV value is not passed at the time of the authorization.
You can set up set up recurring or installment payments in the system for all market segments. There are a few things to keep in mind when setting up a recurring or installment payment:
Recurring transactions will run indefinitely, unless suspended by the user.
Installment transactions will run until the number of installments specified is reached.
No track, Track I, or Track II magnetic stripe reads are allowed when setting up recurring payments for credit cards.
CVV data cannot be passed, as it should not be stored in the system.
You can pass tips on Service market segment at the time of the authorization Cashier-based processing or after authorization Server-based processing. Optionally a server ID and shift ID can be passed as well.
On the initial transaction, the tip amount must be sent along with the transaction amount. The authorization amount is now the total amount, which is recalculated using the authorization amount originally sent and the new tip provided. The settlement amount will reflect the new authorized amount.
Authorization Amount = Amount + Tip Amount
Settlement Amount = Authorization Amount
After the initial transaction, the tip amount must be sent without the transaction amount. The authorization amount will not change. However, the total amount is recalculated using the original authorized amount and the new tip provided. The settlement amount will reflect the new total amount.
Settlement Amount = Authorization Amount + Tip Amount
The tip amount can be sent in the merchant or the cardholder currency
EMV based transactions handle tips differently. Refer to the EMV Credit/Debit Card Transactions sections for more information.
Doing Business As (DBA)
The Dynamic Doing Business As (DBA) provides merchants the ability to control the descriptor on their customer's credit card statements. It allows the merchant to specify, on a per-transaction basis, wording that may be more recognizable or more service-specific to the customer than their usual business name preventing chargebacks. As an example, if the merchant sells magazine subscriptions for multiple publications, they may prefer to include the name of the publication in the authorization: MANYMAG*BAKERS MONTHLY or MANYMAG*CAR DIGEST.
DBA is up to 25 characters constructed in the following format:
- Constant/prefix (3, 7, or 12 fixed alphanumeric value) configured in the terminal with asterisks (*) delimiter.
- DBA name passed by the application. The maximum allowable length of the DBA Name variable provided by the merchant can be 12, 17, or 21 based on the length setup for the constant.
Converge supports the ability to capture and send travel information regarding departure and completion dates. The travel information dates are sent to the Merchant Airline Risk Monitoring System (MARMS). MARMS is a tool used to monitor risk associated with merchants that collect or accept payments for future services or bookings made well in advance of the actual date of use. Both dates must be sent together and cannot be in past.