Purchase - ecspurchase

This section describes the message parameters for Electronic Check Purchase transaction processing, which you can submit using the Hosted Payments, Checkout.js, and XML API integration methods. Refer to the Integration Methods section for more information.

The ecspurchase transaction debits the purchase amount from a checking account.

In this section:

Request

ssl_merchant_id
15 | numeric | required
Merchant ID
Elavon-assigned Converge account ID.
ssl_user_id
15 | alphanumeric | required
Converge User ID
The user ID with Hosted Payment API User status that can send transaction requests through the terminal.
ssl_pin
64 | alphanumeric | required
Terminal ID
Unique identifier of the terminal that will process the transaction request and submit to the Converge gateway.
Important: The ssl_user_id sending the transaction request must be associated with the terminal that will process the request.
ssl_transaction_type
20 | alphanumeric | required
Transaction Type
Value: ecspurchase
ssl_amount
11 | numeric | required
Transaction Amount
The Sale amount that includes the Net and Sales Tax amounts.
For Tip Processing,  the Sale amount must not include the Tip amount.
Format: Number with 2 decimals places
[ECS Paper Check]
Uses a check reader device to capture data.
ssl_micr_data
80 | alphanumeric | required
Unformatted Magnetic Ink Character Recognition Data
The exact MICR line from the check including the spaces and symbols. Replace the symbols with the following letters:
  • T - Transit symbol
  • O - On-US symbol
  • A - Amount symbol
  • D - Dash symbol
ssl_check_image
BLOB | Base64 Encoded TIFF | required
Check Image
Scanned and encoded image of the check.
ssl_drivers_license_number
16 | alphanumeric | conditional
Drivers License Number
Unique identification code as it appears on the license.
Important: Required for Guarantee transactions.
ssl_drivers_license_phone_number
10 | numeric | conditional
Phone Number
Contact number (includes the area code) as it appears on the license.
Important: Required for Guarantee transactions.
ssl_drivers_license_state
2 | alphanumeric | conditional
State Code
State code as it appears on the license.
Important: Required for Guarantee transactions.
[ACH ECheck]
Captures check data manually.
ssl_aba_number
9 | alphanumeric | required
Routing or Transit Number
Unique code assigned to the bank to be able to send and receive funds from other financial institutions.
ssl_bank_account_number
16 | numeric | required
Bank Account Number
Unique identifier of the checking account.
ssl_bank_account_type
1 | numeric | required
Bank Account Type
Indicates the type of checking account.
Valid values:
  • 0 - Personal
  • 1 - Business
ssl_agree
1 | numeric | required
Agreement Indicator
Valid values:
  • 0 - Does not agree
  • 1 - Agrees
ssl_first_name
20 | alphanumeric | conditional
First Name
First name on the cardholder's / customer's account or billing address.
Important: Required if ssl_bank_account_type = 0.
ssl_last_name
30 | alphanumeric | conditional
Last Name
Last name on the cardholder's / customer's account or billing address.
Important: Required if ssl_bank_account_type = 0.
ssl_company
50 | alphanumeric | conditional
Company Name
Company name on the cardholder's / customer's account or billing address.
Important: Required if ssl_bank_account_type = 1.
ssl_check_number
16 | numeric | optional
Check Number
Unique identifier commonly printed at the bottom of the check.
ssl_ecs_product_code
3 | alphanumeric | optional
ACH Processing Option
Overrides the default ACH type specified in Converge.
Valid values:
  • WEB - Web-based Check Processing
    For re-occurring or single Internet-initiated entry processed based on the customer's input of account information at a payment application website
  • TEL - Telephone-based Check Processing
    For re-occurring or single entry in which an Electronic Payment Item is created based on the customer's verbal authorization that is captured through phone
  • PPD - Pre-arranged Payment and Deposit
    For re-occurring or single pre-arranged payment entry to a customer's account pursuant to a written authorization that is obtained from the customer
  • CCD - Corporate Credit or Debit
    A debit entry is initiated by an organization to another organization.
Important:
  • WEB, TEL or PPD is required if ssl_bank_account_type = 0.
  • CCD is required if ssl_bank_account_type = 1.
[Tip Processing]
Use only on terminals that are set up with the Market Segment set to Service.
ssl_tip_amount
11 | numeric | required
Tip or Gratuity Amount
Amount to add or update to the transaction amount.
Format: Number with 2 decimals places
ssl_server
8 | alphanumeric | optional
Server ID
Unique identifier of the clerk, waiter, waitress or cashier.
ssl_shift
4 | alphanumeric | optional
Shift ID
Unique identifier of the time period, course or service type.
[Dynamic DBA]
&nbsp
ssl_dynamic_dba
21 | alphanumeric
Dynamic DBA

The dynamic doing business as name for this transaction.

Lets a merchant specify, on a per-transaction basis, wording that may be more recognizable or more service-specific to the customer than their usual business name preventing chargebacks.

