eCommerce FAQ

Document created by gjsissons on May 10, 2016Last modified by bfinn on Jan 4, 2019
Version 10Show Document
  • View in full screen mode

This eCommerce page provides links to documents discussing topics  ranging from complex online payments to simple methods for connecting shopping carts, or adding disruptive technology to your online stores. Use the links below to look at code examples and learn about the Vantiv, now Worldpay eComm APIs. This includes links to download our comprehensive SDKs for PHP, Java, .NET, Python, and Ruby, as well as to the our Sandbox environment where you can experiment with the various transaction types.


Additionally, you can find answers to many general questions about transaction, merchant accounts, integrations, compliance and Value Added Services, such as eProtect, Recovery, Tokenization, and Fraud Protection.


If you have additional questions, please visit the eCommerce Community page at, or pose your question to one of our eCommerce experts here:






Who is Vantiv?

Vantiv, Inc. is a leading provider of fully integrated PCI-DSS compliant payment processing solutions for merchants and software providers.  For 40 years, our team of committed professionals has made us one of the most trusted and respected organizations in the payment processing industry.


General payments


What is an Authorization?

An authorization is the process of verifying that the credit card has sufficient funds (credit) available to cover the amount of the transaction. An authorization is obtained for every sale, and places a “hold” on the cardholder’s credit line for the amount of the transaction.


What is a chargeback?

A chargeback is when a credit card transaction is billed back to the merchant after a sale has been settled. Chargebacks are initiated by the card issuer on behalf of the cardholder. Typical cardholder disputes involve product delivery failure or product/service dissatisfaction. The merchant’s acquiring bank will charge the merchant a fee for the retrieval of information, and if it is determined that the chargeback is valid, there will be another fee for the chargeback itself.

The customer will be refunded their money directly through the credit card company and the merchant’s business checking account will be debited for the amount in dispute.


What are Dues & Assessments?

Dues & Assessments are processing fees merchants pay to the Card Associations. They are a set percentage of the sale and are generally collected on a daily or monthly basis.



What is the Durbin Amendment?

The Durbin Amendment is a component of the Dodd-Frank Wall Street Reform and Protection Act sponsored by Senator Richard Durbin (D-Ill.). The Amendment was successfully passed to cap debit card fees for merchants.

The final ruling on debit interchanges implements a base fee cap of $.21 with an allowance of $.05 to account for fraud protection costs.



How long does it take to receive funds once a transaction has been processed?

Funds are deposited directly into your business checking account (via ACH) typically within 48-72 hours.





When would you use a Reversal versus a Return?

A Reversal transaction should be used to “un-do” a specific transaction in the current batch, making the funds available on the card. (Transactions may not be reversed after a batch closes). A Return transaction is not tied to a previous transaction and is used to credit a specific amount to a card.



What types of Reversal transactions are supported?

Merchant initiated reversals and merchant initiated timeout reversals are supported.  Merchant initiated reversals are cancellation requests sent by the merchant when a valid a transaction response is received from the host on a previous transaction.

Timeout reversals are cancellation requests sent by the merchant when a transaction response was not received from the host on a previous transaction.

Partial reversals (reversing a portion of the original transaction) are supported for authorizations in the MOTO and eCommerce industries.



Can merchants refund a transaction for more than the amount of the deposit?

Yes. By default merchants are allowed to refund a transaction for more than the amount of the deposit. The ability to limit refunds is an option that must be requested per merchant ID (MID).



Which transaction ID should I use in the XML for a Deposit/Refund?

For a Deposit transaction, use the transaction ID returned in the corresponding Auth response. For a Refund, use the transaction ID returned in the corresponding Deposit transaction.


Do you reject Auths based on address mismatches?

No. We return the responses from the card networks and they do not reject Auths based on address. We recommend that you review the Auth responses for address mismatches to determine if you would like to proceed with a deposit. Proceeding with a transaction with an incorrect address puts the merchant at risk and is not recommended.



Can I Capture an Authorization more than once?

While the system will not prevent the capture of an Authorization multiple times best practice is to only capture an Authorization once. Capturing an Authorization is done by calling the AuthorizationCompletion operation. Note that capturing an Authorization more than once could have an interchange impact.


