Purchase - dbpurchase

This section describes the message parameters for Debit Card Purchase transaction processing, which you can submit using the XML API integration method. Refer to the Integration Methods section for more information.

The dbpurchase transaction deducts the purchase amount from the debit cardholder’s checking or savings account, debiting the account immediately.

In this section:

For the entire list of API endpoints, refer to API Endpoints.

Request

Field name	Description	Required	Length	Data type
`ssl_merchant_id`	Merchant ID Elavon-assigned Converge Account ID (AID).	Required	6 or 7	numeric
`ssl_user_id`	Converge User ID The user ID with Hosted Payment API User status that can send transaction requests through the terminal.	Required	15	alphanumeric
`ssl_pin`	Terminal ID Unique identifier of the terminal that will process the transaction request and submit to the Converge gateway. The `ssl_user_id` sending the transaction request must be associated with the terminal that will process the request.	Required	64	alphanumeric
`ssl_transaction_type`	Transaction Type Valid value: `dbpurchase`	Required	20	alphanumeric
`ssl_amount`	Transaction Amount The base amount that does not include the Cashback or Tip amount. The system computes for the total amount to send for authorization. Format: Number with 2 decimals places	Required	11	numeric
`ssl_cashback_amount`	Cashback Amount Amount to pay the cardholder for making a debit purchase transaction. Format: Number with 2 decimal places Important: Only applicable to terminals that are set up with the Cashback debit payment option.	Optional	12	numeric
`ssl_tender_amount`	New Discounted Amount Indicates the transaction amount less the discount for the offer, if available.
[Card Data]
`ssl_account_type`	Bank Deposit Account Type Valid values: `0` - Checking `1` - Savings	Required	1	numeric
`ssl_exp_date`	Card’s Expiry Date Date when the card becomes invalid. Format: MMYY	Required	4	numeric
`ssl_track_data`	Raw Track I and/or II Data Track data captured from the card’s magnetic stripe. The data includes beginning and ending sentinels, card’s expiry date, cardholder’s first and last name.	Required	76	alphanumeric
`ssl_enc_track_data`	Encrypted Raw Track I and/or II Data Encrypted Track I and/or II data captured from the card’s magnetic stripe when using an encrypting device. The data includes beginning and ending sentinels, card’s expiry date, cardholder’s first name and last name.	Conditional	160	alphanumeric
`ssl_enc_track_data_format`	Encrypted Raw Track I and/or II Data Format Format of the track data captured from the card’s magnetic stripe. Valid value: `ROAM_GENERIC_TDES_EMV` Required if card is read from a ROAM device.	Conditional	NA	NA
`ssl_ksn`	Key Serial Number Unique identifier generated from the swiped payment card and returned by the encrypting device. The KSN encrypts the PAN data through the DUKPT method. Required if using `ssl_enc_track_data`.	Conditional	20	alphanumeric
[PIN Pad]	Values returned by the PIN Pad device.
`ssl_dukpt`	DUKPT Value used to encrypt the PIN of the cardholder.	Required	20	-
`ssl_key_pointer`	Triple-DES DUKPT Pointer Indicates the encryption key used on US debit transactions. Valid value: `T` - Triple-DES DUKPT	Required	1	alphanumeric
`ssl_pin_block`	Encrypted PIN Block The encrypted personal identification number entered by the debit cardholder to authenticate ownership of the card.	Required	16	-
[Tip Processing]	Use only on terminals that are set up with the Market Segment set to Service
`ssl_tip_amount`	Tip or Gratuity Amount Amount to add to or update the transaction amount. Format: Number with 2 decimal places	Optional	11	numeric
`ssl_server`	Server ID Unique identifier of the clerk, waiter, waitress or cashier.	Optional	8	alphanumeric
`ssl_shift`	Shift ID Unique identifier of the time period, course or service type.	Optional	4	alphanumeric
[Card Verification]	Use only on terminals that are set up with the CVV2, CVC2, CID credit card payment option.
`ssl_cvv2cvc2`	Card Verification Value / Card Validation Code Card security code or number printed on the card and commonly used for card not present payment transactions.	Optional	4	numeric
`ssl_cvv2cvc2_indicator`	Card Verification Value / Card Validation Code Indicator Indicates the status of the card security code or number during the transaction. Valid values: `0` - Bypassed `1` - Present `2` - Illegible `9` - Not Present	Optional	1	numeric
[Doing Business As]	Use only on terminals that are set up with the DBA Name terminal option.
`ssl_dynamic_dba`	Doing Business As Name Merchant-defined descriptors that replace the merchant’s business name on credit card statements. Format: PrefixDescriptor Length:* Prefix = 3, 7, or 12, Asterisk = 1, Descriptor = 21 - (Prefix + Asterisk) Important: DBA Prefix must be set using DBA Payment Fields Settings UI if ssl_dynamic_dba is used. Example: MANYMAG*BAKERS MONTHLY	Conditional	21	alphanumeric
`ssl_dynamic_dba_address`	Dynamic DBA Address The dynamic doing business as street address for this transaction. This value allows a merchant use an alternate address for this transaction.		30	alphanumeric
`ssl_dynamic_dba_auth_type`	Merchant ID The dynamic doing business as authorization type. Valid values: `F` - Final `P` - Pre-authorize		1	alphanumeric
`ssl_dynamic_dba_city`	Dynamic City Name This value allows a merchant use an alternate city as part of the address for this transaction		13	alphanumeric
`ssl_dynamic_dba_country`	Dynamic Country ISO Code This value allows a merchant specify an alternate country as part of the address for this transaction.		3	alphanumeric
`ssl_dynamic_dba_email`	Dynamic Email Address This value allows a merchant specify an alternate email address for this transaction.		70	alphanumeric
`ssl_dynamic_dba_mcc`	Dynamic Merchant Category Code This value allows a merchant specify an alternate merchant category for this transaction.		22	numeric
`ssl_dynamic_dba_phone`	Dynamic Phone Number This value allows a merchant specify an alternate phone number for this transaction.		20	alphanumeric
`ssl_dynamic_dba_postal`	Dynamic Postal or ZIP Code This value allows a merchant set an alternate postal code for a transaction.		9	alphanumeric
`ssl_dynamic_dba_state`	Dynamic State Code This value allows a merchant set an alternate state code for a transaction.		2	alphanumeric
`ssl_dynamic_dba_submid`	Dynamic Sub-merchant ID This value allows a merchant set an alternate sub-merchant ID for a transaction.		22	numeric
`ssl_dynamic_dba_taxid`	Dynamic Merchant Tax ID This value allows a merchant set an alternate Tax ID for this transaction.		14	alphanumeric
[Optional Fields]
`ssl_lane_number`	Lane Number A unique identifier for point of sale devices that can be passed to satisfy Mastercard’s unique Terminal ID requirement	Optional	8	numeric