This can prevent chargebacks by preventing users from seeing transactions attached to unrelated names on their payment card statements.

ssl_dynamic_dba_address
30 | alphanumeric
Dynamic DBA Address

The dynamic doing business as street address for this transaction.

This value lets a merchant use an alternate address for this transaction.

ssl_dynamic_dba_auth_type
1 | alphanumeric
Merchant ID

The dynamic doing business as authorization type.

Valid values:

  • F - Final
  • P - Pre-authorize
ssl_dynamic_dba_city
13 | alphanumeric
Dynamic City Name

The dynamic doing business as city name.

This value lets a merchant use an alternate city as part of the address for this transaction

ssl_dynamic_dba_country
3 | alphanumeric
Dynamic Country ISO Code

The dynamic doing business as International Standards Organization country code.

This value lets a merchant specify an alternate country as part of the address for this transaction.

ssl_dynamic_dba_email
70 | alphanumeric
Dynamic Email Address

The dynamic doing business as email address.

This value lets a merchant specify an alternate email address for this transaction.

ssl_dynamic_dba_mcc
22 | numeric
Dynamic Merchant Category Code

The dynamic doing business as merchant category code.

This value lets a merchant specify an alternate merchant category for this transaction.

ssl_dynamic_dba_phone
20 | alphanumeric
Dynamic Phone Number

The dynamic doing business as phone number.

This value lets a merchant specify an alternate phone number for this transaction.

ssl_dynamic_dba_postal
9 | alphanumeric
Dynamic Postal or ZIP Code

The dynamic doing business as postal code.

This value lets a merchant set an alternate postal code for a transaction.

ssl_dynamic_dba_state
2 | alphanumeric
Dynamic State Code

The dynamic doing business as state code.

This value lets a merchant set an alternate state code for a transaction.

ssl_dynamic_dba_submid
22 | numeric
Dynamic Sub-merchant ID

The dynamic doing business as sub merchant ID.

This value lets a merchant set an alternate sub-merchant ID for a transaction.

ssl_dynamic_dba_taxid
14 | alphanumeric
Dynamic Merchant Tax ID

The dynamic doing business as Merchant Tax ID.

This value lets a merchant set an alternate Tax ID for this transaction.

Response

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 Electronic Check Response Codes section for an extensive list of possible returned messages.
ssl_txn_id
 
Transaction ID
Unique identifier of the transaction.
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/2010 10:34:10 AM
ssl_approval_code
 
Transaction Approval Code
Unique code returned that indicates the approval status of the transaction.
ssl_reference_number
 
Transaction Reference Number
 
ssl_amount
 
Total Transaction Amount
The amount includes the Tip amount, if submitted in the request.
Returned based on merchant setup.
ssl_email
 
Email Address
The cardholder's or customer's email address.
Returned based on merchant setup
[ECS Paper Check]
 
ssl_drivers_license_number
 
Drivers License Number
 
ssl_drivers_license_phone_number
 
Phone Number
 
ssl_drivers_license_state
 
State Code
 
[ACH ECheck]
 
ssl_aba_number
 
Routing or Transit Number
Routing or Transit number form the parsed MICR data.
ssl_bank_account_number
 
Bank Account Number
 
ssl_check_number
 
Check Number
 
[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 merchant setup.
ssl_tip_amount
 
Tip Amount
Added or updated tip or gratuity amount.
Returned based on merchant setup.
ssl_server
 
Server ID
Server identifier sent in the request.
Returned based on merchant setup.
ssl_shift
 
Shift
Shift information sent in the request.
Returned based on merchant 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.

Example

error_outline
important
  • In this example, 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.

Request

<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>ecspurchase</ssl_transaction_type>
    <ssl_amount>20.00</ssl_amount>
    <ssl_bank_account_type>0</ssl_bank_account_type>
    <ssl_aba_number>123456789</ssl_aba_number>
    <ssl_bank_account_number>1234567890</ssl_bank_account_number>
    <ssl_agree>1</ssl_agree>
    <ssl_first_name>John</ssl_first_name>
    <ssl_last_name>Doe</ssl_last_name>
</txn>

Response

<txn>
    <ssl_approval_code>NACREN</ssl_approval_code>
    <ssl_agree>1</ssl_agree>
    <ssl_bank_account_type>0</ssl_bank_account_type>
    <ssl_result_message>APPROVAL</ssl_result_message>
    <ssl_aba_number>123456789</ssl_aba_number>
    <ssl_reference_number>212182533</ssl_reference_number>
    <ssl_base_amount>20.00</ssl_base_amount>
    <ssl_amount>20.00</ssl_amount>
    <ssl_txn_id>AA49315-2C70E99A-F9E0-4C65-9339- F8E6AB917B4A</ssl_txn_id>
    <ssl_bank_account_number>12**********7890</ssl_bank_account_num ber>
    <ssl_result>0</ssl_result>
    <ssl_txn_time>02/12/2014 11:25:33 AM</ssl_txn_time>
</txn>