Do I need to add optional fields to my request?

No. Although many of the optional fields are pre-populated with a default value, providing additional information may improve interchange qualification.



Do I need an OrderSource on every Auth?

Yes. The OrderSource Element is required for Auth transactions. For website sales, eCommerce is the most common orderSource value. Other valid values are 3dsAuthenticated, 3dsAttempted, echeckppd, installment, mailorder, recurring, retail, telephone, recurrringtel, applepay.



What changes are needed to send foreign currency?

You will need a new MID for the foreign currency, but the XML messages do not change. The new MID is set-up to accept the specified currency. You need to make sure you send the correct MID when submitting the transaction.



Are there any countries for which you do not support credit cards?

We allow you to accept credit cards from any country. We do have features such as International Card Filtering and Issuer Country Indicator, which can filter out international cards or inform you of which country issued the card.



How quickly can you process transactions in a batch?

A batch of about 10,000 transactions usually would take about 10 minutes to process, although times will vary depending on a number of factors including transaction volumes, server performance and bandwidth characteristics.


Where can I find a sample of your XML for what we should send and what we will receive?

You can find sample XML in the XML Reference Guide. If you do not have our XML Reference Guide, either ask your Sales Representative, Implementation Consultant, or Customer Experience Manager for a copy of the most recent XML Reference Guide. The XML guide is also available on the Vantiv One website for developers.


What is the Billing Descriptor Prefix?

The billing descriptor prefix is a Visa requirement that helps end customers understand the charges on their statement. The prefix can be three or seven characters and must be followed by an asterisk. After the prefix there is your usual billing descriptor. For example - ABC*ABC SALES CORP



What is the difference between online and batch?

Online is considered "real-time," while batch transactions are sent as a group at the end of the day. Vantiv’s eCommerce platform supports both batch and online operations although there are some differences in the types of transactions supported.



Difference between $0 and $X Auths?

Auths confirm that a cardholder has sufficient credit available to cover a particular transaction. A $0 Auth confirms the card number exists, but does not prove that funds are available on the account. Not all card networks support $0 Auths.



Can I change my address?

You can, but if you settle in USD, you must have both a U.S. address and a U.S. bank account.


Can I send any Billing Descriptor I want?

This depends on the risk assessment that was completed as part of the merchant onboarding process. Ask the assigned Customer Experience Manager at Vantiv to confirm this for you. Some merchants may be eligible for unrestricted descriptors, while others may have a more limited list they can choose from (depending on business need).



What is the purpose of the Max Transaction Amount?

Vantiv will flag any transaction sent to us that is equal to or great than the amount you specify for the Max Transaction Amount. The Vantiv Customer Experience Manager will reach out to the merchant to confirm whether or not they want to process the transaction in question. It is mainly used to prevent system errors (processing a transaction with an extra zero, for example).


What is the difference between Prepaid filtering and Prepaid Indicator?

The filter will automatically decline transactions based on whether or not the card is a pre-paid/reloadable card. The indicator returns information in the response message to let you know the card is pre-paid, but does not make any determination beyond that (other than the result of the transaction request).



Who do I contact for questions about chargebacks?

Merchants should contact their Customer Experience Manager for questions related to processing. They will be able to provide further information.






What information do I need to connect to Vantiv?

If you are connecting directly: Merchant ID, Login, Password, and Transaction URL. If you are connecting via a third party presenter: Merchant ID. If you are connecting via Terminal ID, Bank ID, and Platform.



When does a merchant receive their merchant account number?

In order for us to send out merchant-specific connection information, the merchant must complete all requirements of the on-boarding process. This includes the profile setup (with Vantiv Implementations), the compliance review with our Compliance team, and the risk assessment with our Risk team.



Why has my certification account stopped working?

In order to maintain the health and validity of the test environment we periodically wipe all data and rebuild with the latest configuration. While we do take steps to preserve and restore profiles, sometimes unforeseen circumstances require manual intervention for your connection to work. Please contact your Account Manager for more information.


How long does it take to integrate with you?

Integration with us is specific to each Merchant and depends on is how fast you are able to update your internal systems. Your Vantiv Implementation Consultant can certify any transactions you send in a timely manner.



