Vantiv eCommerce Gateway Guide

Vantiv eCommerce fact sheet

Additional notes
Spreedly's integration with Vantiv Litle(CNP) uses API version 9.14 by default. A new gateway version is available for API version 12.49, please reach out to please contact Support at [email protected]
Vantiv Litle(CNP) flags duplicate transactions based on `order_id`. To avoid legitimate transactions being rejected, use a unique `order_id` for supported requests.

Quick start

New to integrating Vantiv Litle(CNP) with Spreedly? Follow this quick setup path.

Retrieve your Vantiv Litle(CNP) credentials
1. Contact FIS Global / Worldpay to obtain your user, password, and merchant_id.
2. Alternatively, request Partner-Presenter access and use merchant_id_only mode with only your Merchant ID.
Get familiar with the Spreedly API
1. Review Spreedly API basics.
2. Understand the core concepts: Gateways, Payment Methods, and Transactions.
Add a Vantiv Litle(CNP) gateway to Spreedly
1. Create separate gateways for each environment: Sandbox, Prelive, and Production.
2. Use sandbox: true for sandbox, or url_override: prelive for certification testing.

📘
Best practice: Create separate Spreedly gateways for each Vantiv Litle(CNP) environment rather than updating a single gateway repeatedly.

Adding a gateway

Authentication modes

Vantiv Litle(CNP) supports two gateway setup patterns in Spreedly.

Mode	When to use it	Required fields
`default`	Use your own Vantiv credentials	`user`, `password`, `merchant_id`
`merchant_id_only`	Use Spreedly Partner-Presenter credentials after Vantiv links your MID	`merchant_id`

Default auth mode

Use this mode when you authenticate with your own user, password, and merchant_id.

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>litle</gateway_type>
        <user>user</user>
        <password>password</password>
        <merchant_id>your_merchant_id</merchant_id>
      </gateway>'

<gateway>
  <token>5etkum2SDFfxKVdM3C2dc2gXYZ</token>
  <gateway_type>litle</gateway_type>
  <name>Vantiv eCommerce (formerly Litle)</name>
  <description nil="true"/>
  <merchant_profile_key nil="true"/>
  <sub_merchant_key nil="true"/>
  <user>user</user>
  <merchant_id>your_merchant_id</merchant_id>
  <characteristics>
    <supports_purchase type="boolean">true</supports_purchase>
    <supports_authorize type="boolean">true</supports_authorize>
    <supports_capture type="boolean">true</supports_capture>
    <supports_partial_capture type="boolean">true</supports_partial_capture>
    <supports_credit type="boolean">true</supports_credit>
    <supports_partial_credit type="boolean">true</supports_partial_credit>
    <supports_general_credit type="boolean">true</supports_general_credit>
    <supports_void type="boolean">true</supports_void>
    <supports_adjust type="boolean">false</supports_adjust>
    <supports_verify type="boolean">true</supports_verify>
    <supports_reference_purchase type="boolean">true</supports_reference_purchase>
    <supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
    <supports_3dsecure_2_mpi_purchase type="boolean">true</supports_3dsecure_2_mpi_purchase>
    <supports_3dsecure_2_mpi_authorize type="boolean">true</supports_3dsecure_2_mpi_authorize>
    <supports_store type="boolean">true</supports_store>
    <supports_remove type="boolean">false</supports_remove>
    <supports_fraud_review type="boolean">false</supports_fraud_review>
    <supports_network_tokenization type="boolean">true</supports_network_tokenization>
    <supports_transaction_retry type="boolean">true</supports_transaction_retry>
    <supports_stored_credentials type="boolean">true</supports_stored_credentials>
    <supports_partial_refund type="boolean">true</supports_partial_refund>
  </characteristics>
  <credentials>
    <credential>
      <name>user</name>
      <value>user</value>
    </credential>
    <credential>
      <name>merchant_id</name>
      <value>your_merchant_id</value>
    </credential>
  </credentials>
  <gateway_settings>
    <url_override nil="true"/>
    <legacy>false</legacy>
  </gateway_settings>
  <gateway_specific_fields>
    <gateway_specific_field>descriptor_name</gateway_specific_field>
    <gateway_specific_field>descriptor_phone</gateway_specific_field>
    <gateway_specific_field>order_source</gateway_specific_field>
    <gateway_specific_field>report_group</gateway_specific_field>
    <gateway_specific_field>customer_id</gateway_specific_field>
    <gateway_specific_field>debt_repayment</gateway_specific_field>
    <gateway_specific_field>cavv</gateway_specific_field>
    <gateway_specific_field>xid</gateway_specific_field>
    <gateway_specific_field>campaign</gateway_specific_field>
    <gateway_specific_field>merchant_grouping_id</gateway_specific_field>
    <gateway_specific_field>affiliate</gateway_specific_field>
    <gateway_specific_field>send_expiration_date_with_token</gateway_specific_field>
    <gateway_specific_field>stored_credential_initiator</gateway_specific_field>
    <gateway_specific_field>stored_credential_processing_type</gateway_specific_field>
    <gateway_specific_field>stored_credential_transaction_id</gateway_specific_field>
    <gateway_specific_field>fraud_filter_override</gateway_specific_field>
    <gateway_specific_field>level_2_data</gateway_specific_field>
    <gateway_specific_field>level_3_data</gateway_specific_field>
    <gateway_specific_field>custom_identifier</gateway_specific_field>
    <gateway_specific_field>sequence</gateway_specific_field>
    <gateway_specific_field>total_count</gateway_specific_field>
  </gateway_specific_fields>
  <payment_methods>
    <payment_method>credit_card</payment_method>
    <payment_method>third_party_token</payment_method>
    <payment_method>apple_pay</payment_method>
    <payment_method>google_pay</payment_method>
    <payment_method>bank_account</payment_method>
  </payment_methods>
  <state>retained</state>
  <redacted type="boolean">false</redacted>
  <sandbox type="boolean">false</sandbox>
  <mode>default</mode>
