CONVERGE
Q: How do I know if I have a temporary or permanent demo account?
A: Demo accounts where the API user ID is webpage as opposed to apiuser###### are usually temporary accounts that need to be extended every 30 days at a time and are repurposed.
Q: When logging into the demo converge user interface I am being prompted for a passcode to reset the password, but I am not receiving the passcode.
A: First you will want to confirm with us what email is associated with the demo user ID. Once confirmed that your email is associated, if you still do not receive the passcode, try pressing on the resend passcode option.
Q: Why are many of my transactions declining in the demo environment?
A: In a Demo environment, only Elavon test cards can be used. There are pre-programmed responses (see attached file) which will vary based on the cent amount of the sale.
Q: Can I use live card numbers for testing?
A: Use of live cards is not permitted.
Q: The Elavon test cards get validated in live mode in production. The merchant doesn't charge their customers upfront, they just validate and save the credit card. This is a potential issue for them. Is there a setting that will prevent a test card from being accepted as valid?
A: If you are doing a CCGETTOKEN API call to tokenize the card, are you passing in ssl_verify set to Y? If you don’t, Converge wouldn’t validate the card, it will take whatever is given and pass back a token (ssl_token).
Q: Is it possible to implement Converge API integration (i.e. Lightbox) using ASP.NET in C#? The sample provided in the developer portal is in PHP.
A: While Elavon does not have ASP.net (C#) sample code available, The HTML/PHP sample code they provide shows the basic elements and formatting required to submit the payload to Elavon/Converge for processing the transaction. You can use that sample code as a basis to create your own ASP.net (C#) code.
Q: What are the endpoint websites for demo accounts and production accounts?
A: A full list and explanation of endpoints is available here. The differences between the demo and production URLS is the removal of "demo" for production endpoints.
Q: What transactions (txns) are supported in Converge?
A: Credit card, Debit Card, Cash, EBT (e.g. food stamps), Gift cart, Loyalty card, Card manager, End of day, Batch import, Account Administration, and Electronic Check.
Q: What fields are required for every transaction (txn) request?
A: While payment methods may vary, the below 5 fields are required for every transaction:
ssl_merchant_id - Elavon assigned Converge account ID **this is not the Elavon merchant ID
ssl_user_id - Elavon assined Converge User ID with API user status that can send transaction requests (must be associated with the terminal that will process the requests)
ssl_pin - unique 64 character alphanumeric Converge Terminal ID identifier that will process transaction requests (must be associated with the ssl_user_id sending the requests)
ssl_transaction - i.e. ccsale
ssl_amount - the sale amount
Q: What paramters must be included in every request during testing?
A: These 5 parameters must be included in every request to Converge
ssl_merchant_id - Elavon assigned Converge account ID **this is not the Elavon merchant ID
ssl_user_id - Elavon assined Converge User ID with API user status that can send transaction requests (must be associated with the terminal that will process the requests)
ssl_pin - unique 64 character alphanumeric Converge Terminal ID identifier that will process transaction requests (must be associated with the ssl_user_id sending the requests)
ssl_vendor_id - assigned by your solution engineer
ssl_partner_id - assigned by your solution engineer
Q: Are there any requirements when sending ecommerce transactions?
A: Whenever sending ecommerce transactions it is required to provide the invoice number. This value is passed back to the card issuer and provided to the cardholder on their monthly statement to identify the
transaction. Optionally you can pass a merchant transaction id value. It is kept throughout the duration of the transaction process and can be used as a unique identifier in payment processing reporting available to you.
Q: Can optional fields be added for identifying features?
A: Yes. There are options to include address, zip codes, etc...as well as other optional fields such as a description field.
Q: What happens if a credit card only has enough money on it to cover part of the transaction?
A: Depending if partial approval is enabled, the resulting message will come back as "partial approval" and there will be an additional field of "balance due." If partial approval is not enabled, the transaction will be rejected. By default, partial approval is not enabled.
Q: What does it mean if the response I receive is credentials supplied in the authorization request are invalid (error 4025)?
A: This can be due to an error in the API credentials (ssl_merchant_id, ssl_user_id, ssl_pin). You will want to double check you are using the right credentials and note these are case sensitive. Keep in mind ssl_merchant_id is the account ID and not the merchant ID. It is also possible there was a setting enabled erroneously (i.e. XML whitelist was setup)
Q: I am working on checkout.js and am not able to generate the session token, I am getting this error: The application has encountered an error, error code = 403
A: To successfully request a session token (ssl_txn_auth_token) for CheckoutJS, Lightbox or Hosted Payment Page we must whitelist the IP Address of the server you will post transactions from. For Lightbox integrations a URL address of the website also needs to be added to the HTTPS referrers list in order to populate the payment modal on the website.
The 403 error indicates there is a problem with the request. This would be that either you did not whitelist the IP/URL or the the what is whitelisted is incorrect. For example, in a Demo environment this would be the development server's IP and for boarded merchants in production, this would be production related servers/URLs.
You can perform a 'GET' request from your server to the following endpoint and contact us requesting us to add the IP to your IP Filter within the account..
https://www.convergepay.com/hosted-payments/myip
PHP GET Example:
<?php
$ch = curl_init("https://www.convergepay.com/hosted-payments/myip");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HEADER, 0);
$data = curl_exec($ch);
echo $data;
exit;
?>
Q: Does the referrer URL need to be provided in full or is domain name sufficient?
A: In our testing experience full URL is required. Domain may be sufficient if there is no subdomain (i.e. merchantname.mywebsite.com would not work by just providing mywebsite.com, but mywebsite.com/merchantname would work when providing mywebsite.com)
Q: What happens when there are too many invalid PIN attempts?
A: After 5 invalid attempts, the source IP address will be added to fraud IP list and any accounts that have that source IP will go into failure as they share the same source IP for the API users. In our example of this, one of the whitelisted IP addresses was not entered correctly on one merchant account resulting in the invalid attempt and thus the blacklist of the source IP, casuing the remaining merchant accounts with the same source IP to fail. If this occurs the source IP will need to be added to the global whitelist by Tier 2 software support in order to bypass the fraud API attempts error.
Q: Why are we receiving the following message: The field Address1 (ssl_avs_address) required but not supplied in the authorization request
A: This would occur when there are AVS fields set to required. Once de-selected in the payment field settings you will no longer encounter this error.
** Note: It is best practice for security to require address verification as card brands enhance their security measures and may make it mandatory in the future.
Q: I am trying to use a token to process a new transaction, why did it fail?
ssl_transaction_type=ccsale&
ssl_amount=15.34
ssl_token=1234567
A: To add a card to the card manager (token vault) to use in future transactions, the first transaction must
include: ssl_add_token=Y
Q: Are there any specific common practices to keep in mind for Converge API (i.e. Lightbox)?
A: A common practice for processing sales is to tokenize the card (ssl_token) upfront, via Lightbox, and then reference the token (ssl_token) to process as a sale via the XML API through a server to server call.
For processing refunds, it is recommended to utilize "linked refunds" so that you issue money back to the original card used for payment.
Q: It looks like XML API requires the data to be posted form encoded. With remote APIs that accept
XML/JSON we've used "application/xml" or "application/text" for instance and sent the XML as-is
rather than having to encode all the text for a form post. Is this possible or is form post the only
method to transmit the transaction?
A: XML API does require the data to be encoded. You should be able to send the XML data as is if you set the Content-Type to “application/x-www-form-urlencoded”.
Q: For installment transactions what is the difference between ssl_payment_number and
ssl_payment_count?
A: Payment count is the total number of installments due. Payment number is the installment sequence count. Payment number must be smaller or equal to payment count (i.e if payment number is 17 and payment count is 20 this would mean this is the 17th payment our of 20).
Q: Re: Amex card acceptance. There is a space for 3 digits only in the CVV field. Is that something that needs to be changed on our side?
A: Converge doesn't show a character limit on the CVV field, so it may be a limitation within your solution.
Q: Is it possible to whitelist based on a whildcard? ie. *.appname.com/api/elavon/exportscript?
A: There is no ability to add the URL using a wildcard.
Q: What data is returned with export scripts?
A: Export Scripts will return the batch summary information which will contain the number and amounts of the payments that were settled.
Q: What time zone is the settlement time / date that is returned in export scripts?
A: The settlement date / time returned is Eastern regardless of the time zone the terminal is setup in. However, the authorization date / time for each transaction will be set in the time zone that the terminal is setup in.
Q: What transactions are included at settlement?
A: The terminal will settle payments for the previous 24 hours. For example, if the terminal is set to auto settle at 12AM, payments between 12:00:00AM and 11:59:59 PM the previous day will be settled.
Q: What is the last component for the date format that is being used for Settled_Date? What time zone is being used and is it affected by daylight savings?
A: The final piece is milliseconds. The time is in Eastern time and the process does follow daylight savings time rules.
Q: Is "Enable Export Script" available in demo accounts, and if so, why aren't we getting posts from it?
A: This feature is available in the DEMO environment. It may be possible that it is a proxy issue and the URL needs to be whitelisted on the backend (added to proxy server).
Q: Does export script send response for settlement only or for all payment requests?
A: Under the specific terminal settings within the Converge User interface (UI), you can list one URL for approval, decline and error transactions. It can be the same URL for each or different one for each depending on how you wish to setup to receive the responses. There is also a flag that can be enabled to only send the settlement response and not include a response as each payment request is received.
Q: I am getting this error, what can be the issue? "javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to
requested target"
A: All three URL values (approval, decline, error) have to be added to receive settlements export scripts.
Q: What IP addresses need to be whitelisted to allow traffic for responses to be returned to our server?
A: Export Script IP Addresses:
62.17.112.80 to 62.17.112.95 (62.17.112.80 /28)
62.134.193.208 to 62.134.193.223 (62.134.193.208 /28)
65.201.175.80 to 65.201.175.95 (65.201.175.80 /28)
204.137.47.32 to 204.137.47.47 (204.137.47.32 /28)
Sometimes partners are not able to receive the responses successfully unless their export script URL is added to the Elavon proxy server. If this is the case, please reach out to Cartis Support to put in this request.
Q: Once I receive the Export Script settlement response, how do I know what transactions are in that batch?
A: The export script settlement response will provide the batch number, settlement date and time. You can then send a transaction query (txnquery) for that specific twenty-four-hour time period to retrieve the settled transactions for the day. Functionality has been added to include the batch ID in the transaction query.
Q: What alternative is there for getting settlement information for our downstream merchants?
A: You can send a transaction query (TXNQUERY) for the previous day based on timeframe that the transactions would have been processed within the settlement time. Then filter anything in the response that has ssl_trans_status of STL. This should match the payments that were settled that day. The TXNQUERY now returns the batch ID, GBOK and token value in the API response, allowing you to add a filter parameter of the GBOK number (Batch ID).
Q: What timeframe is a transaction query in?
A: A transaction query is in the terminal's (or your merchant's) time zone.
Q: What are the components of a GBOK number.
A: The GBOK is comprised of the following GBOK BBBMMDDHHMM
GB = good batch, settlement received OK
BBB = batch number 001 through 999
MMDD = month and day of settlement
HHMM = time of settlement
Q: We are getting a response error method not allowed, with error message Unfortunately our payment gateway is down right now. Please try again in a few minutes, or contact support for assistance.
A: Support for GET method has been depreciated for process.do and processXML.do and should not be used to post transaction requests to Converge, the final shutdown is August 1, 2022. Since GET method requests include all required data in the URL, they are at risk of exposing secure data and API code should be amended to stop using the GET method.
Q: Upon sending a transaction to Converge through the Magento Plugin, we receive a blank response/null response and a status 400 error code.
A: Magento Plugin was developed against Converge’s legacy/classic API, so the GateWay Url must reflect the appropriate endpoint of https://api.convergepay.com/VirtualMerchant/process.do
GENERAL
Q:What can you not store as part of your software application?
A: Full card numbers, expiration dates, social security numbers, track data, CVV2 data should not be stored.
Q: Is there a way to code an e-gift card program?
A: While we do not currently offer e-gift program, there are some workarounds possible but require you to write the whole program from scratch. You would need to write a database program for your software which will still be tied to our physical gift cards that the merchant would order. While the physical gift card does not need to be given out, the numbers can be passed through API. When cards are ordered they are input into the custom database and assigned to unactivated pool of cards. When a customer buys a gift card online, the database would select a gift card and pass it to Converge's API to activate it and would move that number from the unactivated pool to a specific customer profile. When that customer later chooses to pay with their gift card, the shopping cart would take the gift card number and balance and send it via API for redemption, then update balance in the customer's profile.