How do I get a test account set up with you?

If you are integrating via our SDKs or coding to our XML spec, in order to establish a test account in our Sandbox Environment simply you can follow the link to our Sandbox



I would like to integrate with your platform, but will not be able to code directly. How can I still integrate with Vantiv?

We are integrated with many different partners and gateways. If you currently work with one or plan to, you can check with either your Sales Representative or Implementation Consultant to ensure we are integrated with them.



Can I use a non-static IP to connect to your platform?

We only require a static IP for Batch transaction processing. Online transactions do not require a static IP address.


We would like to code directly to your platform, but would like to go live as soon as possible. Can we go live using a gateway or presenter to start, and then code direct at a later point?

Yes. You can begin processing through a gateway or presenter to start, and then code directly to us while you are processing live transactions.



After I am live, if I decide to add another Merchant Division, do I need to re-certify or do any other testing?

Once you have completed the certification process, you will only need to certify for new transaction types, or in some cases, to take advantage of new Value Added Services or features. For example if you have tested and certified for Authorizations, Captures, Refunds, and Voids, you can add a new division without re-certifying for those transactions. If you wanted to add in Conditional Deposits, you will need to test and certify for that transaction type.



How long is a licenseid valid for?

A licenseid is valid for 365 days from the time it was issued. Note that your application will not be able to authenticate against the API if the licenseid has expired and thus cannot submit any transactions to be processed.



How do we test tokens?

It is recommended best-practice that you test normal transactions first to confirm connectivity before adding tokenization logic.


How do I register for Account Updater?

We will assist you in Account Updated (AU) registration. Please contact your Customer Experience Manager or Implementation Consultant to get started. Once registration is completed (depending on the card networks this could take anywhere from 1-6 weeks) we will enable this feature for you.



What do I send for OrderId?

This element should represent some methodology that will allow you to track the order in your system. There is no right or wrong answer to this, but it should be unique enough to identify each order.



What countries support AVS checking?

Only US, Canada, and Great Britain at this time.



What if I only have a few one-off transactions I want to process outside of my gateway or direct connection?

We offer you Virtual Terminal functionality in Vantiv iQ allowing you to enter transactions manually.



What currencies can you support?

We can support customer purchasing in any currency, but you may only settle in USD, AUD, GBP, JPY, Euro, CAD, and HKD.


I am starting out connecting via a gateway, but I may be switching. Can I do that?

You will always be able to change presenters or connection methods in the future. Please contact your CEM to get this change started at least 3-4 weeks in advance of any switchover.


What is the purpose of the id XML Element?

The purpose of the id element is to prevent duplicate transactions from being processed. For online transactions, the system compares transaction type, the id attribute from the request, and the credit card number against other online transactions processed within the previous two days. The id element should be unique enough to catch duplicate transactions.


My transactions are failing on the test environment, how do I fix this?

Please send the XML to your Implementation Consultant and they will help determine the problem. If you have not been working with anyone contact your Customer Experience Manager for the next steps you should take.

I am getting an error saying "System Error - Call Litle & Co"?

First, ensure you are using the correct username and password. Your password for the test environment should begin with 'cert'. If that information is correct, confirm you are using the correct Merchant ID supplied by your Implementation Consultant. If you are still receiving the error, please contact your Implementation Consultant.


What transactions require certification testing?

We ask merchants to test and certify for any transactions they plan on potentially running in production. Typical transactions are Authorizations, Captures, Refunds, and Voids.



Can I use customBilling for the transactions I am sending?

Custom Billing is an option merchants have when sending transactions. This allows merchants to specify exactly what will show up on their customer's credit card statements. In order to use this, our Risk Department must approve the request. Please work either with your Sales Representative, Implementation Consultant, or Customer Experience Manager to initiate the process.



What is the difference between Conditional Deposits and Authorization/Capture transactions?

A Conditional Deposit is a single transaction that groups an Authorization and a Capture together. If the Auth approves, the Capture takes place. Conditional Deposits do not fail if address or CVV does not match. An Authorization and Capture are two separate transactions. First you submit the Authorization and based on the response, submit a Capture against the approved Authorization.