Response

Field name	Description
`ssl_first_name`	First Name First name on the cardholder’s / customer’s account or billing address.
`ssl_last_name`	Last Name Last name on the cardholder’s / customer’s account or billing address.
`ssl_phone`	Phone Number The card holder’s / customer’s phone number.
`ssl_email`	Email Address The cardholder’s or customer’s email address. Returned based on merchant setup.
`ssl_result`	Transaction Outcome An `ssl_result` = 0 indicates an approved transaction. An `ssl_result` not equal to 0 indicates a declined and unauthorized transaction.
`ssl_result_message`	Transaction Result Message Refer to the Payment Card Response Codes section for an extensive list of possible returned messages.
`ssl_issuer_response`	Original Issuer Response The issuer response returned during the authorization attempt. An `ssl_issuer_response` = 00 indicates success. An `ssl_issuer_response` not equal to 00 indicates a decline or failure.
`ssl_txn_id`	Transaction ID Unique identifier of the transaction.
`ssl_transaction_type`	Transaction Type
`ssl_txn_time`	Processing Date and Time Indicates when Converge processed the transaction. Format: MM/DD/YYYY hh:mm:ss AM/PM Example: 03/18/2022 10:34:10 AM
`ssl_approval_code`	Transaction Approval Code Unique code returned by the credit card processor that indicates the approval status of the transaction.
`ssl_reference_number`	Transaction Reference Number
`ssl_card_short_description`	Short Card Brand Name Valid values are: `MC` and `VISA`.
`ssl_card_type`	Payment Type Valid value: `DEBITCARD`
`ssl_card_number`	Masked Card Number Converge only returns the first 2 or last 4 digits of the regular PAN.
`ssl_exp_date`	Card’s Expiry Date Returned based on merchant setup.
`ssl_account_balance`	Account Balance Account balance on the debit card.
`ssl_account_type`	Bank Deposit Account Type Valid values: `0` - Checking `1` - Savings
`ssl_amount`	Transaction Amount The total transaction amount that may include the Surcharge or Cashback amount.
`ssl_cashback_amount`	Cashback Amount Amount to pay the cardholder for making a debit purchase transaction. Format: Number with 2 decimal places Important: Only applicable to terminals that are set up with the Cashback debit payment option.
`ssl_surcharge_amount`	Surcharge Amount The fee that the merchant charges for the transaction as a cost for doing business. Format: Number with 2 decimal places Important: Only applicable to terminals that are set up with the Surcharge debit payment option.
`ssl_avs_address`	Address Line 1 Commonly the house number and street name on the cardholder’s / customer’s account or billing address. Returned based on merchant setup.
`ssl_address2`	Address Line 2 Apartment or condominium unit number and floor number on the cardholder’s or customer’s account or billing address. Returned based on merchant setup.
`ssl_avs_zip`	Postal or ZIP Code Postal or ZIP code on the cardholder’s or customer’s account or billing address. Returned based on merchant setup.
`ssl_city`	City City name on the cardholder’s / customer’s account or billing address. Returned based on merchant setup.
`ssl_state`	State Code State or province code on the cardholder’s / customer’s account or billing address. Returned based on merchant setup.
`ssl_country`	Country ISO Code Country ISO code on the cardholder’s / customer’s account or billing address. Returned based on merchant setup.
`ssl_promo_list`	Promotion List This contains a list of all promo products; the data for each promo product will be nested and embedded between beginning and ending elements `ssl_promo_product` up to 5 promo products. Each promo product `ssl_promo_product` will contain `ssl_promo_code`, `ssl_promo_code_name`, `ssl_promo_code_description`, and `ssl_promo_code_issue_points`.
`ssl_customer_code`	Customer Code or Purchase Order Number Customer ID or PO number specified in the billing statement of the cardholder.
[Address Verification Service]
`ssl_avs_address`	Address Line 1 Commonly the house number and street name on the cardholder’s / customer’s account or billing address. Address Verification Service (AVS) data compared with the address on the card issuer’s file. Recommended for hand-keyed transactions to qualify for better interchange rates.
`ssl_avs_response`	Address Verification Response Code Refer to the AVS Response Codes section for a complete list of AVS response codes.
[Tip Processing]	Returned only if Tip parameters are sent in the request.
`ssl_base_amount`	Base Amount Original transaction amount sent in the request. Returned based on the terminal setup.
`ssl_tip_amount`	Tip Amount Added or updated tip or gratuity amount. Returned based on the terminal setup.
`ssl_server`	Server ID Server identifier sent in the request. Returned based on the terminal setup.
`ssl_shift`	Shift Shift information sent in the request. Returned based on the terminal setup.
[Error]	Returned only if an error occurs. Refer to the Error Codes section for more information.
`errorCode`	Error Code Typically, when the transaction failed validation or the request is incorrect. This will prevent the transaction from going to authorization. This is a numeric field.
`errorMessage`	Error Message Detailed explanation of the error. This field may be changed based on merchant configuration in the user interface.
`errorName`	Error Name Error name or reason for the error.
[Card On File]
`ssl_oar_data`	Original Authorization Response Data This data will be as received during the original authorization processing. This is a retain and return value for terminal-based settlement messages. You may store this field with the payment details from the transaction to make future Card On File transactions.
`ssl_ps2000_data`	PS2000 This data will be as received during the original authorization processing. This is a retain and return value for terminal-based settlement messages. You must store this field with the payment details from the transaction to make future Card On File transactions.