</gateway>

Merchant ID only mode

Spreedly maintains Partner-Presenter credentials with Vantiv Litle(CNP), certified for API version 9.14. Spreedly has separate credentials for Production and Prelive, and the correct set is selected based on the environment.

If you want to use this approach instead of your own user and password, ask Vantiv Litle(CNP) to connect your Merchant ID to Spreedly's Partner-Presenter credentials for each environment you plan to use. If you manage multiple MIDs, each MID must be connected separately.

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>litle</gateway_type>
        <mode>merchant_id_only</mode>
        <merchant_id>your_merchant_id</merchant_id>
      </gateway>'

For more background, see the Gateway user guide.

Core transaction behavior

Purchase

curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H "Content-Type: application/json" \
  -d '{
    "transaction": {
      "payment_method_token": "payment_method_token",
      "amount": 1000,
      "currency_code": "USD",
      "order_id": "unique-order-id-12345",
      "retain_on_success": true
    }
  }'

📘
Additional notes

Vantiv Litle(CNP) uses XML over HTTPS for all gateway API communication.

Amounts are sent in minor currency units.

order_id must be unique per transaction.

Verify performs a $0 authorization followed by a void.

Partial capture requires the sequence and total_count gateway specific fields on capture. Partial refund is also supported.

Reference purchase allows charging a previously authorized or stored reference. Third-party tokens use cnpToken or litleToken.

Store registers a card or bank account token through registerTokenRequest. Store is not supported for Apple Pay, Google Pay cryptogram, or network token cards.

General credit uses Vantiv credit and is limited to credit cards. It is not supported for Apple Pay, Google Pay cryptogram, or third-party tokens.

ACH refunds use echeckCredit and support custom_identifier on API version 12.

Remove is not supported through Spreedly for Vantiv Litle(CNP)-stored tokens.

Environment selection

The Vantiv eCommerce API supports multiple environments. Spreedly uses the sandbox flag and url_override setting to determine which endpoint is used.