Are the XML elements case sensitive?

Yes, the XML Elements are case sensitive. The XML Reference Guide provides information about all transactions and elements.


How do we test AVS or CVV check transactions?

Please refer to Chapter 2 of the XML Reference Guide for required and optional certification test. You can test most of the AVS and CVV results using these tests. To find a list of AVS Response Codes and Card Validation Response Codes and their meanings please refer to Appendix A of the XML Reference Guide.



Can I use real credit cards in your certification environment?

You should use the credit cards in the XML Reference Guide to send test transactions. While our certification environment is not connected to the Credit Card Networks use of real card numbers in the test environment may be a violation of Network regulation.



What value should I send for the reportGroup XML Element?

The reportGroup element defines the grouping of transactions appear in Vantiv iQ. Determine your Reporting Groups based upon how you want to segment the transactions in iQ. For example, you could create Reporting Groups based upon product line or individual products.  Please ask your Implementation Consultant or CEM for additional information.


Where can I find test card data?

All tests detailed in Chapter 2 of the Vantiv eCommerce XML Reference Guide use test cards. Also, Appendix C contains a consolidated list of the test cards used in the document.


We are planning on utilizing a Partner or Gateway to connect to your platform, do we still need to test?

If you use a partner or gateway that is already directly integrated with Vantiv, you are not required to complete any formal certification testing with us but the gateway provider will likely have their own test requirements. If you use a partner or gateway that is not integrated with Vantiv, they must perform certification testing with us before they can connect to our network.


Do I have to use the test card data provided?

The test system will approve any credit card number that passes the credit card standard MOD 10 validation check. If you want to receive decline codes, you must use the credit card numbers located in Chapter 2 of the Vantiv eCommerce XML Reference Guide. The orderId and amount values can be different if your system cannot pass the ones specified.



How long is the transactional test data available for?

Data retention in the Pre-Live Certification environment is limited to 30 days.


Are there transaction volume limitations in the test environment?

Each IP address connecting to the Certification environment receives three concurrent connections for real-time processing. A maximum of five IPs can be granted access to the certification environment. You can submit a maximum of 10,000 transactions in a batch file per day.



Does my test account expire?

Your test account does not expire; however, upon completion of the certification requirements, we move most merchants from the Pre-Live environment to the Post-Live environment. The Post-Live environment will continue to be available for any ongoing testing you wish to perform, such as regression testing.


Merchant Accounts



Can merchants use someone else’s merchant account to run transactions?

No, this practice is known as "credit card laundering." It is against the Visa and MasterCard agreements. Using someone else's merchant account to process credit card transactions can lead to fines and other penalties. In addition, this will put the merchant's credit card processing account in jeopardy.



How long does it take for a merchant to get their funds?

Merchants can refer to section 1 of their contract with Vantiv for the funds transfer timeline.




What is PCI-DSS?

This is an acronym for the Payment Card Industry Data Security Standard. PCI DSS is a set of security standards that were created by the major credit card companies (American Express, Discover Financial Services, JCB, MasterCard Worldwide, and Visa International) to protect their customers from identity theft and security breaches. Under the PCI DSS, a business or organization should be able to assure their customers that its credit card data/account information and transaction information is safe from hackers or any malicious system intrusion. There are 12 key requirements to achieving PCI DSS compliance. Additional information may be found here:


What is PA-DSS?

This is an acronym for the Payment Application Data Security Standard. PA-DSS is a set of security standards created by the PCI Security Standards Council for software developers and integrators of applications that store, process or transmit payment cardholder data as part of authorization or settlement. To stay in scope of PA-DSS, software vendors must undergo the process of validating their application or applications. There are 14 key requirements to achieving PA-DSS compliance. Additional information may be found here:


What is Tokenization?

Tokenization works by moving actual cardholder data offsite to a PCI DSS compliant storage facility. Vantiv's Tokenization service works to create and then return a unique token to the software application. The token may than be used to submit transactions without sensitive payment data.





What is eProtect?

