Elavon gateway guide

Quick Start

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

  1. Retrieve your Elavon credentials
    1. Log in to your Elavon Converge account (Elavon's merchant portal).
    2. Note your Converge Account ID. This is the merchant_id in Spreedly.
    3. Create or select the API user that Spreedly will use, and note its User ID (user).
    4. Generate the terminal PIN for that user (pin).
    5. Make sure the user has permission for the transaction types you plan to run (for example purchase, refund and void). Missing permissions cause those transactions to fail.
  2. Get familiar with the Spreedly API
    1. Review Spreedly API basics
    2. Understand the core concepts: Gateways, Payment Methods, and Transactions
  3. Add Elavon gateway to Spreedly in sandbox mode
📘

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

Additional notes
  • Elavon (Converge) uses an XML API. Spreedly sends every request to the processxml.do endpoint listed under Support and Resources.
  • Supported card brands: Visa, Mastercard, American Express and Discover.
  • Supported countries: US, CA, PR, DE, IE, NO, PL, LU, BE, NL, MX.
  • Amounts are sent in dollars (major units). The default currency is USD.
  • currency_code is sent to Elavon only when the multi_currency gateway setting is true. Multi-currency must also be enabled on the Elavon account.
  • Bank account (ACH) payment methods support purchase and void only.
  • 3D Secure and network tokenization are not supported on this gateway.

Adding an Elavon Gateway

Required Credentials

  • merchant_id: Your Elavon Converge Account ID (labelled "Merchant ID" in the dashboard)
  • pin: The terminal PIN for the API user (stored encrypted, never returned)
  • user: The Converge user ID for API requests

Optional Gateway Settings

  • multi_currency: Set to true to send currency_code to Elavon. Defaults to false. Multi-currency must also be enabled on the Elavon account.

Request

curl https://core.spreedly.com/v1/gateways.xml \
  -u 'EnvironmentKey:AccessSecret' \
  -H 'Content-Type: application/xml' \
  -d '<gateway>
        <gateway_type>elavon</gateway_type>
        <merchant_id>your_account_id</merchant_id>
        <pin>your_pin</pin>
        <user>your_user_id</user>
        <multi_currency>false</multi_currency>
      </gateway>'

Response

<gateway>
 <token>6C3KRRY9TB8Y2RQVMW9B701JAV</token>
 <gateway_type>elavon</gateway_type>
 <name>Elavon</name>
 <description nil="true"/>
 <merchant_profile_key nil="true"/>
 <sub_merchant_key nil="true"/>
 <merchant_id>000301</merchant_id>
 <user>apiuser591937</user>
 <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">false</supports_general_credit>
  <supports_void type="boolean">true</supports_void>
  <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">false</supports_network_tokenization>
  <supports_inquire_by_gateway_transaction_id type="boolean">true</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_stored_credentials type="boolean">true</supports_stored_credentials>
 </characteristics>
 <credentials>
  <credential>
   <name>merchant_id</name>
   <value>000301</value>
  </credential>
  <credential>
   <name>user</name>
   <value>apiuser591937</value>
  </credential>
 </credentials>
 <gateway_settings>
  <multi_currency>false</multi_currency>
 </gateway_settings>
 <gateway_specific_fields>
  <gateway_specific_field>customer_number</gateway_specific_field>
  <gateway_specific_field>custom_fields</gateway_specific_field>
  <gateway_specific_field>dba</gateway_specific_field>
  <gateway_specific_field>level_3_data</gateway_specific_field>
  <gateway_specific_field>merchant_initiated_unscheduled</gateway_specific_field>
  <gateway_specific_field>cit_mit_cof_indicator</gateway_specific_field>
  <gateway_specific_field>ecs_product_code</gateway_specific_field>
  <gateway_specific_field>entry_mode</gateway_specific_field>
  <gateway_specific_field>add_recurring_token</gateway_specific_field>
  <gateway_specific_field>ssl_token</gateway_specific_field>
  <gateway_specific_field>installments</gateway_specific_field>
  <gateway_specific_field>payment_number</gateway_specific_field>
  <gateway_specific_field>ssl_vendor_id</gateway_specific_field>
  <gateway_specific_field>apple_pay_domain</gateway_specific_field>
  <gateway_specific_field>partial_shipment_flag</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>third_party_apple_pay</payment_method>
  <payment_method>third_party_google_pay</payment_method>
 </payment_methods>
 <state>retained</state>
 <redacted type="boolean">false</redacted>
 <sandbox type="boolean">false</sandbox>
 <mode>default</mode>
 <created_at type="dateTime">2026-11-06T10:30:45Z</created_at>
 <updated_at type="dateTime">2026-11-06T10:30:45Z</updated_at>
</gateway>

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": "ORD-1001",
    "retain_on_success": true
  }
}'