Vantiv environment	Endpoint URL	`sandbox` setting	`url_override` setting
Sandbox	https://www.testvantivcnp.com/sandbox/communicator/online	`true`	Empty or omitted
Prelive	https://payments.vantivprelive.com/vap/communicator/online	Ignored	`prelive`
Postlive	https://payments.vantivpostlive.com/vap/communicator/online	Ignored	`postlive`
Production	https://payments.vantivcnp.com/vap/communicator/online	`false`, empty, or omitted	Empty or omitted

If url_override is provided, the sandbox flag is ignored. Sending neither setting creates a Production gateway.

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>litle</gateway_type>
        <url_override>prelive</url_override>
        <mode>merchant_id_only</mode>
        <merchant_id>your_merchant_id</merchant_id>
      </gateway>'

Advanced features

Network tokenization

Vantiv supports Apple Pay, Google Pay, and other network token flows through Spreedly's network tokenization framework.

Payment method	Vantiv `orderSource`
Apple Pay	`applepay`
Google Pay	`androidpay`
Network token (card)	`ecommerce`

Spreedly's stored credentials framework also supports Apple Pay and Google Pay network tokens for later off-session use.

3D Secure

📘
Limitation: Vantiv does not support Spreedly 3DS2 Global.

3D Secure data can still be sent using gateway specific fields cavv and xid, or through Spreedly's three_ds object. For 3DS transactions to succeed, also send order_source with either 3dsAuthenticated or 3dsAttempted.

Stored credentials

Vantiv supports two ways to send stored credential information:

Spreedly first-class support using stored_credential_initiator and stored_credential_reason_type
Gateway specific fields using stored_credential_initiator, stored_credential_processing_type, and stored_credential_transaction_id

Recommended: use Spreedly first-class support unless you need fine-grained gateway control.

First or credential-on-file setup (CIT)

reason_type	initiator	Vantiv `processingType`
`unscheduled`	`cardholder`	`initialCOF`
`installment`	`cardholder`	`initialInstallment`
`recurring`	`cardholder`	`initialRecurring`

Subsequent use

reason_type	initiator	Vantiv field mapping
`unscheduled`	`merchant`	`processingType: merchantInitiatedCOF` and `originalNetworkTransactionId`
`unscheduled`	`cardholder`	`processingType: cardholderInitiatedCOF`
`installment`	`merchant` or `cardholder`	`orderSource: installment`
`recurring`	`merchant` or `cardholder`	`orderSource: recurring`

The network_transaction_id returned in gateway_specific_response_fields.litle from the initial transaction must be stored and reused on subsequent MIT transactions.

curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H "Content-Type: application/json" \
  -d '{
    "transaction": {
      "payment_method_token": "payment_method_token",
      "amount": 1000,
      "currency_code": "USD",
      "order_id": "unique-order-id-67890",
      "stored_credential_initiator": "cardholder",
      "stored_credential_reason_type": "recurring"
    }
  }'

Partial capture

Send both sequence and total_count on capture. These are capture-only gateway specific fields.

curl https://core.spreedly.com/v1/transactions/[auth_token]/capture.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H "Content-Type: application/json" \
  -d '{
    "transaction": {
      "amount": 300,
      "gateway_specific_fields": {
        "litle": {
          "sequence": 1,
          "total_count": 3
        }
      }
    }
  }'

Gateway specific fields alternative

Use stored_credential_initiator, stored_credential_processing_type, and stored_credential_transaction_id when you need direct control over Vantiv's stored credential fields. The stored_credential_transaction_id comes from gateway_specific_response_fields.litle.network_transaction_id and is different from gateway_transaction_id.

Store

Store registers a payment method token at Vantiv for later reference purchases.

curl https://core.spreedly.com/v1/gateways/[gateway_token]/store.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H "Content-Type: application/json" \
  -d '{
    "transaction": {
      "payment_method_token": "payment_method_token",
      "order_id": "unique-store-order-id"
    }
  }'

The response includes a litle_token in gateway_specific_response_fields.litle for use in third-party token flows.

Bank account (ACH / eCheck)

Vantiv supports eCheck purchases, authorizations, refunds, and voids. You can pass bank account details inline or use a stored token.

curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.json \
  -u 'EnvironmentKey:AccessSecret' \
  -H "Content-Type: application/json" \
  -d '{
    "transaction": {
      "amount": 2000,
      "currency_code": "USD",
      "order_id": "unique-echeck-order-id",
      "bank_account": {
        "first_name": "Jon",
        "last_name": "Doe",
        "bank_routing_number": "021000021",
        "bank_account_number": "4242424242424242",
        "bank_account_type": "checking"
      },
      "billing_address": {
        "name": "Jon Doe",
        "address1": "456 My Street",
        "city": "New York",
        "state": "NY",
        "country": "US",
        "zip": "10001"
      }
    }
  }'

Level 2 and Level 3 enhanced data

Pass level_2_data and level_3_data gateway specific fields to support enhanced Visa and Mastercard interchange data. The line_items subfield accepts an array of objects.

See Worldpay enhanced data documentation for detailed field requirements.

curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>payment_method_token</payment_method_token>
        <amount>100</amount>
        <currency_code>USD</currency_code>
        <order_id>unique-order-id</order_id>
        <gateway_specific_fields>
          <litle>
            <level_2_data>
              <sales_tax>200</sales_tax>
            </level_2_data>
          </litle>
        </gateway_specific_fields>
      </transaction>'

curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>payment_method_token</payment_method_token>
        <amount>100</amount>
        <currency_code>USD</currency_code>
        <order_id>unique-order-id</order_id>
        <gateway_specific_fields>
          <litle>
            <level_3_data>
              <discount_amount>50</discount_amount>
              <shipping_amount>50</shipping_amount>
              <duty_amount>20</duty_amount>
              <tax_included_in_total>true</tax_included_in_total>
              <tax_amount>100</tax_amount>
              <tax_rate>0.05</tax_rate>
              <tax_exempt>true</tax_exempt>
              <number_of_payments>1</number_of_payments>
              <tax_type_identifier>01</tax_type_identifier>
              <card_acceptor_tax_id>361531321</card_acceptor_tax_id>
              <line_items type="array">
                <line_item>
                  <item_sequence_number>1</item_sequence_number>
                  <item_description>random-object</item_description>
                  <commodity_code>12345</commodity_code>
                  <product_code>TB123</product_code>
                  <quantity>2</quantity>
                  <unit_of_measure>EACH</unit_of_measure>
                  <unit_cost>25</unit_cost>
                  <discount_per_line_item>5</discount_per_line_item>
                  <line_item_total>300</line_item_total>
                  <line_item_total_with_tax>400</line_item_total_with_tax>
                  <line_item_detail_indicator>0</line_item_detail_indicator>
                </line_item>
              </line_items>
            </level_3_data>
          </litle>
        </gateway_specific_fields>
      </transaction>'

curl https://core.spreedly.com/v1/gateways/[gateway_token]/purchase.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<transaction>
        <payment_method_token>payment_method_token</payment_method_token>
        <amount>100</amount>
        <currency_code>USD</currency_code>
        <order_id>unique-order-id</order_id>
        <gateway_specific_fields>
          <litle>
            <level_2_data>
              <total_tax_amount>200</total_tax_amount>
              <customer_code>PO12345</customer_code>
              <card_acceptor_tax_id>011234567</card_acceptor_tax_id>
              <tax_included_in_total>true</tax_included_in_total>
              <tax_amount>50</tax_amount>
            </level_2_data>
          </litle>
        </gateway_specific_fields>
      </transaction>'

Reference fields and mappings

Gateway specific fields

