Elavon gateway guide
Quick Start
New to integrating Elavon with Spreedly? Here's your setup guide:
- Retrieve your Elavon credentials
- Log in to your Elavon Converge account (Elavon's merchant portal).
- Note your Converge Account ID. This is the
merchant_idin Spreedly. - Create or select the API user that Spreedly will use, and note its User ID (
user). - Generate the terminal PIN for that user (
pin). - 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.
- Get familiar with the Spreedly API
- Review Spreedly API basics
- Understand the core concepts: Gateways, Payment Methods, and Transactions
- Add Elavon gateway to Spreedly in sandbox mode
Review this documentation to understand more about how to test transactions.
| Additional notes |
|---|
|
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
trueto sendcurrency_codeto Elavon. Defaults tofalse. 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 method | Notes |
|---|---|
credit_card | All supported operations. |
bank_account | Purchase and void only. See ACH Bank Account Transactions. |
third_party_token | An Elavon token, sent as ssl_token. |
third_party_apple_pay | Encrypted Apple Pay payment data, sent as ssl_applepay_web. See Third Party Apple Pay. |
third_party_google_pay | Encrypted 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 Name | Type | Required | Use Case (Description) | Example Value |
|---|---|---|---|---|
customer_number | String | No | Customer number, sent as ssl_customer_number. Accepted on all transaction types. | 44 |
custom_fields | Object | No | Merchant-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" } |
dba | String | No | Dynamic "doing business as" name, sent as ssl_dynamic_dba. | company name |
level_3_data | Object | No | Level 2 and level 3 data, including line items. Authorize and purchase only. See the level 3 example below. | See example |
cit_mit_cof_indicator | String | No | Overrides 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_unscheduled | String | No | Legacy flag. Y sends M01 (merchant initiated, unscheduled) when cit_mit_cof_indicator isn't passed. | Y |
entry_mode | String | No | Overrides ssl_entry_mode. Otherwise Spreedly sends 12 for unscheduled stored credential transactions. | 12 |
add_recurring_token | String | No | Send 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_token | String | No | An Elavon token to transact with instead of the card details. Accepted on all transaction types. | 4421912014039990 |
installments | Integer | For installments | Total number of payments in the installment plan (ssl_payment_count). Sent only when stored_credential_reason_type is installment. | 12 |
payment_number | Integer | For installments | Sequence number of this payment within the plan (ssl_payment_number). Sent only when stored_credential_reason_type is installment. | 3 |
ecs_product_code | String | No | ACH product code for bank account purchases. See ACH Bank Account Transactions. | WEB |
apple_pay_domain | String | For Apple Pay | Merchant domain used to start the Apple Pay session (applepayDomain). See Third Party Apple Pay. | example.com |
ssl_vendor_id | String | No | Vendor ID sent with the Apple Pay session request. Regular transactions always use Spreedly's own vendor ID. | 123 |
partial_shipment_flag | Boolean | No | Capture 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 Name | Type | Description |
|---|---|---|
approval_code | string | Authorization code returned by Elavon (ssl_approval_code). |
ssl_token | string | Elavon token, returned when one was requested (for example with add_recurring_token). |
apple_pay_session | string | Apple Pay merchant session. Returned only by the Apple Pay session verify call. |
Other values Spreedly reads from the Elavon response:
gateway_transaction_id: Elavonssl_txn_id.network_transaction_id:ssl_oar_dataandssl_ps2000_datajoined with|.payment_account_reference: Elavonssl_par_value.error_code: ElavonerrorCode.
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_initiatorstored_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)
CIT)reason_type | initiator | ssl_cit_mit_cof_indicator (Elavon mapped field) |
|---|---|---|
unscheduled | cardholder | C01 |
recurring | cardholder | C03 |
installment | cardholder | C04 |
2. Subsequent use
reason_type | initiator | ssl_cit_mit_cof_indicator |
|---|---|---|
unscheduled | merchant | M01 |
recurring | merchant | M03 |
installment | merchant | M04 |
unscheduled / recurring / installment | cardholder | C01 / C03 / C04 |
3. Other fields sent for stored credential transactions
| Elavon field | When it is sent |
|---|---|
ssl_recurring_flag | 1 for recurring, 2 for installment. |
ssl_entry_mode | 12 for unscheduled, unless the entry_mode gateway specific field is passed. Not sent when transacting with an Elavon token. |
ssl_payment_count / ssl_payment_number | For installment, from the installments and payment_number gateway specific fields. |
ssl_oar_data / ssl_ps2000_data | For subsequent transactions, from the previous network_transaction_id. Not sent when transacting with an Elavon token. |
4. Accepted values for cit_mit_cof_indicator
cit_mit_cof_indicator| Value | Description |
|---|---|
000 | Not a CIT/MIT credential-on-file transaction |
C01 | Cardholder initiated – credential on file (ad hoc) |
C02 | Cardholder initiated – standing order |
C03 | Cardholder initiated – subscription |
C04 | Cardholder initiated – installment |
M01 | Merchant initiated – unscheduled credential on file (ad hoc) |
M02 | Merchant initiated – standing order |
M03 | Merchant initiated – subscription |
M04 | Merchant initiated – installment |
M05 | Merchant initiated – partial shipment |
M06 | Merchant initiated – related/delayed charge |
M07 | Merchant initiated – no-show charge |
M08 | Merchant 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_flagastrueon 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:
| Value | Meaning |
|---|---|
WEB | Internet-initiated, consumer account (default for personal accounts) |
TEL | Telephone-authorized, consumer account |
PPD | Prearranged payment or deposit, consumer account (written authorization, for example recurring) |
CCD | Corporate 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].
Elavon Documentation: Developer Portal
API Endpoint: https://api.convergepay.com/VirtualMerchant/processxml.do (Production)
Test Endpoint: https://api.demo.convergepay.com/VirtualMerchantDemo/processxml.do (Test)
Updated 15 days ago