eProtect is a security solution that helps reduce PCI scope by eliminating the need or your application to handle sensitive card holder data. It does this by using an iFrame and Javascript code served by Vantiv to securely exchange sensitive card data for a low value token at the point of capture. eProtect was formerly known as PayPage, and much of the technical documentation still uses the term PayPage to describe this functionality.

eProtect is independent of how payment transactions are coded, however Vantiv’s eCommerce systems accept an eProtect generated token as a secure alternative to actual card data. eProtect can be used to help secure eCommerce or mobile applications regardless of the method of integration (SDK or XML)



When trying to test for PayPage I am receiving a message: "We are experiencing technical difficulties. Please try again later or call 555-555-1212 (timeout)". What should I do?

When creating the PayPage JavaScript make sure to check your line that says:

sendToLitle(litleRequest, formFields, submitAfterLitle, onErrorAfterLitle, timeoutOnLitle, 5000);

Make sure the timeout limit is set to a number that is appropriate, for example 5000 milliseconds.



Can eProtect be used without the Vault?

No, eProtect / PayPage extends the functionality of Vault.



Does a paypageRegistrationId expire?

The paypageRegistrationId is only valid for 24 hours. You must submit the paypageRegistrationId with 24 hours of receiving it to obtain the token.



How many paypageId values are needed?

Each merchant account will have its own unique paypageId to be used in the PayPage request.



Is certification required for eProtect?

Yes, please refer to the eProtect Integration Guide for information about the required certification.



Is JavaScript required?

It depends upon which method you select to implement eProtect. If the eProtect Javascript codes runs locally on your browser, JavaScript support is required. If the code executes in an iFrame served from Vantiv, JavaScript support is not required on the client browser.



Is there a sample site to review?

We created a few simple sample pages to demonstrate how the code is used and executed: Example checkout page showing all inputs and outputs:


Checkout Page without PayPage:


Checkout Page with PayPage (will submit primary account number if PayPage encounters an error):


Checkout Page with PayPage (will never submit primary account number):




If I am tokenized and billing my customers monthly, how will I show them what credit card I am using to bill them?

The tokens last four digits is the same as the credit cards last four digits and therefore you can show the last four digits of the token for your customers to identify their card.



Is there any way to detokenize a card once it's been tokenized?

With the proper permissions, you can view the actual card number in Vantiv iQ. Also, there is an option of a bulk extraction if you would like a large number of tokens detokenized.


Does the expiration date need to be sent with a token?

You must submit the expiration date with a token. We only tokenize the card number. The token does not include the expiration date or card validation number. When the card expires you can simply send in the new expiration date without replacing the token.


Do tokens expire?

The token does not expire. It can be used until the cardholder changes the account number.



Can tokens be entered or returned in the Virtual Terminal?

Currently the Virtual Terminal does not support the use of tokens.



Does Auto Account Updater work with the Vault?

Vault works in conjunction with the Recovery product, which includes Automatic Account Updater. If you are receiving updated information in your response and the account number changes, you will receive a new token in your response.



Is eProtect required if using the Vault?

eProtect is not required when using the Vault. eProtect extends the Vault functionality so that credit card numbers never touch a merchant’s system.


Is there a way to determine if the number is a token or a credit card?

The token is created using a Mod 10 +1 algorithm. The credit cards use the industry standard mod 10 algorithm. We recommend that all values are validated for the industry standard Mod 10 algorithm.


What is the format of the token for a credit card?

(Note: This answer applies to the standard Vantiv eComm token. OmniTokens have several formats available.) For credit cards, in an effort to minimize development requirements on the merchant side, we have elected to use a format-preserving tokenization scheme. In simple terms this means that the length of the original card number is reflected in the token, so a submitted 16-digit number results in a 16-digit token. Also, all tokens use only numeric characters, so you do not have to change your systems to accept alpha-numeric characters. The credit card token numbers themselves have two parts. The last four digits match the last four digits of the card number. The remaining digits (length can vary based upon original card number length) are a randomly generated. Unlike credit card numbers, which are Mod 10 compliant, tokens are Mod 10 + 1 compliant.



What is the format of the token for an echeck?