<gateway_specific_fields>
  <litle>
    <gateway_specific_field>descriptor_name</gateway_specific_field>
    <gateway_specific_field>descriptor_phone</gateway_specific_field>
    <gateway_specific_field>order_source</gateway_specific_field>
    <gateway_specific_field>report_group</gateway_specific_field>
    <gateway_specific_field>customer_id</gateway_specific_field>
    <gateway_specific_field>debt_repayment</gateway_specific_field>
    <gateway_specific_field>cavv</gateway_specific_field>
    <gateway_specific_field>xid</gateway_specific_field>
    <gateway_specific_field>campaign</gateway_specific_field>
    <gateway_specific_field>merchant_grouping_id</gateway_specific_field>
    <gateway_specific_field>affiliate</gateway_specific_field>
    <gateway_specific_field>send_expiration_date_with_token</gateway_specific_field>
    <gateway_specific_field>stored_credential_initiator</gateway_specific_field>
    <gateway_specific_field>stored_credential_processing_type</gateway_specific_field>
    <gateway_specific_field>stored_credential_transaction_id</gateway_specific_field>
    <gateway_specific_field>fraud_filter_override</gateway_specific_field>
    <gateway_specific_field>level_2_data</gateway_specific_field>
    <gateway_specific_field>level_3_data</gateway_specific_field>
    <gateway_specific_field>custom_identifier</gateway_specific_field>
    <gateway_specific_field>sequence</gateway_specific_field>
    <gateway_specific_field>total_count</gateway_specific_field>
  </litle>
</gateway_specific_fields>

Field name	Type	Required	Use case	Example value
`descriptor_name`	String	No	Dynamic descriptor shown on the cardholder statement	`companyName`
`descriptor_phone`	String	No	Phone number associated with the dynamic descriptor	`1331131131`
`order_source`	String	No	Order channel or source such as `ecommerce`, `recurring`, or `3dsAuthenticated`	`recurring`
`report_group`	String	No	Reporting category sent to Vantiv	`Domestic Business`
`customer_id`	String	No	Customer identifier sent to Vantiv	`88`
`debt_repayment`	Boolean	No	Flags the transaction as debt repayment	`true`
`cavv`	String	No	3D Secure CAVV value	`CAVV`
`xid`	String	No	3D Secure transaction identifier	`XID`
`campaign`	String	No	Campaign tracking metadata	`Campaign Name`
`merchant_grouping_id`	String	No	Merchant grouping identifier for reporting	`Merchant Group`
`affiliate`	String	No	Affiliate tracking metadata	`Affiliate Name`
`send_expiration_date_with_token`	Boolean	No	Sends expiration date with third-party tokens when required	`true`
`stored_credential_initiator`	String	No	Stored credential initiator when using gateway specific fields	`merchant`
`stored_credential_processing_type`	String	No	Processing type such as `recurring`, `installment`, or `unscheduled`	`unscheduled`
`stored_credential_transaction_id`	String	No	Network transaction ID from the initial stored credential transaction	`160280498621098`
`fraud_filter_override`	Boolean	No	Disables Vantiv fraud filters for the transaction when true	`true`
`level_2_data`	Object	No	Visa or Mastercard Level 2 enhanced data	See examples above
`level_3_data`	Object	No	Level 3 enhanced data including line items	See examples above
`custom_identifier`	String	No	Custom tracking ID for eCheck transactions in v12 mode only	`echeck-ref-01`
`sequence`	Integer	No	Capture-only partial capture sequence number; requires `total_count`	`1`
`total_count`	Integer	No	Capture-only total number of partial captures; requires `sequence`	`3`

Gateway specific response fields

<gateway_specific_response_fields>
  <litle>
    <network_transaction_id>160280498621098</network_transaction_id>
    <authentication_result>1</authentication_result>
    <post_date><time datetime="2018-02-19">2018-02-19</time></post_date>
    <litle_token>1234567000</litle_token>
    <card_type>Credit</card_type>
    <avs_response_code>00</avs_response_code>
    <card_validation_code>M</card_validation_code>
  </litle>
</gateway_specific_response_fields>

Field name	Type	Description
`network_transaction_id`	string	Network transaction ID for stored credential tracking; store it for later MIT use
`authentication_result`	string	3D Secure authentication result from `fraudResult.authenticationResult`
`post_date`	string	Settlement post date returned by Vantiv
`litle_token`	string	Token returned on store transactions for third-party token flows
`card_type`	string	Card funding source type such as Credit or Debit
`avs_response_code`	string	Raw Vantiv AVS response code before Spreedly normalization
`card_validation_code`	string	Raw Vantiv CVV validation code before Spreedly normalization

Additional resources

📘
If you need support with this gateway please contact Support at [email protected].

📘
Documentation

Worldpay Enhanced Data Documentation

Worldpay CNP API Documentation

Third-party vaulting guide