Vantiv Express fact sheet

Quick Start

New to integrating Vantiv Express with Spreedly? Here's your setup guide:

Retrieve your Vantiv Express credentials
1. Contact the Vantiv Express support team to obtain API credentials
Get familiar with the Spreedly API
1. Review Spreedly API basics
2. Understand the core concepts: Gateways, Payment Methods, and Transactions
Add Vantiv Express gateway to Spreedly in sandbox mode

📘
Review this documentation to understand more about how to test transactions.

Adding a Vantiv Express gateway

Required Credentials

account_id: Your Vantiv Express account identifier

account_token: Your Vantiv Express account token used for authentication

application_id: Your Vantiv Express application identifier

acceptor_id: Your Vantiv Express acceptor identifier

application_name: The name of your integrating application

application_version: The version of your integrating application

Request

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>element</gateway_type>
        <account_id>Your account id</account_id>
        <account_token>Your account token</account_token>
        <application_id>Your application id</application_id>
        <acceptor_id>Your acceptor_id</acceptor_id>
        <application_name>Your application name</application_name>
        <application_version>Your application version</application_version>
      </gateway>'

Response

<gateway>
    <token>33RYJ8PZP39RSBRGJ9621D6xyz</token>
    <gateway_type>element</gateway_type>
    <name>Vantiv Express (formerly Element)</name>
    <description nil="true"/>
    <merchant_profile_key nil="true"/>
    <sub_merchant_key nil="true"/>
    <account_id>1246640</account_id>
    <application_id>16923</application_id>
    <acceptor_id>364803500</acceptor_id>
    <application_name>Spreedly</application_name>
    <application_version>1</application_version>
    <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">false</supports_reference_purchase>
        <supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
        <supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
        <supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
        <supports_offsite_synchronous_purchase type="boolean">false</supports_offsite_synchronous_purchase>
        <supports_offsite_synchronous_authorize type="boolean">false</supports_offsite_synchronous_authorize>
        <supports_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
        <supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
        <supports_3dsecure_2_mpi_purchase type="boolean">false</supports_3dsecure_2_mpi_purchase>
        <supports_3dsecure_2_mpi_authorize type="boolean">false</supports_3dsecure_2_mpi_authorize>
        <supports_store type="boolean">true</supports_store>
        <supports_remove type="boolean">true</supports_remove>
        <supports_fraud_review type="boolean">false</supports_fraud_review>
        <supports_network_tokenization type="boolean">true</supports_network_tokenization>
        <supports_inquire_by_gateway_transaction_id type="boolean">false</supports_inquire_by_gateway_transaction_id>
        <supports_inquire_by_order_id type="boolean">false</supports_inquire_by_order_id>
        <supports_transaction_retry type="boolean">false</supports_transaction_retry>
        <supports_stored_stored_credentials type="boolean">false</supports_stored_stored_credentials>
        <supports_level_2_data type="boolean">true</supports_level_2_data>
        <supports_level_3_data type="boolean">true</supports_level_3_data>
        <supports_stored_credentials type="boolean">true</supports_stored_credentials>
    </characteristics>
    <credentials>
        <credential>
            <name>account_id</name>
            <value>12xxxxx</value>
        </credential>
        <credential>
            <name>application_id</name>
            <value>16xxx</value>
        </credential>
        <credential>
            <name>acceptor_id</name>
            <value>364xxxxx</value>
        </credential>
        <credential>
            <name>application_name</name>
            <value>Spreedly</value>
        </credential>
        <credential>
            <name>application_version</name>
            <value>1</value>
        </credential>
    </credentials>
    <gateway_settings>
  </gateway_settings>
    <gateway_specific_fields>
        <gateway_specific_field>card_present_code</gateway_specific_field>
        <gateway_specific_field>payment_type</gateway_specific_field>
        <gateway_specific_field>submission_type</gateway_specific_field>
        <gateway_specific_field>duplicate_check_disable_flag</gateway_specific_field>
        <gateway_specific_field>merchant_descriptor</gateway_specific_field>
        <gateway_specific_field>market_code</gateway_specific_field>
        <gateway_specific_field>ticket_number</gateway_specific_field>
        <gateway_specific_field>merchant_supplied_transaction_id</gateway_specific_field>
        <gateway_specific_field>duplicate_override_flag</gateway_specific_field>
        <gateway_specific_field>terminal_id</gateway_specific_field>
        <gateway_specific_field>terminal_type</gateway_specific_field>
        <gateway_specific_field>card_holder_present_code</gateway_specific_field>
        <gateway_specific_field>card_input_code</gateway_specific_field>
        <gateway_specific_field>cvv_presence_code</gateway_specific_field>
        <gateway_specific_field>terminal_capability_code</gateway_specific_field>
        <gateway_specific_field>terminal_environment_code</gateway_specific_field>
        <gateway_specific_field>partial_approved_flag</gateway_specific_field>
        <gateway_specific_field>lodging</gateway_specific_field>
        <gateway_specific_field>sales_tax_amount</gateway_specific_field>
        <gateway_specific_field>commercial_card_customer_code</gateway_specific_field>
        <gateway_specific_field>level_3_data</gateway_specific_field>
        <gateway_specific_field>idempotency_key</gateway_specific_field>
    </gateway_specific_fields>
    <payment_methods>
        <payment_method>credit_card</payment_method>
        <payment_method>bank_account</payment_method>
        <payment_method>third_party_token</payment_method>
        <payment_method>apple_pay</payment_method>
        <payment_method>google_pay</payment_method>
    </payment_methods>
    <state>retained</state>
    <redacted type="boolean">false</redacted>
    <sandbox type="boolean">true</sandbox>
    <mode>default</mode>
    <created_at type="dateTime">2026-06-12T09:51:03Z</created_at>
    <updated_at type="dateTime">2026-06-12T09:51:03Z</updated_at>