Examples

important

In all of these examples, you will have to change the data values, such as my_merchant_id, my_user_id, my_pin, and transaction data to match your Converge account and meet the needs of your website.
Code samples provided are for demonstration only and should not be used for live transactions. All sensitive merchant data, including transaction amounts and your Converge credentials, should be placed in server side code.

Basic dbpurchase transaction

Request

xmldata=
<txn>
    <ssl_merchant_id>my_merchant_id</ssl_merchant_id>
    <ssl_user_id>my_user_id</ssl_user_id>
    <ssl_pin>my_pin</ssl_pin>
    <ssl_test_mode>False</ssl_test_mode>
    <ssl_transaction_type>dbpurchase</ssl_transaction_type>
    <ssl_dukpt>654321000040002D</ssl_dukpt>
    <ssl_key_pointer>T</ssl_key_pointer>
    <ssl_pin_block>sc1000I</ssl_pin_block>
    <ssl_track_data>%B5121212121212124^CERTIFICATION-MC/ELAVON^491210199999999900876000000?;5121212121212124=4912101876234567?</ssl_track_data>
    <ssl_account_type>0</ssl_account_type>
    <ssl_cvv2cvc2>123</ssl_cvv2cvc2>
    <ssl_amount>10.00</ssl_amount>
    <ssl_tip_amount>2.00</ssl_tip_amount>
    <ssl_transaction_language>EN</ssl_transaction_language>
    <ssl_server>Test User</ssl_server>
    <ssl_shift>Dinner</ssl_shift>