Supported Payment Methods

Payment methodNotes
credit_cardAll supported operations.
bank_accountPurchase and void only. See ACH Bank Account Transactions.
third_party_tokenAn Elavon token, sent as ssl_token.
third_party_apple_payEncrypted Apple Pay payment data, sent as ssl_applepay_web. See Third Party Apple Pay.
third_party_google_payEncrypted Google Pay payment data, sent as ssl_google_pay.

Gateway Specific Fields

<gateway_specific_fields>
  <elavon>
    <gateway_specific_field>customer_number</gateway_specific_field>
    <gateway_specific_field>custom_fields</gateway_specific_field>
    <gateway_specific_field>dba</gateway_specific_field>
    <gateway_specific_field>level_3_data</gateway_specific_field>
    <gateway_specific_field>merchant_initiated_unscheduled</gateway_specific_field>
    <gateway_specific_field>cit_mit_cof_indicator</gateway_specific_field>
    <gateway_specific_field>ecs_product_code</gateway_specific_field>
    <gateway_specific_field>entry_mode</gateway_specific_field>
    <gateway_specific_field>add_recurring_token</gateway_specific_field>
    <gateway_specific_field>ssl_token</gateway_specific_field>
    <gateway_specific_field>installments</gateway_specific_field>
    <gateway_specific_field>payment_number</gateway_specific_field>
    <gateway_specific_field>ssl_vendor_id</gateway_specific_field>
    <gateway_specific_field>apple_pay_domain</gateway_specific_field>
    <gateway_specific_field>partial_shipment_flag</gateway_specific_field>
  </elavon>
</gateway_specific_fields>
Field NameTypeRequiredUse Case (Description)Example Value
customer_numberStringNoCustomer number, sent as ssl_customer_number. Accepted on all transaction types.44
custom_fieldsObjectNoMerchant-defined custom fields. Each key is sent to Elavon as its own element, so keys must match custom fields configured in Converge. Accepted on all transaction types.{ "custom_field_one": "value one" }
dbaStringNoDynamic "doing business as" name, sent as ssl_dynamic_dba.company name
level_3_dataObjectNoLevel 2 and level 3 data, including line items. Authorize and purchase only. See the level 3 example below.See example
cit_mit_cof_indicatorStringNoOverrides the CIT/MIT credential-on-file indicator (ssl_cit_mit_cof_indicator) that Spreedly derives from the stored credential fields. See Stored Credentials for accepted values.C01
merchant_initiated_unscheduledStringNoLegacy flag. Y sends M01 (merchant initiated, unscheduled) when cit_mit_cof_indicator isn't passed.Y
entry_modeStringNoOverrides ssl_entry_mode. Otherwise Spreedly sends 12 for unscheduled stored credential transactions.12
add_recurring_tokenStringNoSend Y on the initial recurring transaction to ask Elavon to create a token (ssl_add_token). The token is returned in the ssl_token response field. Tokenization must be enabled on the Elavon account.Y
ssl_tokenStringNoAn Elavon token to transact with instead of the card details. Accepted on all transaction types.4421912014039990
installmentsIntegerFor installmentsTotal number of payments in the installment plan (ssl_payment_count). Sent only when stored_credential_reason_type is installment.12
payment_numberIntegerFor installmentsSequence number of this payment within the plan (ssl_payment_number). Sent only when stored_credential_reason_type is installment.3
ecs_product_codeStringNoACH product code for bank account purchases. See ACH Bank Account Transactions.WEB
apple_pay_domainStringFor Apple PayMerchant domain used to start the Apple Pay session (applepayDomain). See Third Party Apple Pay.example.com
ssl_vendor_idStringNoVendor ID sent with the Apple Pay session request. Regular transactions always use Spreedly's own vendor ID.123
partial_shipment_flagBooleanNoCapture only. Send true on every capture to allow multiple captures against one authorization (ssl_partial_shipment_flag).true