</gateway>

Purchase (Auth and Capture)

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",
    "email": "[email protected]",
    "billing_address": {
        "name": "Mit Donga",
        "address1": "some address1",
        "address": "some address2",
        "city": "NYC",
        "state": "CA",
        "zip": "32191",
        "country": "US"
    },
    "retain_on_success": true
  }
}'

📘
Additional Notes

The ticket_number field is required when performing a general_credit transaction.

The lodging field accepts an object which is required when performing hotel/lodging transactions. If you wish to initiate a hotel/lodging transaction, the market_code field will need to indicate the correct transaction type. For more information, please refer to the Express documentation.

Advanced features

Idempotent Requests

Spreedly supports idempotency for Vantiv Express (formerly Element) to prevent duplicate transactions in the event of network timeouts or accidental retries. When an idempotency_key is included in a request, the Spreedly platform maps this value to the IdempotencyKey field within the Vantiv Express XML Transaction Class.

📘
Notes

The gateway strictly mandates that the idempotency_key be formatted as a UUID (Universally Unique Identifier). The use of a non-UUID compliant string results in a validation error at the gateway level.

The idempotency feature is not available for Store and Unstore APIs.

Network Tokenization

Spreedly supports Network Tokenization for Vantiv Express (formerly Element). Transactions can be processed using network-issued tokens from Visa and Mastercard across CreditCardSale, CreditCardAuthorization, and CreditCardCredit methods. This update includes support for high-security cryptograms (TAVV/UCAF) to secure lower interchange rates and automatically tracks unique cards using the Payment Account Reference (PAR).

Stored Credentials

For Vantiv Express, sending stored credential fields is supported through Spreedly's first-class stored-credential API. For any Authorize or Purchase request, include the fields below. They tell Spreedly more about the nature of the transaction so that the correct PaymentType, SubmissionType and NetworkTransactionID elements are sent inside the <Transaction> block of the Element Express XML payload.