For an eCheck token, since the account number length can vary widely, we elected to make the tokens a uniform length of 17 digits. Unlike card tokens, the entire eCheck token number is a randomly generated. The system supplies the last three characters of the account number in a separate element. As with credit card tokens, eCheck tokens are Mod 10 + 1 compliant.


How are tokens charged?

You are only charged when a token is registered for the first time.





What is the format of the filename that contains the recycled responses?

The file name format is: merchantId.MMddyyyy.sessionId.response



What signature should be set if a merchant is also using Account Updater?

Signature 4: Order ID. You would use Order ID alone to avoid a change in card restarting the sequence.



What version of the Vantiv eCommerce XML do I need to use for the Recycling Engine?

You can be on any version of the Vantiv eCommerce XML to take advantage of the Recycling Engine, but to receive recycle specific responses; you will need to be on V8.6 or above.





What is the subject?

The subject links your PayPal API account to your account in our system. Without the subject, transactions cannot be processed.



Are funds guaranteed?

Funds are guaranteed for three days after an approved Authorization.


How do I void an order?

To void an order completely you must send the void direct to PayPal via an expressCheckOut call.

Why do capture transactions reject?

Captures can reject if something changes with the PayPal account after the authorization request has taken place. In the credit card world these rejects do not happen at the time of capture. They are rejected via a chargeback. With PayPal they are rejected at the time of capture.



What is the purpose of the orderComplete element?

Orders can stay open up to 360 days on a customer's PayPal account unless the amount is fully consumed. To close the order and release any remaining funds, send an orderComplete on the capture.



Do refunds always have to be linked to a capture?

A PayPal refund must always be linked to the original capture. We do not support an orphan refund for PayPal.



What is a billing agreement?

The billing agreement is a way for a recurring charge to be setup with a PayPal account.




Using PayFlow Pro as a gateway, can we perform transactions using Reference Transactions?

Not at this time.






What is POODLE and what does it have to do with SSLv3?

In October 2014, security researchers discovered and published a vulnerability known as POODLE (CVE-2014-3566), which affects the Secure Sockets Layer version 3 (SSLv3) protocol. This protocol is currently one of several encryption protocols supported by Vantiv eCommerce, but it can be exploited by a malicious party to extract sensitive information from secure traffic. Beginning January 9, 2015, Vantiv’s production servers will limit SSLv3 traffic and as of January 27, 2015, we will no longer accept any SSLv3 traffic. Only traffic using newer encryption protocols including TLS v1 and later will be accepted.



What SDK versions are affected by Vantiv no longer accepting SSLv3 traffic?

All versions of the 8.X PHP SDK prior to version 8.27.1, as well as version 9.0.0 are written to use only SSLv3 by default. These, along with the OpenCart versions prior to 8.24.1 and Magento prior to 8.15.2 extensions, are the only affected SDKs. PHP SDK versions 8.27.1 and 9.0.1 have been released that are written to use TLSv1.x as the encryption protocol. The required code change is simple to apply to your existing PHP SDK if you choose to make the code change yourself without upgrading to the latest SDK version.



Are the OpenCart and Magento Extensions affected?

Yes. Since both the OpenCart and Magento extensions include an embedded PHP SDK, the extensions for OpenCart versions prior to 8.24.1 and Magento versions prior to 8.15.2 are affected. OpenCart extension version 8.24.1 and Magento extension version 8.15.2 have been released that are written to use TLSv1.x as the encryption protocol. The required code change is also simple to apply to your existing OpenCart or Magento extension. If you choose to make the code change yourself without upgrading to the latest extension version, please see the "How do I correctly edit my PHP SDK to send TLS instead of SSLv3" question below for instructions on how to edit the PHP SDK embedded in OpenCart and Magento extensions to send TLS instead of SSLv3 traffic.



How do I correctly edit my PHP SDK to send TLS instead of SSLv3?

In the Communications.php module of your PHP SDK, find the line that sets CURLOPT_SSLVERSION to 3. By changing the value to 1 (use TLSv1), you will be able to ensure that your application will send TLS traffic to Vantiv.



How can I test my application usage to ensure my SDK version is not using SSLv3?

The Sandbox, as well as the Vantiv Pre-Live and Post-Live certification environments have been patched to disallow SSLv3

1 person found this helpful