Level 3 example (purchase or authorize)

<gateway_specific_fields>
  <elavon>
    <customer_number>44</customer_number>
    <dba>company name</dba>
    <custom_fields>
      <custom_field_one>value one</custom_field_one>
    </custom_fields>
    <level_3_data>
      <customer_code>ABC12345</customer_code>
      <salestax>1.30</salestax>
      <salestax_indicator>Y</salestax_indicator>
      <level3_indicator>Y</level3_indicator>
      <ship_to_zip>12345</ship_to_zip>
      <ship_to_country>US</ship_to_country>
      <shipping_amount>10</shipping_amount>
      <ship_from_postal_code>54321</ship_from_postal_code>
      <discount_amount>2</discount_amount>
      <duty_amount>5</duty_amount>
      <national_tax_indicator>1</national_tax_indicator>
      <national_tax_amount>4</national_tax_amount>
      <order_date>01/22/2014</order_date>
      <other_tax>3</other_tax>
      <summary_commodity_code>123</summary_commodity_code>
      <merchant_vat_number>222</merchant_vat_number>
      <customer_vat_number>333</customer_vat_number>
      <freight_tax_amount>4</freight_tax_amount>
      <vat_invoice_number>224</vat_invoice_number>
      <tracking_number>TN12345</tracking_number>
      <shipping_company>Elavon</shipping_company>
      <other_fees>5</other_fees>
      <line_items>
        <description>Product 1</description>
        <product_code>P-001</product_code>
        <commodity_code>CMD1</commodity_code>
        <quantity>101</quantity>
        <unit_of_measure>M1</unit_of_measure>
        <unit_cost>5.00</unit_cost>
        <discount_indicator>1.00</discount_indicator>
        <tax_indicator>1</tax_indicator>
        <discount_amount>2</discount_amount>
        <tax_rate>20</tax_rate>
        <tax_amount>12</tax_amount>
        <tax_type>1</tax_type>
        <extended_total>20</extended_total>
        <total>20</total>
        <alternative_tax>GST</alternative_tax>
      </line_items>
    </level_3_data>
  </elavon>
</gateway_specific_fields>

Each level_3_data field is sent with an ssl_ prefix (for example ssl_salestax). Each line item field is sent inside LineItemProducts with an ssl_line_Item_ prefix (for example ssl_line_Item_product_code).

Gateway Specific Response Fields

<gateway_specific_response_fields>
  <elavon>
    <approval_code>123456</approval_code>
    <ssl_token>7891000</ssl_token>
  </elavon>
</gateway_specific_response_fields>
Field NameTypeDescription
approval_codestringAuthorization code returned by Elavon (ssl_approval_code).
ssl_tokenstringElavon token, returned when one was requested (for example with add_recurring_token).
apple_pay_sessionstringApple Pay merchant session. Returned only by the Apple Pay session verify call.

Other values Spreedly reads from the Elavon response:

  • gateway_transaction_id: Elavon ssl_txn_id.
  • network_transaction_id: ssl_oar_data and ssl_ps2000_data joined with |.
  • payment_account_reference: Elavon ssl_par_value.
  • error_code: Elavon errorCode.

Stored Credentials

For Elavon, sending stored credential fields can be done using Spreedly's first class support. For any Authorize or Purchase request, you need to include two fields which tell Spreedly a little bit more about the nature of the transaction:

  • stored_credential_initiator
  • stored_credential_reason_type

Spreedly maps them to Elavon's ssl_cit_mit_cof_indicator. Passing the cit_mit_cof_indicator gateway specific field overrides the mapping.

1. First / credential-on-file setup (CIT)

reason_typeinitiatorssl_cit_mit_cof_indicator (Elavon mapped field)
unscheduledcardholderC01
recurringcardholderC03
installmentcardholderC04

2. Subsequent use

reason_typeinitiatorssl_cit_mit_cof_indicator
unscheduledmerchantM01
recurringmerchantM03
installmentmerchantM04
unscheduled / recurring / installmentcardholderC01 / C03 / C04

3. Other fields sent for stored credential transactions