</txn>

Response

<txn>
   <ssl_issuer_response>00</ssl_issuer_response>
   <ssl_last_name/>
   <ssl_company>Elavon</ssl_company>
   <ssl_phone>8524569514</ssl_phone>
   <ssl_card_number>51**********8745</ssl_card_number>
   <ssl_oar_data/>
   <ssl_result>0</ssl_result>
   <ssl_txn_id>290822C4A-5EF3B8D8-9763-46FA-83EE-4E7DDACCA053</ssl_txn_id>
   <ssl_account_type>Checking</ssl_account_type>
   <ssl_approval_code>896565</ssl_approval_code>
   <ssl_account_status/>
   <ssl_email>myemail@elavon.com</ssl_email>
   <ssl_amount>22.00</ssl_amount>
   <ssl_avs_zip>30000</ssl_avs_zip>
   <ssl_txn_time>08/29/2022 02:33:55 PM</ssl_txn_time>
   <ssl_base_amount>20.00</ssl_base_amount>
   <ssl_address2>Second Address</ssl_address2>
   <ssl_card_short_description/>
   <ssl_tip_amount>2.00</ssl_tip_amount>
   <ssl_country>USA</ssl_country>
   <ssl_card_type>DEBITCARD</ssl_card_type>
   <ssl_access_code/>
   <ssl_transaction_type>PURCHASE</ssl_transaction_type>
   <ssl_avs_address>Test Address</ssl_avs_address>
   <ssl_account_balance>0.00</ssl_account_balance>
   <ssl_ps2000_data/>
   <ssl_reference_number>52435</ssl_reference_number>
   <ssl_state>GA</ssl_state>
   <ssl_city>Atlanta</ssl_city>
   <ssl_result_message>APPROVAL</ssl_result_message>
   <ssl_first_name/>
   <ssl_server>TTest Userest User</ssl_server>
   <ssl_tender_amount/>
   <ssl_partner_app_id>AC</ssl_partner_app_id>
</txn>

Cashback

Request

xmldata=
<txn>
   <ssl_merchant_ID>my_merchant_id</ssl_merchant_ID>
   <ssl_user_id>my_user_id</ssl_user_id>
   <ssl_pin>my_pin</ssl_pin>
   <ssl_transaction_type>dbpurchase</ssl_transaction_type>
   <ssl_pin_block>54C3B8599B753FE5</ssl_pin_block>
   <ssl_ksn>FFFF445566000F000031</ssl_ksn>
   <ssl_key_pointer>T</ssl_key_pointer>
   <ssl_exp_date>1249</ssl_exp_date>
   <ssl_enc_track_data>5A034DF2D8A60C308109EE56BE66479280A49718411AC9F642384CCF1C19C918B31BC1CB707D8EE4F730B8ADFBC26DA61B55F1A76FBFA443177D93262BF698C5BCE6F0EF1DC6016578AC542079C6D17EB0FC870708B461FE3993E9D5855DC9E2</ssl_enc_track_data>
   <ssl_dukpt>FFFF654321005900002C</ssl_dukpt>
   <ssl_account_type>checking</ssl_account_type>
   <ssl_amount>10</ssl_amount>
   <ssl_cashback_amount>3</ssl_cashback_amount>
</txn>

Response

<txn>
   <ssl_surcharge_amount>1.00</ssl_surcharge_amount>
   <ssl_transaction_type>PURCHASE</ssl_transaction_type>
   <ssl_card_number>51**********2124</ssl_card_number>
   <ssl_result>0</ssl_result>
   <ssl_txn_id>080821A3E-2E4E6E35-69AB-4FB1-9127-041A55F15CA1</ssl_txn_id>
   <ssl_account_type>Checking</ssl_account_type>
   <ssl_approval_code>777292</ssl_approval_code>
   <ssl_amount>14.00</ssl_amount>
   <ssl_txn_time>08/08/2021 11:24:12 PM</ssl_txn_time>
   <ssl_account_balance>0.00</ssl_account_balance>
   <ssl_reference_number>00001325</ssl_reference_number>
   <ssl_result_message>APPROVAL</ssl_result_message>
   <ssl_base_amount>10.00</ssl_base_amount>
   <ssl_partner_app_id>01</ssl_partner_app_id>
</txn>

Cash Advance

Apple Pay

Magento Guide

Purchase - dbpurchase

Request

Response

Examples

Basic dbpurchase transaction

Request

Response

Cashback

Request

Response