📘
Learn more about how Spreedly enables use of stored credentials by reviewing our Stored Credentials guide

First / credential-on-file setup (CIT and MIT initial)

Send stored_credential_initial_transaction: true. Spreedly will set <SubmissionType>1</SubmissionType>(Initial). Do not send stored_credential_network_transaction_id — there isn't one yet; the network returns it on the response of this transaction.

reason_type	initiator	PaymentType (mapped)	SubmissionType
`installment`	`cardholder`	`Installment (2)`	`Initial (1)`
`installment`	`merchant`	`Installment (2)`	`Initial (1)`
`recurring`	`cardholder`	`Recurring (1)`	`Initial (1)`
`recurring`	`merchant`	`Recurring (1)`	`Initial (1)`
`unscheduled`	`cardholder`	`CardHolderInitiated (3)`	`Initial (1)`
`unscheduled`	`merchant`	`CredentialOnFile (4)`	`Initial (1)`

Subsequent use

Send stored_credential_initial_transaction: false together with the stored_credential_network_transaction_id returned by Vantiv on the initial transaction. Spreedly will set <SubmissionType>2</SubmissionType> (Subsequent) and pass the NTID through to the network.

reason_type	initiator	PaymentType (mapped)	SubmissionType
`installment`	`cardholder`	`Installment (2)`	`Subsequent (2)`
`installment`	`merchant`	`Installment (2)`	`Subsequent (2)`
`recurring`	`cardholder`	`Recurring (1)`	`Subsequent (2)`
`recurring`	`merchant`	`Recurring (1)`	`Subsequent (2)`
`unscheduled`	`cardholder`	`CardHolderInitiated (3)`	`Subsequent (2)`
`unscheduled`	`merchant`	`CredentialOnFile (4)`	`Subsequent (2)`

📘
Note
The initiator field is only consulted for reason_type: unscheduled. For recurring and installment, Vantiv Express does not differentiate by initiator, so the <PaymentType> mapping is the same for both cardholder and merchant.
When stored-credential fields are supplied, the payment_type and submission_type gateway-specific fields (which override <PaymentType> / <SubmissionType> directly) are ignored to avoid duplicate elements inside the <Transaction> block.

L2/L3 Fields

This gateway supports Level 2 and Level 3 transaction processing.

Please refer to the documentation on Level 2 and Level 3 data.