Elavon fieldWhen it is sent
ssl_recurring_flag1 for recurring, 2 for installment.
ssl_entry_mode12 for unscheduled, unless the entry_mode gateway specific field is passed. Not sent when transacting with an Elavon token.
ssl_payment_count / ssl_payment_numberFor installment, from the installments and payment_number gateway specific fields.
ssl_oar_data / ssl_ps2000_dataFor subsequent transactions, from the previous network_transaction_id. Not sent when transacting with an Elavon token.

4. Accepted values for cit_mit_cof_indicator

ValueDescription
000Not a CIT/MIT credential-on-file transaction
C01Cardholder initiated – credential on file (ad hoc)
C02Cardholder initiated – standing order
C03Cardholder initiated – subscription
C04Cardholder initiated – installment
M01Merchant initiated – unscheduled credential on file (ad hoc)
M02Merchant initiated – standing order
M03Merchant initiated – subscription
M04Merchant initiated – installment
M05Merchant initiated – partial shipment
M06Merchant initiated – related/delayed charge
M07Merchant initiated – no-show charge
M08Merchant initiated – re-submission
📘

Learn more about how spreedly enables use of stored credentials by reviewing our Stored credentials Guide

Partial Capture

Elavon supports capturing less than the authorized amount.

  • A single partial capture needs no extra fields. Authorize, then capture a smaller amount. Elavon then closes the authorization, so a second capture against it fails.
  • To capture more than once against the same authorization, send partial_shipment_flag as true on every capture, including the first. If the first capture omits the flag, later captures fail.
  • The total captured can't exceed the authorized amount.
curl https://core.spreedly.com/v1/transactions/[authorize_transaction_token]/capture.json \
-u 'EnvironmentKey:AccessSecret' \
-H "Content-Type: application/json" \
-d '{
  "transaction": {
    "amount": 50,
    "gateway_specific_fields": {
      "elavon": {
        "partial_shipment_flag": true
      }
    }
  }
}'

ACH Bank Account Transactions

Bank account payment methods support purchase and void only. Use the ecs_product_code gateway specific field to set the ACH product code:

ValueMeaning
WEBInternet-initiated, consumer account (default for personal accounts)
TELTelephone-authorized, consumer account
PPDPrearranged payment or deposit, consumer account (written authorization, for example recurring)
CCDCorporate credit or debit, business account (default for business accounts)

If ecs_product_code isn't passed, Spreedly picks a default from account_holder_type: CCD for business accounts and WEB otherwise.

Third Party Apple Pay

Elavon supports Apple Pay through the third_party_apple_pay payment method. Payment methods of this type are locked to the elavon gateway type, so they fail on any other gateway.

Step 1: Start the Apple Pay session. Run a verify with a third_party_apple_pay payment method. apple_pay_domain is required; ssl_vendor_id is optional. Spreedly sends an EWALLETINQUIRY request to Elavon and returns the session in the apple_pay_session response field.

curl https://core.spreedly.com/v1/gateways/[gateway_token]/verify.json \
-u 'EnvironmentKey:AccessSecret' \
-H "Content-Type: application/json" \
-d '{
  "transaction": {
    "payment_method": {
      "payment_method_type": "third_party_apple_pay",
      "gateway_type": "elavon"
    },
    "gateway_specific_fields": {
      "elavon": {
        "apple_pay_domain": "example.com",
        "ssl_vendor_id": "123"
      }
    }
  }
}'

Step 2: Update the payment method. Use the session to complete Apple Pay on the client and get the PKPaymentToken. Then update the payment method with its paymentData:

curl https://core.spreedly.com/v1/payment_methods/[payment_method_token].json \
-u 'EnvironmentKey:AccessSecret' \
-X PUT \
-H "Content-Type: application/json" \
-d '{
  "payment_method": {
    "payment_data": {
      "version": "EC_v1",
      "data": "...",
      "signature": "...",
      "header": {
        "ephemeralPublicKey": "...",
        "transactionId": "...",
        "publicKeyHash": "..."
      }
    }
  }
}'

Step 3: Purchase or authorize with the updated payment method. Spreedly sends the payment data to Elavon as ssl_applepay_web. A purchase or authorize fails if the payment method has no payment_data yet.

Additional resources

📘

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


Did this page help you?