{
    "transaction": {
        "gateway_specific_fields": {
            "element": {
                "level_3_data": {
                    "merchant_vat_registration_number": "60ac16",
                    "customer_vat_registration_number": "5a5a2e",
                    "summary_commodity_code": "345",
                    "discount_amount": "12",
                    "freight_amount": "500",
                    "duty_amount": "0",
                    "destination_postal_code": "121",
                    "ship_from_postal_code": "2876",
                    "destination_country_code": "US",
                    "unique_vat_invoice_reference_number": "1234",
                    "order_date": "20250910",
                    "vat_amount": "12",
                    "vat_rate": "",
                    "alternate_tax_amount": "234",
                    "national_tax_amount": "850",
                    "line_items": [
                        {
                            "commodity_code": "1234567890",
                            "product_code": "WIDGET001",
                            "description": "Widget A",
                            "quantity": "2",
                            "unit_price": "4000",
                            "unit_measure": "2",
                            "total_amount": "8000",
                            "tax_amount": "640",
                            "tax_rate": "2",
                            "discount_amount": "6",
                            "alternate_tax_id": "1123",
                            "vat_type": "1",
                            "discount_code": "NotSupported",
                            "net_gross_code": "ItemAmountIncludesTaxAmount",
                            "extended_item_amount": "8",
                            "debit_credit_code": "ExtendedItemAmountIsDebit",
                            "item_discount_rate": "1"
                        }
                    ]
                }
            }
        }
   }

Gateway Specific Fields

<gateway_specific_fields>
  <element>
    <gateway_specific_field>card_present_code</gateway_specific_field>
    <gateway_specific_field>payment_type</gateway_specific_field>
    <gateway_specific_field>submission_type</gateway_specific_field>
    <gateway_specific_field>duplicate_check_disable_flag</gateway_specific_field>
    <gateway_specific_field>duplicate_override_flag</gateway_specific_field>
    <gateway_specific_field>terminal_id</gateway_specific_field>
    <gateway_specific_field>market_code</gateway_specific_field>
    <gateway_specific_field>ticket_number</gateway_specific_field>
    <gateway_specific_field>merchant_supplied_transaction_id</gateway_specific_field>
    <gateway_specific_field>terminal_type</gateway_specific_field>
    <gateway_specific_field>card_holder_present_code</gateway_specific_field>
    <gateway_specific_field>card_input_code</gateway_specific_field>
    <gateway_specific_field>cvv_presence_code</gateway_specific_field>
    <gateway_specific_field>terminal_capability_code</gateway_specific_field>
    <gateway_specific_field>terminal_environment_code</gateway_specific_field>
    <gateway_specific_field>partial_approved_flag</gateway_specific_field>
    <gateway_specific_field>lodging</gateway_specific_field>
    <gateway_specific_field>sales_tax_amount</gateway_specific_field>
    <gateway_specific_field>commercial_card_customer_code</gateway_specific_field>
    <gateway_specific_field>level_3_data</gateway_specific_field>
    <gateway_specific_field>idempotency_key</gateway_specific_field>
  </element>
</gateway_specific_fields>

Field Name	Type	Required	Use Case (Description)	Example Value
card_present_code	String / Integer	No	Indicates whether the card was physically present. Maps to Express values: `Unknown` (1), `Present` (2), `NotPresent` (3).	`NotPresent` or `3`
payment_type	String / Integer	No	Specifies the payment type for the transaction. Maps to Express values: `NotUsed` (0), `Recurring` (1), `Installment` (2), `CardHolderInitiated` (3), `CredentialOnFile` (4). Ignored when stored-credential fields are supplied.	`CardHolderInitiated` or `3`
submission_type	String / Integer	No	Indicates whether the transaction is an initial or subsequent stored-credential use. Maps to Express values: `NotUsed` (0), `Initial` (1), `Subsequent` (2), `Resubmission` (3), `ReAuthorization` (4), `DelayedCharges` (5), `NoShow` (6). Ignored when stored-credential fields are supplied.	`Initial` or `1`
duplicate_check_disable_flag	Boolean	No	When `true`, disables duplicate-transaction checking at the gateway.	`true`
duplicate_override_flag	Boolean	No	When `true`, overrides duplicate-transaction checking at the gateway (treated equivalently to `duplicate_check_disable_flag`).	`true`
terminal_id	String	No	Identifies the terminal processing the transaction. Defaults to `01` if not provided.	`02`
market_code	String / Integer	No	Indicates the market or industry segment for the transaction. Maps to Express values such as `AutoRental` (1), `DirectMarketing` (2), `ECommerce` (3), `FoodRestaurant` (4), `HotelLodging` (5), `Petroleum` (6), `Retail` (7), `QSR` (8), `Grocery` (9).	`ECommerce` or `3`
ticket_number	String	No	User-defined ticket number. Numeric recommended. Required when performing a `general_credit` transaction.	`1`
merchant_supplied_transaction_id	String	No	Merchant-supplied identifier for tracking the transaction in your systems.	`your-transaction-id`
terminal_type	String / Integer	No	Type of terminal used for the transaction. Maps to Express values such as `Unknown` (0), `PointOfSale` (1), `ECommerce` (2), `MOTO` (3), `FuelPump` (4), `ATM` (5), `Voice` (6), `Mobile` (7), `WebSiteGiftCard` (8).	`ECommerce` or `2`
card_holder_present_code	String / Integer	No	Indicates whether the cardholder was present. Maps to Express values such as `Default` (0), `Unknown` (1), `Present` (2), `NotPresent` (3), `MailOrder` (4), `PhoneOrder` (5), `StandingAuth` (6), `ECommerce` (7).	`ECommerce` or `7`
card_input_code	String / Integer	No	Describes how card data was captured. Maps to Express values such as `ManualKeyed` (4), `MagstripeRead` (2), `ChipRead` (6), and others.	`ManualKeyed` or `4`
cvv_presence_code	String / Integer	No	Indicates CVV presence status. Maps to Express values: `UseDefault` (0), `NotProvided` (1), `Provided` (2), `Illegible` (3), `CustomerIllegible` (4).	`NotProvided` or `1`
terminal_capability_code	String / Integer	No	Describes terminal capabilities. Maps to Express values such as `KeyEntered` (5), `MagstripeReader` (3), `ChipReader` (6), and others.	`KeyEntered` or `5`
terminal_environment_code	String / Integer	No	Describes the terminal environment. Maps to Express values such as `ECommerce` (6), `LocalAttended` (2), `RemoteUnattended` (5), and others.	`ECommerce` or `6`
partial_approved_flag	Boolean	No	Specifies whether software supports partial approvals	`true`
lodging	Object	No	Extended lodging data object required for hotel/lodging transactions. When used, `market_code` should indicate the appropriate lodging transaction type (for example, `HotelLodging`). Supports fields such as `agreement_number`, `check_in_date`, `check_out_date`, `room_amount`, `room_tax`, `no_show_indicator`, `duration`, `customer_name`, `client_code`, `extra_charges_detail`, `extra_charges_amounts`, `prestigious_property_code`, `special_program_code`, and `charge_type`.	As shown below this table, for more information check Worldpay Express documentation
sales_tax_amount	String	No	Sales tax amount for the transaction, used for commercial and Level 2/3 processing.	`"100"`
commercial_card_customer_code	String	No	Customer code sent with commercial card transactions.	any value
level_3_data	Object	No	Level 3 enhanced data object. Supported on Capture requests. Includes header fields and a `line_items` array.	See L2/L3 Fields section
idempotency_key	String (UUID)	No	UUID used to prevent duplicate transactions on retry. Not supported for Store or Unstore operations.	`550e8400-e29b-41d4-a716-446655440000`

The lodging field can look like the structure below:

{
  "agreement_number": "12345",
  "check_in_date": "YYYYMMDD",
  "check_out_date": "YYYYMMDD",
  "room_amount": 1000,
  "room_tax": 0,
  "no_show_indicator": 0,
  "duration": 5,
  "customer_name": "First Last",
  "client_code": "Default",
  "extra_charges_detail": "01",
  "extra_charges_amounts": "Default",
  "prestigious_property_code": "DollarLimit500",
  "special_program_code": "Sale",
  "charge_type": "Restaurant"
}

Gateway Specific Response Fields

<gateway_specific_response_fields>
  <element>
    <host_response_code>000</host_response_code>
    <gateway_transaction_id>531976182</gateway_transaction_id>
    <commercial_card_response_code>B</commercial_card_response_code>
  </element>
</gateway_specific_response_fields>

Field Name	Type	Description
host_response_code	string	Host response code returned by the Vantiv Express gateway indicating the result from the payment host.
gateway_transaction_id	string	Transaction identifier
commercial_card_response_code	string	Commercial card indicator (Vantiv, FDC, TSYS)

Additional resources

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

📘

Vantiv Express / Worldpay Documentation: Worldpay Express API documentation

API Endpoints

Environment Transaction URL Services URL (Store / Unstore)
Test (Sandbox) https://certtransaction.elementexpress.com https://certservices.elementexpress.com
Production https://transaction.elementexpress.com https://services.elementexpress.com