Elavon Converge Developer guide

More than 94 currencies are supported. Refer to the ISO

information.

Converge Developer Guide: Transaction Format

Input Field Name

ssl_ksn ssl_card_number ssl_token ssl_exp_date ssl_amount ssl_pos_mode

CON-0002-N

Req? Description

C Required when sending track data from an encrypting device for payment cards.

(DUKPT) method. It is a 10 byte composite field that is transmitted as 20 alphanumeric character fixed length.

C Required for hand-keyed transactions.

Credit Card Number as it appears on the credit card.

Required for hand-keyed transaction if card number is not sent.

Use only with a terminal that is setup with Tokenization.

Credit Card Token, previously generated from a card number. A token can be stored and used as a substitute for a card number.

Required for hand-keyed transactions.

Credit Card Expiry Date as it appears on credit card formatted as MMYY.

Note: Do not send an expiration date with a token that is stored in the Card Manager.

Transaction Sale Amount. Number with 2 decimal places.

This amount includes the Net amount and Sales Tax.



The authorized amount passed on request should not contain the tip amount, tips must be passed separately. The total authorized amount will be calculated during the authorization if tip is provided. For example: 1.00.

 For those terminals processing Multi-Currency, be sure to submit the correct number of decimal places for the transaction as some currencies have no exponents and some can have three.

Recommended for swiped or contactless transactions

The payment application capability. Valid values are:



02 for Swiped device – Default value when track

Data is sent alone

 03 Proximity / Contactless capable device

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_entry_mode ssl_card_present ssl_avs_zip ssl_avs_address ssl_cvv2cvc2 ssl_cvv2cvc2_indicator ssl_invoice_number ssl_description ssl_customer_code ssl_salestax

Req? Description

N Recommended for swiped or contactless transactions

The transaction entry indicator to indicate how the track data was captured. Valid values are:



03 = Swiped – Default value when track Data is sent alone

 04 = Proximity / Contactless

N Recommended for hand-keyed transactions.

Recommended to be passed on hand-keyed transactions to indicate if the card was present at the time of the transaction. Valid values: Y or N. Example: Card present of Y in hand-keyed retail and service environments.

N Recommended for hand-keyed transactions.

Cardholder ZIP code.

Recommended for hand-keyed transactions.

Cardholder Address.

Recommended for hand-keyed transactions.

The credit card security code is a three-digit or four-digit number, printed either on the back or the front of the card.

When CVV data is passed, it is compared to the cardholder‘s CVV data that the card issuer has on file, a

CVV Response Code is then returned.

Recommended for hand-keyed transactions.

The CVV2/CVC/CID indicator is one numeric value that should be passed with the CVV value (ssl_cvv2cvc2) to indicate if the CVV is present in the request. Valid values are:

 0 for Bypassed



1 for Present

 2 for Illegible



9 for Not Present

The invoice or ticket number.

The description, merchant defined value.

Recommended for purchasing cards.

The Customer Code or PO Number that appears on the cardholder's credit card billing statement.

Recommended for purchasing cards.

Sales tax amount applied to this transaction in decimal.

Tax exempt transactions can pass 0.00 to properly reflect a tax exempt transaction.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_tip_amount ssl_server ssl_shift ssl_dynamic_dba ssl_partial_auth_indicator

Req? Description

N Use only in a Service market segment

Tip or gratuity amount to be added, must be 2 decimal places, can be 0.00 to reset or remove the original tip from a transaction. Example: 1.00.

Use only in a Service market segment

Server ID, this is the clerk, cashier, and waiter or waitress identification number.

Alphanumeric, Example: Jack.

Use only in a Service market segment.

Shift, can refer to or be used to identify time period, course or type of service.

Alphanumeric, Example: Lunch.

User only with a terminal that is setup with DBA.

DBA Name provided by the merchant with each transaction. The maximum allowable Length of DBA

Name variable provided by Merchant can be 21, 17 or 12 based on the length setup for the DBA constant in the field setup.

The partial indicator flag must be sent to indicate that the application supports partial approval.

Valid values:

 0 – Partial Auth not supported



1 – Partial Auth supported ssl_recurring_flag ssl_payment_number ssl_payment_count

Use only when maintaining your own recurring and

installment database.

The recurring flag must be sent to indicate if a credit card sale transaction is a recurring or an installment payment.

Valid values:



1=Recurring



2=Installment

Note: When the flag is indicated as Installment, the payment number and payment count must be passed.

Use only when maintaining your own recurring and

installment database.

Installment Sequence Number (Payment Number).

Use only when maintaining your own recurring and

installment database.

Installment Count (total number of payments).

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_departure_Date ssl_completion_Date ssl_transaction_currency ssl_get_token ssl_add_token

Req? Description

N Use only with a terminal that is setup with Travel Data.

Date of the departure. Format MM/DD/YYYY. This field will be sent to the MARMS system to monitor risk associated with advanced booking. Examples include airlines and travel or tour agencies. Only used when setup with option for MARMS.

Use only with a terminal that is setup with Travel Data.

Date of the completion of travel. Format MM/DD/YYYY.

This field is sent to the MARMS system to monitor risk associated with advanced booking. Examples include airlines and travel or tour agencies. Only used when setup with Travel Data option for MARMS.

Use only with a terminal that is setup with Multi-

Currency.

Transaction currency alphanumeric code must be included in the request to indicate the currency in which you wish to process. If omitted, the terminal default currency is assumed (for example: USD, CAD, and JPY).

Currency Codes section for an extensive list of available

currencies.

Use only with a terminal that is setup with Tokenization.

Generate Token indicator, used to indicate if you wish to generate a token when passing card data. Valid value: Y

(generate a token), N (do not generate token). Defaulted to N.

Once generated, the token number can be stored and used as a substitute for a card number at later time.

Use only with a terminal that is setup with Tokenization.

Add to Card Manager indicator, used to indicate if you wish to generate a token and store it in Card Manager.

Valid value: Y (add token) , N (do not add token)

Defaulted to N

To add the token to the card manager you must send the card data and cardholder first/last name, those are required. Once stored to Card Manager, the token number can be sent alone and will be used as a substitute for the stored information.

Converge Developer Guide: Transaction Format

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id ssl_txn_time ssl_approval_code ssl_amount ssl_base_amount ssl_tip_amount ssl_requested_amount ssl_balance_due ssl_account_balance ssl_card_number ssl_avs_response ssl_cvv2_response

CON-0002-N

Description

Outcome of a transaction. A response that contains ssl_result

of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized.

Transaction result message. Example: APPROVAL, PARTIAL

APPROVAL. Refer to the Authorization Response Codes section

for an extensive list of possible returned messages.

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10

AM.

Transaction approval code.

The total transaction authorized or approved amount. This amount will include tip if tip has been provided in the request.

Returned based on merchant setup.

Base amount. Transaction amount sent originally on the request.

Returned based on merchant setup. Returned in a Service market segment.

Tip or gratuity amount that was added or updated. Returned based on merchant setup. Returned in a Service market segment.

The amount originally requested on partial approvals only.

Remaining balance due in the ssl_balance_due field. This is the difference of the amount requested versus the amount authorized that the merchant has to collect from the consumer on partial approvals only.

The balance left in card, which is always 0.00 for a partially authorized transaction.

Masked card number for this transaction. Only first 2 / last 4 digits will be returned for regular PAN or the last four (4) digits from the actual card number if it is an association token

(Example: ApplePay).

The Address Verification Response Code (refer to the AVS

Response Codes section for a complete list of AVS response

codes).

The Card Verification Response Code (refer to the CVV2/CVC2

Response Codes section for a complete list of CVV/CVC2

response codes).

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_invoice_number ssl_conversion_rate

Description

The invoice or ticket number sent originally on the request.

Returned based on merchant setup.

Only returned on DCC transactions. ssl_cardholder_currency ssl_cardholder_amount

Only returned on DCC transactions.

Total amount in cardholder currency, only returned on DCC transactions. ssl_cardholder_base_amount Base amount in cardholder currency, only returned on DCC transactions. ssl_cardholder_tip_amount Tip amount in cardholder currency, only returned on DCC transactions with Service market segment. ssl_server

Server ID submitted with the request. Only returned on Service market segment based on the merchant setup. ssl_shift Shift information submitted with the request. Only returned on

Service market segment based on the merchant setup. ssl_eci_ind ssl_transaction_currency

Only returned on 3D Secure transactions.

Valid values:



Fully Authenticated

 Authentication Attempted

Transaction currency. Returned only if terminal is setup for

Multi-Currency. ssl_card_short_description

Card description, valid values are: AMEX, CUP, DISC, MC,

PP, VISA. ssl_card_type ssl_token ssl_token_response ssl_add_token_response

Card type, valid values are: CASH, CREDITCARD, DEBITCARD,

FOODSTAMP, GIFTCARD or LOYALTY.

Credit Card Token generated from the card number. A token can be stored and used as a substitute for a card number.

Returned only if generating a token is requested in a terminal that is setup for Tokenization.

Outcome of the token generation. This value will be a SUCCESS if a token has been generated. Other possible returned values are FAILURE, Action Not Permitted, Invalid Token, Not Permitted, or Acct Verification Failed.

Returned only if generating a token is requested in a terminal that setup for Tokenization.

Outcome of the Add to Card Manager request, examples: Card

Added, Card Updated, Not Permitted, or FAILURE - First Name - is required.

Returned only if storing token is requested in a terminal that setup for Tokenization.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_promo_list errorCode errorMessage errorName

Description

The promo list will contain 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

Error code returned only if an error occurred. 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. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant

configuration in the user interface. Refer to the Error Codes

section for more information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Examples

Important:

 In all of these examples, you will have to change the data values, such as my_virtualmerchant_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.

Converge Developer Guide: Transaction Format CON-0002-N

Example 1: process.do (true)

In this example, the code demonstrates the initiation of a minimal sale transaction in which

Converge payment form gathers the entire customer’s billing information. ssl_merchant_id=my_vid_id ssl_user_id=my_user_id ssl_pin=my_pin ssl_show_form=true ssl_amount=1.00 ssl_result_format=HTML ssl_transaction_type=ccsale

Example 2: process.do (false)

The following example demonstrates the key value pairs from the header by themselves for a credit card sale transaction where the merchant collects all the data ssl_merchant_id=my_vid_id ssl_user_id=my_user_id ssl_pin=my_pin ssl_show_form=false ssl_card_number=0000000000000000 ssl_exp_date=1208 ssl_amount=1.00 ssl_error_url=http://www.url.com/cgi-bin/testtran.cgi ssl_result_format=HTML ssl_transaction_type=ccsale ssl_receipt_decl_method=REDG ssl_receipt_decl_get_url=http://www.url.com/cgi-bin/testtran.cgi

Converge Developer Guide: Transaction Format CON-0002-N

By specifying the http://www.url.com/cgi-bin/testtran.cgi url in the ssl_apprvl_get_url

field for the redirect for the transaction above, the following values are returned for the approved transaction: ssl_card_number=00********0000 ssl_exp_date=1208 ssl_amount=1.00 ssl_result=0 ssl_result_message=APPROVAL ssl_txn_id=1016413275E60BB4EC-B4C6-FD4D-A878-F70C3372C986 ssl_approval_code=CVI368 ssl_account_balance=1.00 ssl_txn_time=10/05/2008 10:50:55 AM

By specifying the http://www.url.com/cgi-bin/testtran.cgi url in the ssl_error_url

field for the redirect for the transaction above, for example, the following error is returned if one of the credentials in the request is invalid: errorCode=4025 errorName= Invalid Credentials errorMessage= The credentials supplied in the authorization request are invalid

Converge Developer Guide: Transaction Format CON-0002-N

Example 3: process.do (false)with AVS and CVV2/CVC2

The following code is similar to Example 2, including additional fields required to pass AVS data and CVV2/CVC2 data: ssl_merchant_id=my_vid_id ssl_user_id=my_user_id ssl_pin=my_pin ssl_show_form=false ssl_transaction_type=ccsale ssl_amount=12.77 ssl_card_number=0000000000000000 ssl_exp_date=1208 ssl_cvv2cvc2_indicator=1 ssl_cvv2cvc2=123 ssl_avs_address=123 Main Street ssl_avs_zip=99999 ssl_error_url=http://www.url.com/cgi-bin/testtran.cgi ssl_result_format=HTML ssl_receipt_decl_method=REDG ssl_receipt_decl_get_url=http://www.url.com/cgi-bin/testtran.cgi ssl_receipt_apprvl_method=REDG ssl_receipt_apprvl_get_url=http://www.url.com/cgibin/testtran.cgi

Converge Developer Guide: Transaction Format CON-0002-N

Example 4: process.do with Receipt

The following example passes receipt options in the transaction request to generate a receipt on the payment form to your customer with a link to return to your page: ssl_merchant_id=my_vid_id ssl_user_id=my_user_id ssl_pin=my_pin ssl_show_form=false ssl_transaction_type=ccsale ssl_amount=5.00 ssl_card_number=0000000000000000 ssl_exp_date=1208 ssl_cvv2cvc2_indicator=1 ssl_cvv2cvc2=123 ssl_avs_address=123 Main Street ssl_avs_zip=99999 ssl_invoice_number=123-ABC [email protected] ssl_result_format=HTML ssl_receipt_decl_method=POST ssl_receipt_decl_post_url=http://www.website.com/decline.asp ssl_receipt_apprvl_method=GET ssl_receipt_apprvl_get_url=http://www.website.com/approval.asp ssl_receipt_link_text=Continue

Converge Developer Guide: Transaction Format CON-0002-N

This generates a receipt that includes the following code for an approved transaction:

This is your Receipt<br><br>

…

<!--The visible portion of your receipt will appear here, according to the configuration settings you applied in the

Converge administrative Website.-->

…

<input type="hidden" name="ssl_txn_id" value="99C7884A-EDB6-

4256-BE69-4547B8859D5B">

<br>

</form>

Converge Developer Guide: Transaction Format CON-0002-N

The result could be a form that includes the following code for a declined transaction:

<b>An Error Occurred</b><br><br>

Number: 1<br>

Message: This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.<br>

<input type="hidden" name="ssl_txn_id" value="B6637C93-CA38-41C5-

951A-C995BFFBD708">

<br>

</form>

Example 5: process.do (form) with ASCII

The following code passes receipt options in the transaction request to allow you to generate your own receipt based on ASCII values being returned: ssl_merchant_id=my_virtualmerchant_id ssl_user_id=my_user_id ssl_pin=my_pin ssl_show_form=false ssl_transaction_type=ccsale ssl_amount=5.00 ssl_invoice_number=123-ABC [email protected] ssl_card_number= 0000000000000000 ssl_exp_date=1215 ssl_result_format=ASCII

Converge Developer Guide: Transaction Format CON-0002-N

This generates a receipt that includes the following key value pairs for an approved transaction: ssl_result=0 ssl_result_message=APPROVAL ssl_txn_id=9621F9AD-E49E-4003-91BD-5C1B08569959 ssl_approval_code=N54032 ssl_cvv2_response=M ssl_avs_response=A ssl_invoice_number=123-ABC ssl_amount=5.00 ssl_card_number=00*******0000 ssl_exp_date=0000 [email protected]

A declined transaction will generate a receipt that includes the following key value pairs: ssl_result=0 ssl_result_message=DECLINED ssl_txn_id=10164132759743E096-C5C1-C6A3-7DE4-FE9525313D47 ssl_approval_code= ssl_cvv2_response= ssl_avs_response= ssl_invoice_number=123-ABC ssl_amount=5.00 ssl_card_number=00*******0000 ssl_exp_date=0000 [email protected]

Converge Developer Guide: Transaction Format CON-0002-N

Example 6: process.do (false) Redirect

The following example passes receipt options in the transaction request to redirect the customer to your own receipt on the website specified: ssl_amount=5.00 ssl_merchant_id=my_virtualmerchant_id ssl_user_id=my_user_id ssl_pin=my_pin ssl_transaction_type=ccsale ssl_show_form=false ssl_invoice_number=123-ABC [email protected] ssl_card_number=00000000000000000 ssl_exp_date=1214 ssl_result_format=HTML ssl_receipt_decl_method="REDG ssl_receipt_decl_get_url=http://www.website.com/decline.asp ssl_receipt_apprvl_method=REDG ssl_receipt_apprvl_get_url=http://www.website.com/approval.asp

The customer would be redirected to http://www.website.com/approval.asp for an

Approved transaction or to http://www.website.com/decline.asp for a Declined

transaction. Transaction data will be passed along as GET variables in the query string of the URL.

Converge Developer Guide: Transaction Format CON-0002-N

Example 7: process.do (false) Partially Approved Transaction

This demonstrates an example of a request with partial approval indicator: ssl_amount=10.10 ssl_merchant_id=my_virtualmerchant_id ssl_user_id=my_user_id ssl_pin" value=my_pin ssl_transaction_type=ccsale ssl_partial_auth_indicator=1 ssl_show_form=true ssl_invoice_number" value="123-ABC [email protected] ssl_card_number=0000000000000000 ssl_exp_date=1214 ssl_result_format=HTML ssl_receipt_decl_method=REDG ssl_receipt_decl_get_url=http://www.website.com/decline.asp ssl_receipt_apprvl_method=REDG ssl_receipt_apprvl_get_url=http://www.website.com/approval.asp

Converge Developer Guide: Transaction Format CON-0002-N

The issuer in this case has indicated that the card balance did not cover the entire amount requested; however, the transaction was approved partially. The application must collect the remainder of the amount by initiating a new transaction:

This is your Receipt<br><br>

…

<!--The visible portion of your receipt will appear here, according to the configuration settings you applied in the

Converge administrative Website.-->

…

<input type="hidden" name="ssl_result_message" value="PARTIAL

APPROVAL">

<input type="hidden" name="ssl_txn_id" value="99C7884A-EDB6-

4256-BE69-4547B8859D5B">

<br>

</form>

Converge Developer Guide: Transaction Format CON-0002-N

Example 8: processxml.do

The following XML code example demonstrates the initiation of a basic Sale transaction request and response.

In the case of XML, no additional information can be collected by Converge when the request is sent. All required data must be sent in the transaction request to process the transaction. xmldata=<txn><ssl_merchant_id>my_virtualmerchant_id</ssl_merchant_id

<ssl_user_id>my_user</ssl_user_id><ssl_pin>my_pin</ssl_pin>

<ssl_test_mode>false</ssl_test_mode><ssl_transaction_type>ccsale

</ssl_transaction_type><ssl_card_number>00*********0000

</ssl_card_number><ssl_exp_date>1215</ssl_exp_date><ssl_amount>1.00

</ssl_amount>

</txn>

The Response generated will look similar to the following: xmldata=<txn>

<ssl_card_number>00********0000</ssl_card_number>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_amount>1.00</ssl_amount>

<ssl_result>0</ssl_result>

<ssl_result_message>APPROVAL</ssl_result_message>

<ssl_txn_id>101641221593ACBA6-BAFD-76B7-4948-

B3DE68CFD0CC</ssl_txn_id>

<ssl_approval_code>CMC142</ssl_approval_code>

<ssl_account_balance>1.00</ssl_account_balance>

<ssl_txn_time>01/20/2011 01:07:23 PM</ssl_txn_time>

</txn>

Converge Developer Guide: Transaction Format CON-0002-N

Example 9: processxml.do Partial Approved Transaction

The point of sale application will send a partial approval of 1 to indicate the support of partial approval processing. The requested amount is sent per current functionality in the ssl_amount field.

The Initial Request will show the following: 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>ccsale</ssl_transaction_type>

<ssl_card_number>0000000000000000</ssl_card_number>

<ssl_exp_date>1212</ssl_exp_date>

<ssl_amount>10.10</ssl_amount>

<ssl_cvv2cvc2_indicator>1</ssl_cvv2cvc2_indicator>

<ssl_first_name>Test</ssl_first_name>

<ssl_partial_auth_indicator>1</ssl_partial_auth_indicator>

</txn>

If the balance on a card is not enough to cover for the entire purchase, the point of sale application must be able to read the additional returned fields and collect balance that remains by other means. In this case, the amount requested was 10.10 and only 10.05 was approved. The integrated application must display the balance left to pay as 0.05. xmldata=<txn>

<ssl_card_number>00********0000</ssl_card_number>

<ssl_exp_date>1212</ssl_exp_date>

<ssl_amount>10.05</ssl_amount>

<ssl_requested_amount>10.10</ssl_requested_amount>

<ssl_balance_due>0.05</ssl_balance_due>

<ssl_result>0</ssl_result>

<ssl_result_message>PARTIAL APPROVAL</ssl_result_message>

<ssl_txn_id>AA48439-9D9AFF76-AFEC-0B8D-DC7F-

43A5F97BF81B</ssl_txn_id>

<ssl_approval_code>CVI788</ssl_approval_code>

<ssl_account_balance>0.00</ssl_account_balance>

<ssl_txn_time>10/25/2011 10:49:52 PM</ssl_txn_time>

</txn>

Converge Developer Guide: Transaction Format CON-0002-N

If the consumers indicate that they do not wish to continue with the additional tender type, the point of sale application must send a reversal to cancel this payment and reestablish the balance back to the card. A reversal can be achieved by sending a delete in terminal-based terminals or void in host-based terminals. 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>ccdelete</ssl_transaction_type>

<ssl_txn_id>AA48439-9D9AFF76-AFEC-0B8D-DC7F-

43A5F97BF81B</ssl_txn_id>

</txn>

Example 10: processxml.do Sale with Tip Transaction

The following XML code example demonstrates the initiation of a Sale transaction with tip in the

Service market segment.

Notes:

Provide the following information in order to add a tip or gratuity amount at the time of the transaction:



The amount to be authorized in the ssl_amount field.



The tip amount you wish to add to the amount to be authorized in the ssl_tip_amount

field.

 The Server ID in the ssl_server field.



The Shift in the ssl_shift field.

Converge Developer Guide: Transaction Format CON-0002-N

In this example the Sale amount is 10.00, the tip amount is 2.00. Please do not provide the total amount in the request. xmldata=<txn>

<ssl_merchant_id>my_virtualmerchant_id</ssl_merchant_id>

<ssl_user_id>my_user</ssl_user_id>

<ssl_pin>my_pin</ssl_pin>

<ssl_test_mode>false</ssl_test_mode>

<ssl_transaction_type>ccsale</ssl_transaction_type>

<ssl_card_number>0000000000000000</ssl_card_number>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_amount>10.00</ssl_amount>

<ssl_tip_amount>2.00</ssl_tip_amount>

<ssl_shift>dinner</ssl_shift>

<ssl_server>Joe123</ssl_server>

</txn>

The Sale amount is then added to the tip amount and sent for authorization, an approval will be returned to the integrated application. The following information is returned in the response:



The total amount that has been authorized in the ssl_amount field.

 The original Sale amount in the ssl_base_amount field.



The tip amount provided in the in the ssl_tip_amount field.

 The authorization data (response message, approval code). xmldata=<txn>

<ssl_result>0</ssl_result>

<ssl_approval_code>N25032</ssl_approval_code>

<ssl_result_message>APPROVAL</ssl_result_message>

<ssl_txn_id>TEST43B-D0638677-26EB-40F5-B2F9-

3AF2545DE144</ssl_txn_id>

<ssl_txn_time>10/03/2012 10:25:03 PM</ssl_txn_time>

<ssl_card_number>00********0000</ssl_card_number>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_base_amount>10.00</ssl_base_amount>

<ssl_amount>12.00</ssl_amount>

<ssl_tip_amount>2.00</ssl_tip_amount>

<ssl_shift>dinner</ssl_shift>

<ssl_server>Joe1</ssl_server>

</txn>

Converge Developer Guide: Transaction Format CON-0002-N

Example 11: processxml.do Sale with currency

The following XML code example demonstrates the initiation of a Sale transaction with currency: xmldata=<txn>

<ssl_merchant_id>my_virtualmerchant_id</ssl_merchant_id>

<ssl_user_id>my_user</ssl_user_id>

<ssl_pin>my_pin</ssl_pin>

<ssl_test_mode>false</ssl_test_mode>

<ssl_transaction_type>ccsale</ssl_transaction_type>

<ssl_card_number>0000000000000000</ssl_card_number>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_amount>200</ssl_amount>

<ssl_transaction_currency>JPY</ssl_transaction_currency>

<ssl_invoice_number>XMLXSSJPYNVISA20-200</ssl_invoice_number>

</txn>

Notes:



When specifying amounts, be sure to submit the correct number of decimal places for the transaction currency.



For Japanese Yen, there are no currency exponents after the decimal place. Any numbers included after the decimal place will be dropped.



For those currencies with 3 possible digits, for example: Bahraini Dinar, we will automatically round the transaction to two decimals. (for example: 1.235 will round to

1.23.

Converge Developer Guide: Transaction Format CON-0002-N

Converge will process and settle this transaction in JPY. The following information is returned in the response:

<txn>

<ssl_approval_code>CVI032</ssl_approval_code>

<ssl_cvv2_response />

<ssl_exp_date>1222</ssl_exp_date>

<ssl_result_message>APPROVAL</ssl_result_message>

<ssl_invoice_number>XMLXSSJPYNVISA20-200</ssl_invoice_number>

<ssl_amount>200</ssl_amount>

<ssl_transaction_currency>JPY</ssl_transaction_currency>

<ssl_result>0</ssl_result>

<ssl_txn_id>AA47AE-BD32FF54-BE12-4046-98E9-

F78E9D75212D</ssl_txn_id>

<ssl_card_number>00**********0000</ssl_card_number>

<ssl_txn_time>11/19/2013 12:02:29 AM</ssl_txn_time>

</txn>

Credit Card Auth Only (ccauthonly)

The ccauthonly is used to obtain a real-time authorization for a credit card transaction. This transaction will guarantee that the funds are available on the card and reduce the cardholder‘s limit to buy for only a predetermined amount of time. This is usually 7-10 days based on the credit card’s issuing bank; however it will not place the authorization in the batch for settlement.

To place the transaction in the open batch, it must be converted to Sale using cccomplete, or reversed using ccdelete to restore the funds back to the card.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_show_form

Req? Description

Credit Card Auth Only (ccauthonly).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Set value to true to show the Converge Payment Form

(available only for process.do), set to false otherwise.

Converge Developer Guide: Transaction Format

Input Field Name

ssl_track_data ssl_ksn ssl_card_number ssl_token ssl_exp_date

CON-0002-N

Req? Description

C Required for swiped or contactless (MSD) transactions.

The raw track I and/or II data from the magnetic strip on the card. The track data captured from the swipe device cannot be manipulated and must be passed at the time of the transaction. This includes the beginning and ending sentinels that are included in the track data. Raw track data cannot be stored under any circumstance.

Expiration date is included with a track data. First and last name of the Cardholder is also included with the

Track I data.

Notes:

 If using a Magtek encrypting device, pass the encrypted track data in the ssl_encrypted_track1_data

and/or ssl_encrypted_track2_data



If using an Ingenico encrypting device, pass the encrypted track data in the ssl_enc_track_data



More than 94 currencies are supported. Refer to the ISO

information.

Required when sending track data from an encrypting device for payment cards.

(DUKPT) method. It is a 10 byte composite field that is transmitted as 20 alphanumeric character fixed length.

Required for hand-keyed transactions.

Credit card number as it appears on the credit card.

Required for hand-keyed transaction if card number is not sent.

Use only with a terminal that is setup with Tokenization.

Credit Card Token, previously generated from a card number. A token can be stored and used as a substitute for a card number.

C Required for hand-keyed transactions.

Credit Card Expiry Date as it appears on credit card formatted as MMYY.

Note: Do not send an expiration date with a token that is stored in the Card Manager.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_amount ssl_pos_mode ssl_entry_mode ssl_card_present ssl_avs_zip ssl_cvv2cvs2 ssl_cvv2cvs2_indicator ssl_invoice_number ssl_description

Req? Description

Y Transaction Auth Amount. Number with 2 decimal places. This amount includes the Net amount and Sales

Tax.

For those terminals processing Multi-Currency, be sure to submit the correct number of decimal places for the transaction as some currencies have no exponents and some can have three.

Recommended for swiped or contactless transactions

The payment application capability. Valid values are:

 02 for Swiped device – Default value when track

Data is sent alone



03 Proximity / Contactless capable device

Recommended for swiped or contactless transactions

The transaction entry indicator to indicate how the track data was captured. Valid values are:

 03 = Swiped – Default value when track Data is sent alone



04 = Proximity / Contactless

Recommended for hand-keyed transactions.

Cardholder ZIP code.

Recommended for hand-keyed transactions.

Cardholder Address.

Recommended for hand-keyed transactions.

The CVV2/CVC/CID indicator is one numeric value that should be passed with the CVV value (ssl_cvv2cvc2) to indicate if the CVV is present in the request. Valid values are:

 0 for Bypassed



1 for Present

 2 for Illegible



9 for Not Present

The invoice or ticket number.

The description, merchant defined value.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_customer_code ssl_salestax ssl_dynamic_dba ssl_partial_auth_indicator

Req? Description

N Recommended for purchasing cards.

The Customer Code or PO Number that appears on the cardholder's credit card billing statement.

Recommended for purchasing cards.

Sales tax amount applied to this transaction in decimal.

Tax exempt transactions can pass 0.00 to properly reflect a tax exempt transaction.

Use only with a terminal that is setup with DBA.

DBA name provided by the merchant with each transaction. The maximum allowable length of DBA

Name variable provided by the merchant can be 21, 17 or 12 based on the length setup for the DBA constant in the field setup.

The partial indicator flag must be sent to indicate that the application supports partial approval.

Valid value: 1. ssl_departure_date N ssl_completion_date ssl_transaction_currency

User only with a terminal that is setup with Travel Data.

Used only with a terminal that is setup with Travel Data.

Date of the completion of travel. Format MM/DD/YYYY.

Optional. This field is sent to the MARMS system to monitor risk associated with advanced booking.

Examples include airlines and travel or tour agencies.

Only used when setup with Travel Data option for

MARMS.

Use only with a terminal that is setup with Multi-

Currency.

Transaction currency alphanumeric code must be included in the request to indicate the currency in which you wish to process. If omitted the terminal default currency is assumed (for example: USD, CAD, and JPY).

Currency Codes section for an extensive list of available

currencies.

Converge Developer Guide: Transaction Format

Input Field Name

ssl_get_token ssl_add_token

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id ssl_txn_time ssl_approval_code ssl_amount ssl_requested_amount

CON-0002-N

Req? Description

N Use only with a terminal that is setup with Tokenization.

Generate Token indicator, used to indicate if you wish to generate a token when passing card data. Valid value:

Y (generate a token), N (do not generate token).

Defaulted to N.

Once generated, the token number can be stored and used as a substitute for a card number at later time.

N Use only with a terminal that is setup with Tokenization.

Add to Card Manager indicator, used to indicate if you wish to generate a token and store it in Card Manager.

Valid value: Y (add token) , N (do not add token)

Defaulted to N

To add the token to the card manager you must send the card data and cardholder first/last name, those are required. Once stored to Card Manager, the token number can be sent alone and will be used as a substitute for the stored information.

Description

Authorization Response Codes section for an extensive list of

possible returned messages.

Transaction result message. Example: APPROVAL, PARTIAL

APPROVAL. Refer to the Authorization Response Codes section

for an extensive list of possible returned messages.

Transaction identification number. This is a unique number used to identify the transaction. This value can be used to complete the

Auth Only transaction.

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10

AM.

Transaction approval code.

Transaction authorized or approved amount. Returned based on merchant setup.

The amount originally requested on partial approvals only.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_balance_due ssl_account_balance ssl_avs_response

Description

The balance left on the card, which is always 0.00 for a partially authorized transaction.

The Address Verification Response Code (refer to the AVS

Response Codes section for a complete list of AVS response

codes). ssl_cvv2_response ssl_card_number ssl_invoice_number ssl_conversion_rate

The Card Verification Response Code (refer to the CVV2/CVC2

Response Codes section for a complete list of CVV/CVC2

response codes).

Masked card number for this transaction. Only first 2 / last 4 digits will be returned for regular PAN or the last four (4) digits from the actual card number if it is an association token (Example:

ApplePay).

The invoice or ticket number sent originally on the request.

Returned based on merchant setup.

Only returned on DCC transactions. ssl_eci_ind ssl_transaction_currency

Only returned on 3D Secure transactions.

Valid values:



Fully Authenticated



Authentication Attempted

Transaction currency. Returned only if terminal is setup for Multi-

Currency. ssl_card_short_description Card description, valid values are: AMEX, CUP, DISC, MC, PP, VISA. ssl_card_type Card type, valid values are: CASH, CREDITCARD, DEBITCARD,

FOODSTAMP, GIFTCARD or LOYALTY. ssl_token Credit Card Token generated from the card number. A token can be stored and used as a substitute for a card number.

Returned only if generating a token is requested in a terminal that is setup for Tokenization. ssl_token_response Outcome of the token generation. This value will be a SUCCESS if a token has been generated. Other possible returned values are

FAILURE, Action Not Permitted, Invalid Token, Not Permitted, or

Acct Verification Failed.

Returned only if generating a token is requested in a terminal that setup for Tokenization.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_add_token_response errorCode errorMessage errorName

Description

Outcome of the Add to Card Manager request, examples: Card

Added, Card Updated, Not Permitted, or FAILURE - First Name - is required.

Returned only if storing token is requested in a terminal that setup for Tokenization.

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant

configuration in the user interface. Refer to the Error Codes

section for more information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Examples

Important:



In all of these examples, you will have to change the data values, such as my_virtualmerchant_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, rather than in hidden value fields on an HTML form.

Converge Developer Guide: Transaction Format CON-0002-N

Example 1: process.do (false)

Shown below are the key value pairs from the header by themselves for a credit card Auth Only transaction: ssl_merchant_id=xxxxxx ssl_user_id=xxxxxxx ssl_pin=xxxxxx ssl_show_form=false ssl_card_number=0000000000000000 ssl_exp_date=1208 ssl_amount=1.00 ssl_error_url=http://www.url.com/cgi-bin/testtran.cgi ssl_result_format=HTML ssl_transaction_type=ccauthonly ssl_receipt_decl_method=REDG ssl_receipt_decl_get_url=http://www.url.com/cgi-bin/testtran.cgi ssl_receipt_apprvl_method=REDG ssl_receipt_apprvl_get_url=http://www.url.com/cgi-bin/testtran.cgi

Converge Developer Guide: Transaction Format CON-0002-N

By specifying the http://www.url.com/cgi-bin/testtran.cgi url in the ssl_apprvl_get_url

By specifying the http://www.url.com/cgi-bin/testtran.cgi url in the ssl_error_url

Example 2: process.do(true)

This example demonstrates the initiation of a minimal Auth Only transaction in which Converge payment form gathers the entire customer’s billing information. ssl_merchant_id=my_virtualmerchant_id ssl_user_id=my_user_id ssl_pin=my_pin ssl_transaction_type=ccsale ssl_show_form=true ssl_amount=5.00

Note: In all of these examples, you will have to change the data values, such as my_virtualmerchant_id

, my_user_id, my_pin, and the amount of 5.00 to values that match your Converge account and meet the needs of your websites.

Converge Developer Guide: Transaction Format CON-0002-N

Example 3: processxml.do

The following XML code example demonstrates the initiation of a basic Auth Only transaction. In the case of XML, no additional information can be collected by Converge when the request is sent. All required data must be sent in the transaction request to process the transaction:

<txn>

<ssl_merchant_ID>my_virtualmerchant_id</ssl_merchant_ID>

<ssl_user_id>my_user_id</ssl_user_id>

<ssl_pin>my_pin</ssl_pin>

<ssl_description>Auth for 3.00</ssl_description>

<ssl_transaction_type>CCAUTHONLY</ssl_transaction_type>

<ssl_card_number>0000000000000000</ssl_card_number>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_amount>3.00</ssl_amount>

<ssl_salestax>0.01</ssl_salestax>

<ssl_cvv2cvc2_indicator>1</ssl_cvv2cvc2_indicator>

<ssl_cvv2cvc2>123</ssl_cvv2cvc2>

<ssl_customer_code>CORP</ssl_customer_code>

<ssl_invoice_number>1234</ssl_invoice_number>

<ssl_first_name>John</ssl_first_name>

<ssl_last_name>Doe</ssl_last_name>

<ssl_avs_address>123 Main</ssl_avs_address>

<ssl_city>Atlanta</ssl_city>

<ssl_state>GA</ssl_state>

<ssl_avs_zip>99999</ssl_avs_zip>

<ssl_country>USA</ssl_country>

<ssl_phone>9999999999</ssl_phone>

<ssl_ship_to_state>GA</ssl_ship_to_state>

<ssl_ship_to_zip>99999</ssl_ship_to_zip>

<ssl_ship_to_address1>999 Main</ssl_ship_to_address1>

<ssl_ship_to_company>Ship Company</ssl_ship_to_company>

<ssl_ship_to_last_name>Doe</ssl_ship_to_last_name>

<ssl_ship_to_city>Any City</ssl_ship_to_city>

<ssl_ship_to_first_name>Jane</ssl_ship_to_first_name>

</txn>

(continued)

Converge Developer Guide: Transaction Format CON-0002-N

<txn>

<ssl_approval_code>CMC720</ssl_approval_code>

<ssl_cvv2_response>M</ssl_cvv2_response>

<ssl_last_name>Doe</ssl_last_name>

<ssl_avs_zip>99999</ssl_avs_zip>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_account_balance>3.00</ssl_account_balance>

<ssl_company />

<ssl_result_message>APPROVAL</ssl_result_message>

<ssl_country>USA</ssl_country>

<ssl_city>Atlanta</ssl_city>

<ssl_phone>9999999999</ssl_phone>

<ssl_avs_address>123 Main</ssl_avs_address>

<ssl_invoice_number>1234</ssl_invoice_number>

<ssl_address2 />

<ssl_first_name>John</ssl_first_name>

<ssl_amount>3.00</ssl_amount>

<ssl_state>GA</ssl_state>

<ssl_txn_id>AA4843A-1416AF5F-9A4C-4C10-AA00-

537ADF2B3E0E</ssl_txn_id>

<ssl_result>0</ssl_result>

<ssl_card_number>00**********0000</ssl_card_number>

<ssl_txn_time>01/28/2014 05:14:49 PM</ssl_txn_time>

<ssl_avs_response>Z</ssl_avs_response>

</txn>

(end)

Credit Card AVS Only (ccavsonly)

The ccavsonly transaction is used to verify the credit card account for AVS data. An AVS code is returned to indicate if the AVS data passed originally was correct and matched the cardholder statement billing address.

Converge Developer Guide: Transaction Format CON-0002-N

Request

Input Field Name Req? Description

ssl_transaction_type Y Credit Card AVS Only (ccavsonly). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin ssl_show_form

N ssl_track_data ssl_ksn ssl_card_number ssl_exp_date ssl_avs_address ssl_avs_zip

Converge PIN as configured within Converge, case sensitive.

Set value to true to show the Converge Payment Form (available only for process.do), set to false otherwise.

Required for swiped or contactless transactions.

The raw track I and/or II data from the magnetic strip on the card. The track data captured from the swipe device cannot be manipulated and must be passed at the time of the transaction.

This includes the beginning and ending sentinels that are included in the track data. Raw track data cannot be stored under any circumstance. Expiration date is included with a track data.

First and last name of the Cardholder is also included with the

Track I data.

Notes:

 If using a Magtek encrypting device, pass the encrypted track data in the ssl_encrypted_track1_data and/or ssl_encrypted_track2_data.

 If using an Ingenico encrypting device, pass the encrypted track data in the ssl_enc_track_data.



Refer to the Encryption section for more information.

Required when sending track data from an encrypting device for payment cards.

The Key Serial Number generated from the swiped payment card, this is the value returned by the encrypting device. This value is used to encrypt the PAN data, using the Derived Unique Key Per

Transaction (DUKPT) method. It is a 10 byte composite field that is transmitted as 20 alphanumeric character fixed length.

Required for hand-keyed transactions.

Credit card number as it appears on the credit card.

Required for hand-keyed transactions.

Credit Card Expiry Date as it appears on credit card formatted as

MMYY.

Customer's address used to process AVS.

Customer's ZIP code used to process AVS.

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_result

Description

Transaction identification number. This number is a unique number used to identify the transaction. ssl_txn_time Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM. ssl_approval_code Transaction approval code. ssl_card_number

Masked card number for this transaction. Only first 2 / last 4 digits will be returned for regular PAN or the last four (4) digits from the actual card number if it is an association token (Example: ApplePay). ssl_avs_response

The Address Verification Response Code (refer to the AVS Response Codes

section for a complete list of AVS response codes). errorCode Error code returned only if an error occurred. 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. Refer to the Error Codes

section for more information. errorMessage errorName

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user interface.

Refer to the Error Codes section for more information.

Error name or reason for the error returned only if an error occurred. Refer to

Refer to the Encryption section for more information.

Examples

Important:



In all of these examples, you will have to change the data values, such as my_virtualmerchant_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, rather than in hidden value fields on an HTML form.

Converge Developer Guide: Transaction Format CON-0002-N

Example 1: process.do (false)

Shown below are the key value pairs from the header by themselves for a credit card AVS Only transaction: ssl_merchant_id=xxxxxx ssl_user_id=xxxxxxx ssl_pin=xxxxxx ssl_show_form=false ssl_transaction_type=ccavsonly ssl_card_number=0000000000000000 ssl_exp_date=1215 ssl_avs_zip=99999 ssl_avs_address=123 Main ssl_result_format= ASCII

The following values are returned for the approved transaction indicating that the Address matches, but ZIP Code does not match ssl_approval_code=CMC020 ssl_avs_address=123 Main ssl_avs_zip=99999 ssl_txn_id=AA4843A-444ECA99-EB04-4A8D-8339-B2A578F92EF6 ssl_result=0 ssl_card_number=00**********0000 ssl_account_balance=0.00 ssl_txn_time=01/28/2014 05:25:48 PM ssl_result_message=APPROVAL ssl_avs_response=A

Example 2: process.do(true)

This example demonstrates the initiation of a minimal AVS Only transaction in which Converge payment form gathers the entire card data. ssl_merchant_id=my_virtualmerchant_id ssl_user_id=my_user_id ssl_pin=my_pin ssl_transaction_type=ccavsonly ssl_show_form=true

Converge Developer Guide: Transaction Format CON-0002-N

Note: In all of these examples, you will have to change the data values, such as my_virtualmerchant_id

, my_user_id, my_pin, and the amount of 5.00 to values that match your Converge account and meet the needs of your websites.

Example 3: processxml.do

The following XML code example demonstrates the initiation of a basic AVS Only transaction. In the case of XML, no additional information can be collected by Converge when the request is sent. All required data must be sent in the transaction request to process the transaction:

<txn>

<ssl_merchant_ID>my_virtualmerchant_id</ssl_merchant_ID>

<ssl_user_id>my_user_id</ssl_user_id>

<ssl_pin>my_pin</ssl_pin>

<ssl_transaction_type>CCAVSONLY</ssl_transaction_type>

<ssl_card_number>0000000000000000</ssl_card_number>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_first_name>John</ssl_first_name>

<ssl_last_name>Doe</ssl_last_name>

<ssl_avs_address>123 Main</ssl_avs_address>

<ssl_city>Atlanta</ssl_city>

<ssl_state>GA</ssl_state>

<ssl_avs_zip>99999</ssl_avs_zip>

<ssl_country>USA</ssl_country>

</txn>

<txn>

<ssl_approval_code>CMC720</ssl_approval_code>

<ssl_last_name>Doe</ssl_last_name>

<ssl_avs_zip>99999</ssl_avs_zip>

<ssl_account_balance>3.00</ssl_account_balance>

<ssl_result_message>APPROVAL</ssl_result_message>

<ssl_country>USA</ssl_country>

<ssl_city>Atlanta</ssl_city>

<ssl_avs_address>123 Main</ssl_avs_address>

<ssl_first_name>John</ssl_first_name>

<ssl_state>GA</ssl_state>

<ssl_txn_id>AA3456VC-1416AF5F-9A4C-4C10-AA00-

537ADF2B3E0E</ssl_txn_id>

<ssl_result>0</ssl_result>

<ssl_card_number>00**********0000</ssl_card_number>

<ssl_txn_time>01/28/2014 05:33:40 PM</ssl_txn_time>

<ssl_avs_response>Z</ssl_avs_response>

</txn>

Converge Developer Guide: Transaction Format CON-0002-N

Credit Card Verification (ccverify)

The ccverify transaction is used to verify the credit card account for AVS and CVV data. AVS and CVV codes are returned to indicate if the AVS and CVV data passed originally were correct and matched the cardholder statement billing address and the CVV value located on the card.

Request

Input Field Name Req? Description

ssl_transaction_type

Y Credit Card Verification (ccverify). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin ssl_show_form

N ssl_track_data C

Converge PIN as configured within Converge, case sensitive.

Set value to true to show the Converge Payment Form (available only for process.do), set to false otherwise.

Required for swiped or contactless (MSD) transactions.

The raw track I and/or II data from the magnetic strip on the card. The track data captured from the swipe device cannot be manipulated and must be passed at the time of the transaction.

This includes the beginning and ending sentinels that are included in the track data. Raw track data cannot be stored under any circumstance. Expiration date is included with a track data. First and last name of the Cardholder is also included with the Track I data.

Notes:



If using a Magtek encrypting device, pass the encrypted track data in the ssl_encrypted_track1_data

and/or ssl_encrypted_track2_data



If using an Ingenico encrypting device, pass the encrypted track data in the ssl_enc_track_data.



ssl_ksn ssl_card_number

Required when sending track data from an encrypting device for payment cards.

The Key Serial Number generated from the swiped payment card, this is the value returned by the encrypting device. This value is used to encrypt the PAN data, using the Derived Unique

Key Per Transaction (DUKPT) method. It is a 10 byte composite field that is transmitted as 20 alphanumeric character fixed length.

Required for hand-keyed transactions.

Credit card number as it appears on the credit card.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_exp_date ssl_avs_zip ssl_avs_address ssl_cvv2cvc2

Req? Description

C Required for hand-keyed transactions.

Credit Card Expiry Date as it appears on credit card formatted as

MMYY.

Y Recommended for hand-keyed transactions.

Cardholder ZIP code.

Recommended for hand-keyed transactions.

Cardholder Address.

Recommended for hand-keyed transactions.

The credit card security code is a three-digit or four-digit number, printed either on the back or the front of the card.

When CVV data is passed, it is compared to the cardholder‘s

CVV data that the card issuer has on file, a CVV Response Code is then returned.

Response

Output Field Name

ssl_result

Description

The Address Verification Response Code (refer to the AVS Response Codes

section for a complete list of AVS response codes). ssl_cvv2_response

The Card Verification Response Code (refer to the CVV2/CVC2 Response

Codes section for a complete list of CVV/CVC2 response codes).

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

errorCode errorMessage errorName

Description

Error code returned only if an error occurred. 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. Refer to the Error Codes

section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user interface.

Refer to the Error Codes section for more information.

Error name or reason for the error returned only if an error occurred. Refer to

Example

Important:

 In all of these examples, you will have to change the data values, such as my_virtualmerchant_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, rather than in hidden value fields on an HTML form.

Example 1: process.do (false)

Shown below are the key value pairs from the header by themselves for a verification transaction: ssl_merchant_id=xxxxxx ssl_user_id=xxxxxxx ssl_pin=xxxxxx ssl_show_form=false ssl_transaction_type=ccverify ssl_card_number=0000000000000000 ssl_exp_date=1215 ssl_cvv2cvc2=123 ssl_avs_zip=99999 ssl_avs_address=123 Main ssl_result_format= ASCII

Converge Developer Guide: Transaction Format CON-0002-N

The following values are returned for the approved transaction indicating that the Address and

CVV value match – but ZIP Code does not match ssl_approval_code=CMC020 ssl_avs_address=123 Main ssl_avs_zip=99999 ssl_txn_id=AA4843A-B73B4A08-FA09-43E1-B858-072923E2E387 ssl_result=0 ssl_card_number=00**********0000 ssl_account_balance=0.00 ssl_txn_time=01/28/2014 05:25:48 PM ssl_result_message=APPROVAL ssl_avs_response=A ssl_cvv2_response=M

Example 2: process.do(true)

This example demonstrates the initiation of a minimal verification in which Converge payment form gathers the entire card data. ssl_merchant_id=my_virtualmerchant_id ssl_user_id=my_user_id ssl_pin=my_pin ssl_transaction_type=ccverify ssl_show_form=true

Note: In all of these examples, you will have to change the data values, such as my_virtualmerchant_id

, my_user_id, my_pin, and the amount of 5.00 to values that match your Converge account and meet the needs of your websites.

Converge Developer Guide: Transaction Format CON-0002-N

Example 3: processxml.do

The following XML code example demonstrates the initiation of a basic verification. In the case of

XML, no additional information can be collected by Converge when the request is sent. All required data must be sent in the transaction request to process the transaction:

<txn>

<ssl_merchant_ID>my_virtualmerchant_id</ssl_merchant_ID>

<ssl_user_id>my_user_id</ssl_user_id>

<ssl_pin>my_pin</ssl_pin>

<ssl_transaction_type>CCVERIFY</ssl_transaction_type>

<ssl_card_number>0000000000000000</ssl_card_number>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_first_name>John</ssl_first_name>

<ssl_last_name>Doe</ssl_last_name>

<ssl_cvv2cvc2>123</ssl_cvv2cvc2>

<ssl_avs_address>123 Main</ssl_avs_address>

<ssl_city>Atlanta</ssl_city>

<ssl_state>GA</ssl_state>

<ssl_avs_zip>99999</ssl_avs_zip>

<ssl_country>USA</ssl_country>

</txn>

(continued)

Converge Developer Guide: Transaction Format CON-0002-N

<txn>

<ssl_approval_code>CMC720</ssl_approval_code>

<ssl_last_name>Doe</ssl_last_name>

<ssl_avs_zip>99999</ssl_avs_zip>

<ssl_account_balance>0.00</ssl_account_balance>

<ssl_result_message>APPROVAL</ssl_result_message>

<ssl_country>USA</ssl_country>

<ssl_city>Atlanta</ssl_city>

<ssl_avs_address>123 Main</ssl_avs_address>

<ssl_first_name>John</ssl_first_name>

<ssl_state>GA</ssl_state>

<ssl_txn_id> AA4843A-750B6205-7F8F-42B4-838A-

79E0BA322D56</ssl_txn_id>

<ssl_result>0</ssl_result>

<ssl_card_number>00**********0000</ssl_card_number>

<ssl_txn_time>01/28/2014 05:36:40 PM</ssl_txn_time>

<ssl_avs_response>Z</ssl_avs_response>

<ssl_cvv2_response>M</ssl_cvv2_response>

</txn>

(end)

Credit Card Return/Credit (cccredit)

The cccredit transaction is used to issue a return (refund) to a cardholder’s credit card using full card number.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_show_form

Req? Description

Y Credit Card Return/Credit (cccredit).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Set value to true to show the Converge Payment Form

(available only for process.do), set to false otherwise.

Converge Developer Guide: Transaction Format

Input Field Name

ssl_track_data ssl_ksn ssl_card_number ssl_token ssl_exp_date

CON-0002-N

Req? Description

C Required for swiped or contactless (MSD) transactions.

Cardholder is also included with the Track I data.

Notes:



If using a Magtek encrypting device, pass the encrypted track data in the ssl_encrypted_track1_data

and/or ssl_encrypted_track2_data



If using an Ingenico encrypting device, pass the encrypted track data in the ssl_enc_track_data



supported. Refer to the ISO Currency Codes section for an

information.

Required when sending track data from an encrypting device for payment cards.

The Key Serial Number generated from the swiped payment card, this is the value returned by the encrypting device.

This value is used to encrypt the PAN data, using the

Derived Unique Key Per Transaction (DUKPT) method. It is a

10 byte composite field that is transmitted as 20 alphanumeric character fixed length.

Required for hand-keyed transactions.

Credit Card Number as it appears on the credit card.

Required for hand-keyed transaction if card number is not sent.

Use only with a terminal that is setup with Tokenization.

Credit Card Token, previously generated from a card number. A token can be stored and used as a substitute for a card number.

Required for hand-keyed transactions.

Credit Card Expiry Date as it appears on credit card formatted as MMYY.

Note: Do not send an expiration date with a token that is stored in Card Manager.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_amount ssl_card_present ssl_dynamic_dba ssl_departure_Date ssl_completion_Date

Req? Description

Y Transaction Amount to be refunded. Positive Number with

2 decimal places. Example: 2.00

For those terminals processing Multi-Currency, be sure to submit the correct number of decimal places for the transaction as some currencies have no exponents and some can have three.

Use only with a terminal that is setup with DBA.

DBA Name provided by the merchant with each transaction.

The maximum allowable Length of DBA Name variable provided by Merchant can be 21, 17 or 12 based on the length setup for the DBA constant in the field setup.

User only with a terminal that is setup with Travel Data.

MARMS.

Used only with a terminal that is setup with Travel Data.

Date of the completion of travel. Format MM/DD/YYYY.

Optional. This field is sent to the MARMS system to monitor risk associated with advanced booking. Examples include airlines and travel or tour agencies. Only used when setup with Travel Data option for MARMS.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name Req? Description

ssl_transaction_currency N Use only with a terminal that is setup with Multi-Currency.

Transaction currency alphanumeric code must be included in the request to indicate the currency in which you wish to process. If omitted the terminal default currency is assumed

(for example: USD, CAD, JPY). More than 94 currencies are

extensive list of available currencies. ssl_get_token N ssl_add_token N

Use only with a terminal that is setup with Tokenization.

Generate Token indicator, used to indicate if you wish to generate a token when passing card data. Valid values: Y

(generate a token), N (do not generate token).

Defaulted to N

Once generated, the token number can be stored and used as a substitute for a card number at later time.

Use only with a terminal that is setup with Tokenization.

Add to Card Manager indicator, used to indicate if you wish to store the token generated in Card Manager. Valid value: Y (add token) , N (do not add token) Defaulted to N

To add the token to the card manager you must send the card data and cardholder first/last name, those are required.

Once stored to Card Manager, the token number can be sent alone and will be used as a substitute for the stored information.

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id ssl_txn_time ssl_amount ssl_avs_response

Description

Transaction result message. Example: APPROVAL.

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 am.

Transaction amount. Returned based on merchant setup.

The Address Verification Response Code (refer to the AVS

Response Codes section for a complete list of AVS response

codes).

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_cvv2_response ssl_cardholder_amount ssl_card_number ssl_conversion_rate ssl_email

Description

The Card Verification Response Code (refer to the CVV2/CVC2

Response Codes section for a complete list of CVV/CVC2

response codes).

Only returned on DCC transactions.

Masked card number.

Only returned on DCC transactions.

Returned based on merchant setup. ssl_invoice_number The invoice or ticket number sent originally on the request.

Returned based on merchant setup. ssl_transaction_currency

Transaction currency. Returned only if terminal is setup for Multi-

Currency ssl_card_short_description Card description, valid values are: AMEX, CUP, DISC, MC, PP, VISA. ssl_card_type Card type, valid values are: CASH, CREDITCARD, DEBITCARD,

FOODSTAMP, GIFTCARD or LOYALTY. ssl_token ssl_token_response ssl_add_token_response errorCode errorMessage errorName

Credit Card Token generated from the card number. A token can be stored and used as a substitute for a card number.

Returned only if generating a token is requested in a terminal that is setup for Tokenization.

Outcome of the token generation. This value will be a SUCCESS if a token has been generated. Other possible returned values are

FAILURE, Action Not Permitted, Invalid Token, Not Permitted, or

Acct Verification Failed.

Returned only if generating a token is requested in a terminal that setup for Tokenization.

Outcome of the Add to Card Manager request, examples: Card

Added, Card Updated, Not Permitted, or FAILURE - First Name - is required.

Returned only if storing token is requested in a terminal that setup for Tokenization.

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant

configuration in the user interface. Refer to the Error Codes

section for more information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Converge Developer Guide: Transaction Format CON-0002-N

Example

Example: process.do(false)

The following example demonstrates the key value pairs from the header by themselves for a credit card return transaction for $10.00 where the merchant collects all the data from the consumer: ssl_merchant_id=my_vid_id ssl_user_id=my_user_id ssl_pin=my_pin ssl_show_form=false ssl_card_number=0000000000000000 ssl_exp_date=1215 ssl_amount=10.00 ssl_invoice_number=1234 ssl_error_url=http://www.url.com/cgi-bin/testtran.cgi ssl_result_format=HTML ssl_transaction_type=cccredit ssl_receipt_decl_method=REDG ssl_receipt_decl_get_url=http://www.url.com/cgi-bin/testtran.cgi ssl_receipt_apprvl_method=REDG ssl_receipt_apprvl_get_url=http://www.url.com/cgi-bin/testtran.cgi

By specifying the http://www.url.com/cgi-bin/testtran.cgi url in the ssl_apprvl_get_url

field for the redirect for the transaction above, the following values are returned for the approved transaction: ssl_card_number=00********0000 ssl_amount=10.00 ssl_result=0 ssl_result_message=APPROVAL ssl_txn_id= AA4843A-335FBE74-9608-45A1-B30A-658A3ABB5584 ssl_account_balance=1.00 ssl_invoice_number=1234 ssl_txn_time= 01/28/2014 05:46:22 PM

Converge Developer Guide: Transaction Format CON-0002-N

Credit Card Force (ccforce)

The ccforce is a transaction that places a previously authorized transaction into a current unsettled batch.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_pin ssl_user_id ssl_show_form ssl_track_data ssl_ksn

Req? Description

Y Credit Card Force (ccforce).

Converge ID as provided by Elavon.

Converge PIN as configured within Converge, case sensitive.

Converge User ID as configured on Converge, case sensitive.

Set value to true to show the Converge Payment Form

(available only for process.do), set to false otherwise.

Required for swiped or contactless (MSD) transactions.

Cardholder is also included with the Track I data.

Notes:



If using a Magtek encrypting device, pass the encrypted track data in the ssl_encrypted_track1_data

and/or ssl_encrypted_track2_data



If using an Ingenico encrypting device, pass the encrypted track data in the ssl_enc_track_data



currencies are supported. Refer to the ISO Currency Codes

information.

Required when sending track data from an encrypting device for payment cards.

The Key Serial Number generated from the swiped payment card, this is the value returned by the encrypting device. This value is used to encrypt the PAN data, using the Derived Unique Key Per Transaction (DUKPT) method. It is a 10 byte composite field that is transmitted as 20 alphanumeric character fixed length.

Converge Developer Guide: Transaction Format

Input Field Name

ssl_card_number ssl_token ssl_exp_date ssl_approval_code ssl_amount ssl_card_present ssl_avs_zip ssl_avs_address ssl_cvv2cvc2

CON-0002-N

Req? Description

C Required for hand-keyed transactions.

Credit Card Number as it appears on the credit card.

C Required for hand-keyed transaction if card number is not sent.

Use only with a terminal that is setup with Tokenization.

Credit Card Token, previously generated from a card number. A token can be stored and used as a substitute for a card number.

C Required for hand-keyed transactions.

Credit Card Expiry Date as it appears on credit card formatted as MMYY.

Note: Do not send an expiration date with a token that is stored in Card Manager.

Previously received Authorization Approval Code.

Transaction Sale Amount. Number with 2 decimal places.

This amount includes the Net amount and Sales Tax.



 For those terminals processing Multi-Currency, be sure to submit the correct number of decimal places for the transaction as some currencies have no exponents and some can have three.

Recommended for hand-keyed transactions.

Cardholder ZIP code.

Recommended for hand-keyed transactions.

Cardholder Address.

Recommended for hand-keyed transactions.

The credit card security code is a three-digit or four-digit number, printed either on the back or the front of the card.

When CVV data is passed, it is compared to the cardholder‘s CVV data that the card issuer has on file, a

CVV Response Code is then returned.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_cvv2cvc2_indicator ssl_invoice_number ssl_description ssl_customer_code ssl_salestax ssl_tip_amount ssl_server ssl_shift ssl_dynamic_dba

Req? Description

N Recommended for hand-keyed transaction.

The CVV2/CVC/CID indicator is one numeric value that should be passed with the CVV value (ssl_cvv2cvc2) to indicate if the CVV is present in the request. Valid values are:



0 for Bypassed

 1 for Present



2 for Illegible

 9 for Not Present

The invoice or ticket number.

The description, merchant defined value.

Recommended for purchasing cards.

The Customer Code or PO Number that appears on the cardholder's credit card billing statement.

Recommended for purchasing cards.

Sales tax amount applied to this transaction in decimal. Tax exempt transactions can pass 0.00 to properly reflect a tax exempt transaction.

Use only in a Service market segment

Tip or gratuity amount to be added, must be 2 decimal places, can be 0.00 to reset or remove the original tip from a transaction. Example: 1.00.

Use only in a Service market segment

Server ID, this is the clerk, cashier, and waiter or waitress identification number.

Alphanumeric, Example: Jack.

Use only in a Service market segment.

Shift, can refer to or be used to identify time period, course or type of service.

Alphanumeric, Example: Lunch.

Use only with a terminal that is setup with DBA.

DBA Name provided by the merchant with each transaction. The maximum allowable Length of DBA Name variable provided by Merchant can be 21, 17 or 12 based on the length setup for the DBA constant in the field setup.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_departure_Date ssl_completion_Date ssl_transaction_currency

Req? Description

N User only with a terminal that is setup with Travel Data.

Used only with a terminal that is setup with Travel Data.

Date of the completion of travel. Format MM/DD/YYYY.

Use only with a terminal that is setup with Multi-Currency.

section for an extensive list of available currencies. ssl_get_token ssl_add_token

Use only with a terminal that is setup with Tokenization.

Generate Token indicator, used to indicate if you wish to generate a token when passing card data. Valid value: Y

(generate a token), N (do not generate token).

Defaulted to N.

Once generated, the token number can be stored and used as a substitute for a card number at later time.

Use only with a terminal that is setup with Tokenization.

Add to Card Manager indicator, used to indicate if you wish to generate a token and store it in Card Manager.

Valid value: Y (add token), N (do not add token)

Defaulted to N

Converge Developer Guide: Transaction Format

Response

Output Field Name

CON-0002-N

Description

Authorization Response Codes section for an extensive list of

possible returned messages.

Transaction result message. Example: APPROVAL. Refer to

Authorization Response Codes section for more information.

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10

AM.

Transaction approval code.

The total transaction authorized or approved amount. This amount will include tip if tip has been provided in the request.

Returned based on merchant setup.

Base amount. Transaction amount sent originally on the request.

Returned based on merchant setup. Returned in the Service market segment.

Tip or gratuity amount that was added or updated. Returned based on merchant setup. Returned in the Service market segment.

The amount originally requested on partial approvals only.

The balance left in card, which is always 0.00 for a partially authorized transaction.

Masked card number.

The Address Verification Response Code (refer to the AVS

Response Codes section for a complete list of AVS response

codes).

The Card Verification Response Code (refer to the CVV2/CVC2

Response Codes section for a complete list of CVV/CVC2

response codes).

The invoice or ticket number sent originally on the request.

Returned based on merchant setup.

Only returned on DCC transactions.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_cardholder_currency ssl_cardholder_amount ssl_cardholder_base_amount Base amount in cardholder currency, only returned on DCC transactions. ssl_cardholder_tip_amount Tip amount in cardholder currency, only returned on DCC transactions with Service market segment. ssl_server ssl_shift

Server Id submitted with the request. Only returned on Service market segment based on the merchant setup.

Shift information submitted with the request. Only returned on

Service market segment based on the merchant setup. ssl_eci_ind ssl_transaction_currency

Only returned on 3D Secure transactions.

Valid values:

 Fully Authenticated



Authentication Attempted

Transaction currency. Returned only if terminal is setup for Multi-

Currency ssl_card_short_description

Description

Only returned on DCC transactions.

Total amount in cardholder currency, only returned on DCC transactions.

Card description, valid values are: AMEX, CUP, DISC, MC,

PP, VISA. ssl_card_type ssl_token ssl_token_response ssl_add_token_response

Card type, valid values are: CASH, CREDITCARD, DEBITCARD,

FOODSTAMP, GIFTCARD or LOYALTY.

Credit Card Token generated from the card number. A token can be stored and used as a substitute for a card number.

Returned only if generating a token is requested in a terminal that is setup for Tokenization.

Outcome of the token generation. This value will be a SUCCESS if a token has been generated. Other possible returned values are

FAILURE, Action Not Permitted, Invalid Token, Not Permitted, or

Acct Verification Failed.

Returned only if generating a token is requested in a terminal that setup for Tokenization.

Outcome of the Add to Card Manager request, examples: Card

Added, Card Updated, Not Permitted, or FAILURE - First Name - is required.

Returned only if storing token is requested in a terminal that setup for Tokenization.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

errorCode errorMessage errorName

Description

Error code returned only if an error occurred, 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. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant

configuration in the user interface. Refer to the Error Codes

section for more information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Credit Card Balance Inquiry (ccbalinquiry)

The ccbalinquiry is a transaction that returns the balance of a pre-paid card to the merchant.

This message format is for either a track 1 or a track 2 magnetic stripe read, or hand keyed prepaid card.

Request

Input Field Name Req? Description

ssl_transaction_type Y

Credit Card Balance Inquiry (ccbalinquiry). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin ssl_show_form

Converge PIN as configured within Converge, case sensitive.

Set value to true to show the Converge Payment Form (available only for process.do), set to false otherwise.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_track_data ssl_ksn ssl_card_number ssl_token

Req? Description

C Required for swiped or contactless (MSD) transactions.

The raw track I and/or II data from the magnetic strip on the card. The track data captured from the swipe device cannot be manipulated and must be passed at the time of the transaction.

This includes the beginning and ending sentinels that are included in the track data. Raw track data cannot be stored under any circumstance. Expiration date is included with a track data.

First and last name of the Cardholder is also included with the

Track I data.

Notes:



If using a Magtek encrypting device, pass the encrypted track data in the ssl_encrypted_track1_data and/or ssl_encrypted_track2_data.



If using an Ingenico encrypting device, pass the encrypted track data in the ssl_enc_track_data.



Refer to the Encryption section for more information.

Required when sending track data from an encrypting device for payment cards.

The Key Serial Number generated from the swiped payment card, this is the value returned by the encrypting device. This value is used to encrypt the PAN data, using the Derived Unique Key Per

Transaction (DUKPT) method. It is a 10 byte composite field that is transmitted as 20 alphanumeric character fixed length.

Required for hand-keyed transactions.

Credit Card Number as it appears on the credit card.

C Required for hand-keyed transaction if card number is not sent.

Use only with a terminal that is setup with Tokenization.

Credit Card Token, previously generated from a card number. A token can be stored and used as a substitute for a card number.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_exp_date ssl_get_token ssl_add_token

Req? Description

C Required for hand-keyed transactions.

Credit Card Expiry Date as it appears on credit card formatted as

MMYY.

Note: Do not send an expiration date with a token that is stored in Card Manager.

Use only with a terminal that is setup with Tokenization.

Generate Token indicator, used to indicate if you wish to generate a token when passing card data. Valid value: Y

(generate a token), N (do not generate token). Defaulted to N.

Once generated, the token number can be stored and used as a substitute for a card number at later time.

Use only with a terminal that is setup with Tokenization.

Add to Card Manager indicator, used to indicate if you wish to store the token generated in Card Manager. Valid value: Y (add token), N (do not add token) Defaulted to N

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id

Description

Outcome of a transaction. A response that contains ssl_result of

0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized.

Transaction result message. Example: APPROVAL.

Transaction identification number. This is a unique number used to identify the transaction. ssl_txn_time ssl_account_balance ssl_approval_code

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM.

The account balance. Number with two decimal places.

Transaction approval code. ssl_card_number Masked card number. ssl_transaction_currency Transaction currency. Returned only if terminal is setup for Multi-

Currency.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_token ssl_token_response ssl_add_token_response errorCode errorMessage errorName

Description

Credit Card Token generated from the card number. A token can be stored and used as a substitute for a card number.

Returned only if generating a token is requested in a terminal that is setup for Tokenization.

Outcome of the token generation. This value will be a SUCCESS if a token has been generated. Other possible returned values are

FAILURE, Action Not Permitted, Invalid Token, Not Permitted, or Acct

Verification Failed.

Returned only if generating a token is requested in a terminal that setup for Tokenization.

Outcome of the Add to Card Manager request, examples: Card

Added, Card Updated, Not Permitted, or FAILURE - First Name - is required.

Returned only if storing token is requested in a terminal that setup for Tokenization.

Error code returned only if an error occurred, 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. Refer to the Error Codes section for more information.

Detailed explanation of the error returned only if an error occurred.

This field may be changed based on merchant configuration in the

user interface. Refer to the Error Codes section for more

information.

Error name or reason for the error returned only if an error occurred.

Refer to the Error Codes section for more information.

Credit Card Generate Token (ccgettoken)

The ccgettoken is a transaction that generates a token from a card number or an existing recurring/installment in the recurring batch. The token generated can be used in place of a credit card number in any subsequent transactions. Additionally, you can request that the token generated is added to the Card Manager. This transaction type is supported only when a terminal

is setup for tokenization for hand-keyed cards only; refer to the Tokenization section for more

information.

Converge Developer Guide: Transaction Format CON-0002-N

To perform a ccgettoken, you must submit either:

 Card number, expiration date for generating a token, in addition first and last name are required to add the token to card manager.

 Recurring ID or installment ID of an existing recurring/installment transaction in the ssl_recurring_id

field for generating a token. In order to add the token to the card manager, the first and last names must be previously stored with the recurring records or sent along with the transaction.



The encrypted track data for swiped or contactless transactions:



Track 1 data in the ssl_encrypted_track1_data field and/or track 2 data in the ssl_encrypted_track2_data field, extracted from the Magtek readers

(MagneSafe encryption). Refer to the Encryption section for more information.



Entire track data in the ssl_enc_track_data field captured from the Ingenico

device (3DES DUKPT encryption). Refer to the Encryption section for more

information.

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_show_form ssl_card_number ssl_exp_date ssl_recurring_id

Req? Description

Y Credit Card Generate Token (ccgettoken).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Set value to true to show the Converge Payment Form

(available only for process.do), set to false otherwise.

Required for generating token using hand-keyed card.

Credit Card Number as it appears on the credit card.

Required for generating token using hand-keyed card.

Expiration date as it appears on the credit card.

Required for generating token using an existing recurring or installment transactions.

The ID number of the recurring record or installment record to be submitted for payment. This value was returned in the recurring ID when the original recurring record was added for recurring or populate with installment ID when the original installment was added for installment.

Alphanumeric.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_enc_track_data

Req? Description

C Required for generating token using swiped or contactless

(MSD) credit from an Ingenico encrypting device.

This is the entire encrypted Track data combined into a single cipher text that was extracted from the Ingenico encrypting device. ssl_encrypted_track1_data C

Required for generating token using swiped or contactless

(MSD) credit from a Magtek encrypting reader.

This is the encrypted Track 1 data extracted from the encrypting device. ssl_encrypted_track2_data C

Required for generating token using swiped or contactless

(MSD) credit from a Magtek encrypting reader.

This is the encrypted Track 2 data extracted from the secure device. ssl_ksn C ssl_verify

Required when sending track data from an encrypting device for payment cards.

The Key Serial Number generated from the swiped payment card, this is the value returned by the encrypting device. This value is used to encrypt the PAN data, using the Derived

Unique Key Per Transaction (DUKPT) method. It is a 10 byte composite field that is transmitted as 20 alphanumeric character fixed length.

Account Verify indicator to indicate that account verification is needed prior to generating a token. Valid values: Y, N. ssl_avs_zip C ssl_avs_address ssl_cvv2cvc2

Recommended with Account Verify indicator, required with

Add to Card Manager indicator.

Cardholder ZIP code.

Recommended with Account Verify indicator, required with

Add to Card Manager indicator.

Cardholder Address.

Recommended with Account Verify indicator.

The credit card security code is a three-digit or four-digit number, printed either on the back or the front of the card.

When CVV data is passed, it is compared to the cardholder‘s

CVV data that the card issuer has on file, a CVV Response

Code is then returned.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_add_token ssl_first_name ssl_last_name

Req? Description

N Add to Card Manager indicator, used to indicate if you wish to store the token generated in Card Manager. Valid value: Y (add token), N (do not add token) Defaulted to N

To add the token to the card manager you must send the card data and cardholder first/last name, those are required or you can send a recurring ID that has those data previously stored. Once stored to Card Manager, the token number can be sent alone and will be used as a substitute for the stored information.

Required with Add to Card Manager indicator when generating a toke from card number.

Cardholder first name.

Required with Add to Card Manager indicator when generating a toke from card number.

Cardholder last name.

Response

Output Field Name

ssl_result

Description

Generate Token Result code. A result of 0 indicates that the token was generated; 1 indicates that the token was not generated. ssl_result_message ssl_token

The account verification transaction result message returned only when ccgettoken is requested with Account verification flag. Example:

APPROVAL, DECLINE. Refer to the Authorization Response Codes

section for an extensive list of possible returned messages.

Credit Card Token generated from the card number. A token can be stored and used as a substitute for a card number. ssl_token_response Outcome of the token generation. This value will be SUCCESS if a token has been generated. Other possible returned values are FAILURE,

Action Not Permitted, Invalid Token, Not Permitted, Acct Verification

Failed.

Returned only if generating a token is requested in a terminal that setup for Tokenization. ssl_add_token_response Outcome of the Add to Card Manager request, examples: Card Added,

Card Updated, Not Permitted, FAILURE - First Name - is required.

Returned only if storing token is requested in a terminal that setup for

Tokenization. ssl_txn_id Transaction identification number, returned only when ccgettoken is requested with Account verification flag. This is a unique number used to identify the transaction. This value can be used to complete the Auth

Only transaction.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_txn_time ssl_avs_response ssl_cvv2_response ssl_approval_code errorCode errorMessage errorName

Description

Date and time when the transaction was processed, returned only when ccgettoken

is requested with Account verification flag. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM.

The Address Verification Response Code (refer to the AVS Response

Codes section for a complete list of AVS response codes). Returned

only when ccgettoken is requested with Account verification flag.

The Card Verification Response Code (refer to the CVV2/CVC2

Response Codes section for a complete list of CVV/CVC2 response

codes). Returned only when ccgettoken is requested with Account verification flag.

Transaction approval code, returned only when ccgettoken is requested with Account verification flag.

Refer to the Error Codes section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user

interface. Refer to the Error Codes section for more information.

Error name or reason for the error returned only if an error occurred.

Refer to the Error Codes section for more information.

Credit Card Return (ccreturn)

The ccreturn transaction is used to issue a partial or a full return (refund) to a cardholder’s credit card using the transaction ID of the original sale or force transaction. This will guarantee that the same credit card used previously for the purchase is the one being refunded.

Users may choose to generate a partial return by passing the original transaction ID of the sale or force transaction and an amount that is less than the original amount, or a full return by passing the original transaction ID only without the amount. Enhanced credits for an amount higher than the original sale/force amount are not allowed.

Notes:

 Converge will continue to allow merchants to refund credit card transactions using full card number/track data per current functionality using cccredit. We strongly advise however, to use the enhanced credits in order to minimize risks associated with refund abuse.

 The ssl_show_form property does not apply on Void transactions.

Converge Developer Guide: Transaction Format CON-0002-N

Request

Input Field Name Req? Description

ssl_transaction_type Y Credit Card Enhanced Return/Credit (ccreturn). ssl_merchant_id ssl_pin

Converge ID as provided by Elavon.

Converge PIN as configured within Converge, case sensitive. ssl_user_id ssl_txn_id ssl_amount

Converge User ID as configured on Converge, case sensitive.

Unique identifier returned on the original transaction.

Amount to be refunded in full or partial. Number with two decimal places. Must be less or equal to the original purchase, if not supplied original full amount is refunded. For example: 1.00.

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id

Description

Transaction result message. Example: APPROVAL.

Transaction identification number. This is a unique number used to identify the transaction. ssl_txn_time ssl_amount

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM.

Transaction amount. Returned based on merchant setup. ssl_approval_code ssl_avs_response ssl_cvv2_response

The Card Verification Response Code (refer to the CVV2/CVC2 Response

Codes section for a complete list of CVV/CVC2 response codes).

ssl_cardholder_amount

Only returned on DCC transactions. ssl_card_number Masked card number. ssl_conversion_rate

Transaction approval code.

The Address Verification Response Code (refer to the AVS Response

Codes section for a complete list of AVS response codes).

ssl_email ssl_invoice_number

Only returned on DCC transactions.

Returned based on merchant setup.

The invoice or ticket number sent originally on the request. Returned based on merchant setup.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

errorCode errorMessage errorName

Description

interface. Refer to the Error Codes section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user

Error name or reason for the error returned only if an error occurred.

Refer to the Error Codes section for more information.

Credit Card Void (ccvoid)

The ccvoid is a transaction that removes a Sale, Credit or Force transaction from the open batch. No funds will be deposited into the merchant’s bank account at settlement. The ccvoid command is typically used for same day returns or to correct cashier mistakes. This action can only be performed before the batch is settled. To perform a ccvoid, you must submit the transaction ID received from the original transaction.

Note: The ssl_show_form property does not apply on Void transactions.

Request

Input Field Name Req? Description

ssl_transaction_type Y Credit Void (ccvoid). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin ssl_txn_id

Converge PIN as configured within Converge, case sensitive.

Unique identifier returned on the original transaction.

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_result

Description

Date and time when the transaction was processed, Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM. ssl_txn_id Transaction identification number. This is a unique number used to identify the transaction. ssl_approval_code Transaction approval code. ssl_invoice_number

The invoice or ticket number sent originally on the request. Returned based on merchant setup. ssl_email Returned based on merchant setup. errorCode Error code returned only if an error occurred. 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. Refer to the Error Codes

section for more information. errorName errorMessage

Error name or reason for the error returned only if an error occurred. Refer to

Refer to the Error Codes section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user interface.

Converge Developer Guide: Transaction Format CON-0002-N

Examples

Example 1: process.do(false)

To void the transaction submit a transaction request using HTTPS POST with the Transaction ID associated to the transaction you wish to modify. The card number or track data should not be sent. Shown below are the key value pairs from the header by themselves for a credit card void transaction: ssl_merchant_id=xxxxxx ssl_user_id=xxxxxxx ssl_pin=xxxxxx ssl_transaction_type=ccvoid ssl_txn_id =1016413275E60BB4EC-B4C6-FD4D-A878-F70C3372C986 ssl_error_url=http://www.url.com/cgi-bin/testtran.cgi ssl_result_format=HTML ssl_receipt_decl_method=REDG ssl_receipt_decl_get_url=http://www.url.com/cgi-bin/testtran.cgi ssl_receipt_apprvl_method=REDG ssl_receipt_apprvl_get_url=http://www.url.com/cgi-bin/testtran.cgi

By specifying the http://www.url.com/cgi-bin/testtran.cgi URL in the ssl_receipt_apprvl_get_url

field for the redirect for the transaction above, the following values are an example of a response returned for the approved modified transaction: ssl_card_number=00********0000 ssl_amount=1.00 ssl_result=0 ssl_result_message=APPROVAL ssl_txn_id=1016413275E60BB4EC-B4C6-FD4D-A878-F70C3372C986 ssl_approval_code=CVI368 ssl_txn_time=10/05/2008 10:50:55 AM

By specifying the http://www.url.com/cgi-bin/testtran.cgi URL in the ssl_error_url

field for the redirect for the transaction above, the following values (in the example below the Transaction ID is invalid) are returned if the request is invalid: errorCode=5040 errorName= Invalid Transaction ID errorMessage= The transaction ID is invalid for this transaction type

Converge Developer Guide: Transaction Format CON-0002-N

Example 2: processxml.do

This XML example demonstrates how to void a sale transaction. This is the response associated to a sale transaction: xmldata=<txn>

<ssl_result>0</ssl_result>

<ssl_approval_code>N07032</ssl_approval_code>

<ssl_account_balance>0.00</ssl_account_balance>

<ssl_amount>1.00</ssl_amount>

<ssl_result_message>APPROVAL</ssl_result_message>

<ssl_invoice_number>PO456</ssl_invoice_number>

<ssl_description>Purchase</ssl_description>

<ssl_txn_id>AA49315-F494FC02-661E-4426-A410-

A87F6249F26B</ssl_txn_id>

<ssl_card_number>00**********0000</ssl_card_number>

<ssl_txn_time>07/21/2013 03:07:41 PM</ssl_txn_time>

<ssl_avs_response/>A</ssl_avs_response>

<ssl_cvv2_response>M</ssl_cvv2_response>

</txn>

This is an example of a request and response to void the previous sale transaction:

Request

xmldata=<txn>

<ssl_merchant_id>my_virtualmerchant_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>ccvoid</ssl_transaction_type>

<ssl_txn_id>AA49315-F494FC02-661E-4426-A410-

A87F6249F26B</ssl_txn_id>

</txn>

Converge Developer Guide: Transaction Format CON-0002-N

Response

<txn>

<ssl_result>0</ssl_result>

<ssl_approval_code>N07033</ssl_approval_code>

<ssl_account_balance>0.00</ssl_account_balance>

<ssl_amount>1.00</ssl_amount>

<ssl_result_message>APPROVAL</ssl_result_message>

<ssl_invoice_number>PO456</ssl_invoice_number>

<ssl_description>Purchase</ssl_description>

<ssl_txn_id>AA47AD-8B8D1518-FAD3-46AD-A0F4-

790652B5617E</ssl_txn_id>

<ssl_card_number>00**********0000</ssl_card_number>

<ssl_txn_time>07/21/2013 03:15:31 PM</ssl_txn_time>

<ssl_avs_response/>A</ssl_avs_response>

<ssl_cvv2_response>M</ssl_cvv2_response>

</txn>

Notes:



In all of these examples, you will have to change the data values, such as my_virtualmerchant_id

, my_user_id, my_pin, and the transaction ID obtained from the original transaction to void.



Transaction update returns a new Transaction ID value.



Transaction update returns the original data such as billing, shipping and custom values in the response.

Converge Developer Guide: Transaction Format CON-0002-N

Credit Card Completion (cccomplete)

A transaction type of cccomplete places an approved Auth Only transaction into the open batch for settlement.

An Auth Only transaction is converted to a sale when a transaction type of cccomplete is sent with a transaction ID that belongs to an Auth Only transaction. All transactions converted to Sale will be placed in the open batch and are handled the same way as Sale transactions.

The following completion types are supported:



Full completion:

Send cccomplete with the Auth Only Transaction ID without any amount, if you wish to convert an existing Auth Only to Sale. The entire Auth Only transaction will move from the Auth Only batch to the Main batch for settlement.



Partial-completion:

Send cccomplete with the Auth Only Transaction ID with an amount that is less than the original Auth Only amount, if you wish to convert only a portion of the Auth Only to

Sale. The Auth only transaction will move from the Auth Only batch to the Main batch and the transaction will only be settled for smaller amount. The original Auth Only transaction cannot be used again.



Multi partial-completion:

Send cccomplete with the Auth Only Transaction ID with an amount that is less than the Auth Only amount and the partial shipment flag, this action will allow you to keep the unused portion of the Auth only in the Auth Only batch, and convert only the desired portion to the Main batch. The Auth Only will remain in the Auth Only batch and multiple completions can be performed on the single Auth only transaction until the total amount has been reached. Every completion will create a new fresh sale.

Notes:



Transaction status will not change. A pended Auth Only will be converted to a pended sale. Users have to login to the application in order to unpend a transaction. Transactions set to pend will not settle until they are set to unpend



The ssl_show_form property does not apply on completion transactions.

 A completion request for an amount higher than the original Auth Only is not allowed.

 Users must have the Batches-Edit Transactions user right in order to complete a transaction.

Converge Developer Guide: Transaction Format CON-0002-N

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_pin ssl_user_id ssl_txn_id ssl_amount

Req? Description

Y Credit Card Completion (cccomplete).

Converge ID as provided by Elavon.

Converge PIN as configured within Converge, case sensitive.

N ssl_partial_shipment_flag N

Converge User ID as configured on Converge, case sensitive.

Unique identifier returned on the Auth Only transaction to be converted to Sale.

Amount to be converted in full or partial. Number with two decimal places. Must be less or equal to the original purchase, If not supplied full amount will be converted. For example: 1.00.

Partial shipment flag to indicate the support of partial shipments, defaulted to N if not sent.

Valid values:

N – Partial Shipment not supported

Y – Partial Shipment supported

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id ssl_txn_time ssl_card_number ssl_amount ssl_approval_code ssl_avs_response ssl_cvv2_response

Description

Outcome of a transaction. A response that contains ssl_result of 0 represents an Approved transaction.

Transaction result message. Example: APPROVAL.

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM.

Masked card number.

Transaction amount. Returned based on merchant setup.

Transaction approval code.

The Address Verification Response Code (refer to the AVS Response

Codes section for a complete list of AVS response codes).

The Card Verification Response Code (refer to the CVV2/CVC2 Response

Codes section for a complete list of CVV/CVC2 response codes).

ssl_invoice_number Invoice or ticket number sent originally on the request. Returned based on merchant setup. ssl_cardholder_amount Only returned on DCC transactions. ssl_conversion_rate Only returned on DCC transactions.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

errorCode errorMessage errorName

Description

Refer to the Error Codes section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user

interface. Refer to the Error Codes section for more information.

Error name or reason for the error returned only if an error occurred.

Refer to the Error Codes section for more information.

Example

This example demonstrates how to complete an Auth Only transaction. This is the response associated to an Auth Only transaction:

<txn>

<ssl_result>0</ssl_result>

<ssl_approval_code>N19032</ssl_approval_code>

<ssl_result_message>APPROVAL</ssl_result_message>

<ssl_txn_id>AA4843B-EEBFF0FE-0BDC-47A3-B4F6-

5D752E2FBE42</ssl_txn_id>

<ssl_txn_time>07/21/2013 05:27:42 PM</ssl_txn_time>

<ssl_amount>3.00</ssl_amount>

<ssl_salestax>0.01</ssl_salestax>

<ssl_account_balance>0.00</ssl_account_balance>

<ssl_card_number>00**********0000</ssl_card_number>

<ssl_cvv2_response>M</ssl_cvv2_response>

<ssl_avs_response>A</ssl_avs_response>

<ssl_invoice_number>1234</ssl_invoice_number>

<ssl_first_name>John</ssl_first_name>

<ssl_last_name>Doe</ssl_last_name>

<ssl_avs_address>123 Main</ssl_avs_address>

<ssl_city>Atlanta</ssl_city>

<ssl_avs_zip>30123</ssl_avs_zip>

<ssl_state>GA</ssl_state>

<ssl_country>USA</ssl_country>

<ssl_dynamic_dba>123456789012*ABCCORP</ssl_dynamic_dba>

</txn>

Converge Developer Guide: Transaction Format CON-0002-N

This is an example of a request and response to complete the previous auth transaction for the full amount:

Request

xmldata=<txn>

<ssl_merchant_id>my_virtualmerchant_id</ssl_merchant_id>

<ssl_user_id>my_user_id</ssl_user_id>

<ssl_pin>my_pin</ssl_pin>

<ssl_description>Keyed Sale API</ssl_description>

<ssl_transaction_type>cccomplete</ssl_transaction_type>

<ssl_txn_id>AA4843B-EEBFF0FE-0BDC-47A3-B4F6-

5D752E2FBE42</ssl_txn_id>

</txn>

Response

<txn>

<ssl_result>0</ssl_result>

<ssl_approval_code>N19032</ssl_approval_code>

<ssl_result_message>APPROVAL</ssl_result_message>

<ssl_txn_id>AA4843B-EEBFF0FE-0BDC-47A3-B4F6-

5D752E2FBE42</ssl_txn_id>

<ssl_txn_time>07/21/2013 05:19:38 PM</ssl_txn_time>

<ssl_amount>3.00</ssl_amount>

<ssl_salestax>0.01</ssl_salestax>

<ssl_account_balance>0.00</ssl_account_balance>

<ssl_card_number>00**********0000</ssl_card_number>

<ssl_cvv2_response>M</ssl_cvv2_response>

<ssl_avs_response>A</ssl_avs_response>

<ssl_invoice_number>1234</ssl_invoice_number>

<ssl_first_name>John</ssl_first_name>

<ssl_last_name>Doe</ssl_last_name>

<ssl_avs_address>123 Main</ssl_avs_address>

<ssl_city>Atlanta</ssl_city>

<ssl_avs_zip>30123</ssl_avs_zip>

<ssl_state>GA</ssl_state>

<ssl_country>USA</ssl_country>

<ssl_dynamic_dba>123456789012*ABCCORP</ssl_dynamic_dba>

</txn>

Converge Developer Guide: Transaction Format CON-0002-N

Credit Card Delete (ccdelete)

The ccdelete is a transaction that deletes and attempts a reversal on a Sale or Auth Only credit transaction. A transaction that has been deleted from the batch cannot be recovered. This transaction type is typically used in a partial approval scenario. When a consumer decides not to continue with an additional tender type, the point of sale application must send a reversal to cancel the payment and restore the balance to the card.

Reversals free up cardholders open to buy amounts by reducing issuer holds on available balances when transactions are not completed. This reduces declines at the point of sale and the amount of cardholder complaints that are unpleasant for all parties involved. To perform a ccdelete, you must submit the transaction ID received from the original transaction.

Note:



The ssl_show_form property does not apply on Delete transactions.



Users must have the Batches-Void Delete user right in order to delete a transaction.

Request

Input Field Name Req? Description

ssl_transaction_type Y Credit Card Delete (ccdelete). ssl_merchant_id ssl_pin

Converge ID as provided by Elavon.

Converge PIN as configured within Converge, case sensitive. ssl_user_id ssl_txn_id

Converge User ID as configured on Converge, case sensitive.

Unique identifier returned on the original transaction.

Response

Output Field Name

ssl_result

Description

Outcome of a transaction. A response that contains ssl_result of 0 represents an Approved transaction. A response containing any other value for ssl_result represents a Declined transaction preventing it from being authorized. ssl_result_message Transaction result message. Example: APPROVAL. ssl_txn_id Transaction identification number. This is a unique number used to identify the transaction. ssl_approval_code Transaction approval code. ssl_email Returned based on merchant setup. ssl_invoice_number Invoice or ticket number sent originally on the request. Returned based on merchant setup.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_txn_time errorCode errorMessage errorName

Description

Date and time when the transaction was processed, Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 A.M.

Error code returned only if an error occurred. 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. Refer to the Error Codes

section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user interface.

Refer to the Error Codes section for more information.

Error name or reason for the error returned only if an error occurred. Refer to

numeric field. Refer to the Error Codes section for more

Credit Card Update Tip (ccupdatetip)

The ccupdatetip transaction is used to add, modify or reset a tip (gratuity) on an open approved credit card sale or force transactions using the original transaction ID. This transaction type is supported in the Service market segment. Tips are updated or added after the transaction has been processed, typically at the end of the day prior to settlement. The most current tip amount sent will reflect in the total amount of that transaction. Error 5040 is returned if adding a tip is attempted on an invalid transaction.

To perform a ccupdatetip, you must submit the transaction ID received from the original transaction along with the desired tip amount. This also will override the tip amount if present with the latest tip amount provided.

Notes:



The ssl_show_form property does not apply on update tips.



A tip amount of 0.00 removes or resets an existing tip on a transaction



Tip amount can be sent in the cardholder amount



You may send the Shift and Server ID to update this information on an existing transaction



This transaction may be sent several times prior to settlement if needed. The last and most current tip sent will be processed as the tip amount

Converge Developer Guide: Transaction Format CON-0002-N

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_pin ssl_user_id ssl_txn_id ssl_tip_amount ssl_cardholder_tip_amount

Req? Description

Y Update Tip (ccupdatetip).

Converge ID as provided by Elavon.

Converge PIN as configured within Converge, case sensitive.

Converge User ID as configured on Converge, case sensitive.

Unique identifier returned on the original transaction, must be either a credit sale or credit force.

Tip or gratuity amount to be added or updated, must be 2 decimal places, can be 0.00 to reset or remove the original tip from a transaction. Example: 1.00.

Use only for DCC transaction.

Tip or gratuity amount to be added or updated in the cardholder currency if the original transaction was processed as a DCC transaction and the amount authorized was in the cardholder currency, must be two decimal places, can be 0.00 to reset or remove the original tip from a DCC transaction. Example: 1.00. ssl_server ssl_shift

Server ID, this is the clerk, cashier, waiter or waitress identification number, can be used for reporting purposes.

Alphanumeric, Example: Jack.

Shift, can refer to or be used to identify time period, course or type of service, and can be used for reporting purposes.

Alphanumeric, Example: Lunch.

Response

Output Field Name

ssl_result_message ssl_txn_id ssl_amount ssl_base_amount ssl_tip_amount

Description

Tip update result message: a result of SUCCESS indicates the tip was updated or added successfully. ERROR indicates the tip was not added or updated successfully.

Transaction identification number. This is a unique number used to identify the transaction.

Transaction total amount including tip. Returned based on merchant setup.

Base amount. Transaction amount sent originally on the request.

Returned based on merchant setup.

Tip or gratuity amount that was added or updated. Returned based on merchant setup.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_server ssl_shift ssl_conversion_rate ssl_cardholder_currency ssl_cardholder_amount

Description

Server identification number or name sent on request. Returned based on merchant setup.

Shift sent on request, Returned based on merchant setup.

Only returned on DCC transactions.

Total amount in cardholder currency, only returned on DCC transactions. ssl_cardholder_base_amount Base amount in cardholder currency, only returned on DCC transactions. ssl_cardholder_tip_amount

Tip amount in cardholder currency, only returned on DCC transactions. errorCode Error code returned only if an error occurred. Typically, when the transaction failed validation or the request is incorrect. This will prevent the transaction from going to authorization. This is a

information. errorMessage errorName

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant

configuration in the user interface. Refer to the Error Codes

section for more information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Example

The following XML code example demonstrates how to update the tip on a previously approved transaction. The previously approved transaction may or may not have a tip. This will override the tip amount with the latest tip amount provided. This request can be performed several times if needed on a single transaction.

In this example the tip amount that was previously added to the transaction (2.00) will be updated to 5.00, the shift and server values have been updated as well.

Converge Developer Guide: Transaction Format CON-0002-N

Initial Request

xmldata=<txn>

<ssl_merchant_id>my_virtualmerchant_id</ssl_merchant_id>

<ssl_user_id>my_user</ssl_user_id>

<ssl_pin>my_pin</ssl_pin>

<ssl_test_mode>false</ssl_test_mode>

<ssl_transaction_type>ccupdatetip</ssl_transaction_type>

<ssl_txn_id>TEST43B-D0638677-26EB-40F5-B2F9-

3AF2545DE144</ssl_txn_id>

<ssl_tip_amount>5.00</ssl_tip_amount>

<ssl_shift>lunch</ssl_shift>

<ssl_server>Jane</ssl_server>

</txn>

Response Receipt

xmldata=<txn>

<ssl_result_message>SUCCESS</ssl_result_message>

<ssl_txn_id>101641221593ACBA6-BAFD-76B7-4948-

B3DE68CFD0CC</ssl_txn_id>

<ssl_amount>15.00</ssl_amount>

<ssl_base_amount>10.00</ssl_base_amount>

<ssl_tip_amount>5.00</ssl_tip_amount>

<ssl_shift>lunch</ssl_shift>

<ssl_server>Jane</ssl_server>

</txn>

Credit Card Signature (ccsignature)

The ccsignature is a transaction that adds signature data to a previously approved credit card transaction. To perform a ccsignature, you must submit the transaction ID received from the original transaction.

The following transaction types can be assigned a signature by passing the original transaction ID obtained from an approved transaction along with the signature data:



Credit Card Sale



Credit Card Force



Credit Card Auth Only



Credit Card Credit

Converge Developer Guide: Transaction Format CON-0002-N

Notes:



The ssl_show_form property does not apply on adding a signature.

 All signature images must be BASE64 encoded in the following supported formats:

 Signature is not allowed for the e-Commerce market segment.

 Signature can only be added to an approved transaction

 Signature can only be added to a transaction that has no signature

Request

Input Field Name Req? Description

ssl_transaction_type Y Credit Signature (ccsignature). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin ssl_image_type ssl_signature_image ssl_txn_id

Converge PIN as configured within Converge, case sensitive.

Image format.

Possible values, must be capital:

 GIF



TIF



JPG



PNG

BASE 64 Encoded version of an IMAGE.

Unique identifier returned on the original transaction.

Response

Output Field Name

ssl_result

Description

Signature request result code. A result of 0 indicates the signature was successfully uploaded and added. 1 indicates that the signature upload failed. ssl_result_message Signature upload result message. A result of SUCCESS indicates the image was uploaded or added successfully. ERROR indicates the image was not added or imported successfully. ssl_user_id Converge User ID.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

errorCode errorMessage errorName

Description

Error code returned only if an error occurred. 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. Refer to the Error Codes

section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user interface.

Refer to the Error Codes section for more information.

Error name or reason for the error returned only if an error occurred. Refer to

numeric field. Refer to the Error Codes section for more

Example

The following XML code example demonstrates how to add a signature to a previously approved sale transaction. The original transaction ID obtained from the approved Sale must be passed along with the signature data:

Initial Sale Request

xmldata=<txn>

<ssl_merchant_id>my_virtualmerchant_id</ssl_merchant_id>

<ssl_user_id>my_user</ssl_user_id>

<ssl_pin>my_pin</ssl_pin>

<ssl_test_mode>false</ssl_test_mode>

<ssl_transaction_type>ccsale</ssl_transaction_type>

<ssl_amount>1.00</ssl_amount>

<ssl_track_data>%B0000000000000000^NOVA

CORPORATION^2212101543213961456?;

0000000000000000=2212101543213961456?</ssl_track_data>

</txn>

Converge Developer Guide: Transaction Format

Sale Response

<txn>

<ssl_approval_code>N21032</ssl_approval_code>

<ssl_cvv2_response />

<ssl_exp_date>1222</ssl_exp_date>

<ssl_departure_date />

<ssl_account_balance>0.00</ssl_account_balance>

<ssl_result_message>APPROVAL</ssl_result_message>

<ssl_invoice_number />

<ssl_amount>1.00</ssl_amount>

<ssl_result>0</ssl_result>

<ssl_txn_id>AA49315-DCA463E6-F924-4CA8-9FBF-

01220FBACA19</ssl_txn_id>

<ssl_card_number>00**********0000</ssl_card_number>

<ssl_completion_date />

<ssl_txn_time>01/28/2014 10:21:31 PM</ssl_txn_time>

<ssl_avs_response />

</txn>

Adding Signature Request

xmldata=<txn>

<ssl_merchant_id>my_virtualmerchant_id</ssl_merchant_id>

<ssl_user_id>my_user_id</ssl_user_id>

<ssl_pin>my_pin</ssl_pin>

<ssl_description>Keyed Sale API</ssl_description>

<ssl_transaction_type>ccsignature</ssl_transaction_type>

<ssl_txn_id>AA49315-DCA463E6-F924-4CA8-9FBF-

01220FBACA19</ssl_txn_id>

</txn>

CON-0002-N

Converge Developer Guide: Transaction Format CON-0002-N

Adding Signature Response

xmldata=<txn>

<ssl_transaction_type>CCSIGNATURE</ssl_transaction_type>

<ssl_user_id>kmintz</ssl_user_id>

<ssl_result>0</ssl_result>

<ssl_result_message>SUCCESS</ssl_result_message>

</txn>

Credit Card Add Recurring Transaction (ccaddrecurring)

The ccaddrecurring is a transaction that adds a credit card recurring record to Converge recurring batch. Once added, the transaction will run automatically within the specified billing cycle on the scheduled payment day without the need to send it for authorization.

To perform a ccaddrecurring, you must submit either:



Card number and expiration date

 The original transaction ID of an approved Sale, Auth Only, Force or refund transaction.

(applicable to

processxml.do

only)



The token in the ssl_token from a previously tokenized card number, expiration date and AVS data is not needed if token is stored in Card Manager

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_show_form ssl_card_number ssl_token

Req? Description

Y Add Credit Card Recurring (ccaddrecurring).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Set value to true to show the Converge Payment Form

(available only for process.do), set to false otherwise.

Required when adding a recurring using a card number.

Credit Card Number as it appears on the credit card.

Required when adding a recurring using a token. If token is stored in Card Manager then the expiration date, first name, last name and AVS data on file will be used.

Use only with a terminal that is setup with Tokenization.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_exp_date ssl_txn_id ssl_amount ssl_next_payment_date Y ssl_billing_cycle Y ssl_bill_on_half

Req? Description

C Required when adding a recurring using a card number.

Credit Card Expiry Date as it appears on credit card formatted as MMYY.

C Required when adding a recurring based on previously approved transaction.

Unique identifier returned on the original transaction, this value replaces the card number, expiration date, billing and shipping information if provided in the original request.

Transaction Amount. Number with 2 decimal places. This amount includes the Net amount and Sales Tax.

Next payment date. Format MM/DD/YYYY.

Billing cycle.

Valid returned values, all caps and no hyphens:



DAILY



WEEKLY



BIWEEKLY

 SEMIMONTHLY



MONTHLY

 BIMONTHLY



QUARTERLY

 SEMESTER



SEMIANNUALLY

 ANNUALLY

 SUSPENDED

Half of the month or Semimonthly indicator.

Valid values are 1 and 2:



1 = the 1st and the 15th of the month

 2 = the 15th and the last day of the month

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_end_of_month ssl_skip_payment ssl_first_name ssl_last_name ssl_avs_zip ssl_avs_address ssl_invoice_number ssl_dynamic_dba ssl_customer_code ssl_salestax

Req? Description

C End of month indicator. Valid values Y or N

You must indicate if the recurring transaction will be processed on the last day of the month for the monthly, bi-monthly, quarterly, semester, and semi-annually billing cycles when the start payment date is any of the following dates:

 30-Apr



30-June

 30-Sept



30-Nov



28-Feb (non-leap year)



29-Feb (leap year)

You also need to provide the end of the month indicator for the annually billing cycles when the start payment date is any of the following dates:



28-Feb (non-leap year)

 29-Feb (leap year)

N Skip Payment field. Valid values: Y for yes or N for no.

Defaulted to N.

Cardholder first name

Cardholder last name

Cardholder ZIP code.

Cardholder Address.

The invoice or ticket number.

User only with a terminal that is setup with DBA.

DBA Name provided by the merchant with each transaction.

The maximum allowable Length of DBA Name variable provided by Merchant can be 21, 17 or 12 based on the length setup for the DBA constant in the field setup.

Recommended for purchasing cards.

The Customer Code or PO Number that appears on the cardholder's credit card billing statement.

Recommended for purchasing cards.

Sales tax amount applied to this transaction in decimal. Tax exempt transactions can pass 0.00 to properly reflect a tax exempt transaction.

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_result ssl_result_message ssl_user_id ssl_card_number ssl_exp_date ssl_amount ssl_billing_cycle ssl_card_number ssl_next_payment_date

Description

Outcome of a transaction. A response that contains ssl_result of 0 represents a successful recurring transaction.

Transaction result message. A result of SUCCESS indicates the recurring was successfully added.

Converge User ID as configured on Converge.

Masked card number.

Returned based on merchant setup.

Recurring amount.

Billing cycle.

Card number. Returned in hashed/masked format.

Next payment due date. ssl_recurring_batch_count Current number of transactions sitting in the recurring batch after the recurring transaction has been added. ssl_recurring_id

The ID number of the recurring record added returned on SUCCESS only. ssl_start_payment_date Start payment date. Format MM/DD/YYYY. Date when the first payment started. If recently added, start date is same as next payment. errorCode errorMessage errorName

information.

Detailed explanation of the error returned only if an error occurred.

This field may be changed based on merchant configuration in the

user interface. Refer to the Error Codes section for more

information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Converge Developer Guide: Transaction Format CON-0002-N

Example

Example 1: process.do(false)

Shown below are the key value pairs from the header by themselves for adding a credit card recurring transaction. ssl_merchant_id=xxxxxx ssl_user_id=xxxxxxx ssl_pin=xxxxxx ssl_show_form=false ssl_transaction_type=ccaddrecurring ssl_card_number=0000000000000000 ssl_exp_date=1208 ssl_amount=1.00 ssl_billing_cycle=SEMESTER ssl_next_payment_date=09/02/2011 ssl_skip_payment=Y ssl_total_installments=4 ssl_avs_zip=70004 ssl_invoice_number=1111 ssl_customer_code=4444 ssl_first_name=John ssl_last_name=Doe

Converge Developer Guide: Transaction Format CON-0002-N

Converge then returns a response to the POST by specifying the http://www.url.com/cgibin/testtran.cgi

URL in the ssl_apprvl_get_url field for the redirect for the transaction above, the following values are returned for the successful transaction.

Shown below are the key value pairs returned when successfully adding a credit card recurring transaction. ssl_start_payment_date=12/12/2011 ssl_transaction_type=CCADDRECURRING ssl_card_number=00**********0000 ssl_exp_date=1212 ssl_amount=10.00 ssl_next_payment_date=12/12/2011 ssl_billing_cycle=SEMESTER ssl_result_message=SUCCESS ssl_recurring_id=AA4844B-6345A73B-296A-03BB-226B-01A66829FA9F ssl_number_of_payments=0 ssl_skip_payment=N ssl_recurring_batch_count=6

Based on the billing cycle and the start date supplied, the recurring transaction will run automatically in the system without further action from the merchant.

By specifying the http://www.url.com/cgi-bin/testtran.cgi URL in the ssl_error_url

Converge Developer Guide: Transaction Format CON-0002-N

Example 2: process.do(true)

This example demonstrates the initiation of a minimal credit card recurring transaction in which

Converge gathers the entire customer’s billing information to automatically charge the customer

$9.95 on a monthly basis. When customers purchase the initial product or service from a website, they can indicate their agreement to automatically renew their subscription and to process payment to their credit card. The Converge Gateway will automatically add this customer to the recurring Billing database and run the payment every month.

Send a ccaddrecurring request

ssl_merchant_id=my_virtualmerchant_id ssl_user_id=my_user_id ssl_pin=my_pin ssl_transaction_type=ccaddrecurring ssl_show_form=true ssl_amount=9.95 ssl_billing_cycle=MONTHLY ssl_result_format=HTML

Response

<input type="hidden" name="ssl_recurring_id" value="AA484C3-

B08B6F1B-4765-A1FF-C0BC-5722F21A0EB6">

<input type="hidden" name="ssl_amount" value="9.95"> input type="hidden" name="ssl_next_payment_date" value="01/01/2012">

</form>

Converge Developer Guide: Transaction Format CON-0002-N

Example 3: processxml.do

The following XML code demonstrates an example of a basic transaction request and response.

ccaddrecurring request

xmldata=<txn>

<ssl_merchant_id>my_virtualmerchant_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>ccaddrecurring</ssl_transaction_type>

<ssl_card_number>0000000000000000</ssl_card_number>

<ssl_exp_date>1212</ssl_exp_date>

<ssl_amount>10.36</ssl_amount>

<ssl_billing_cycle>MONTHLY</ssl_billing_cycle>

<ssl_next_payment_date>01/31/2012</ssl_next_payment_date>

<ssl_end_of_month>Y</ssl_end_of_month>

<ssl_invoice_number>1111</ssl_invoice_number>

</txn>

ccaddrecurring response

<txn>

<ssl_start_payment_date>01/31/2012</ssl_start_payment_date>

<ssl_transaction_type>CCADDRECURRING</ssl_transaction_type>

<ssl_card_number>00**********00000</ssl_card_number>

<ssl_exp_date>1212</ssl_exp_date>

<ssl_amount>10.36</ssl_amount>

<ssl_next_payment_date>01/31/2012</ssl_next_payment_date>

<ssl_billing_cycle>MONTHLY</ssl_billing_cycle>

<ssl_result_message>SUCCESS</ssl_result_message>

<ssl_recurring_id>AA484C3-8E5D1201-A05E-824D-9DAD-

E3534E83F078</ssl_recurring_id>

<ssl_number_of_payments>0</ssl_number_of_payments>

<ssl_skip_payment>N</ssl_skip_payment>

<ssl_recurring_batch_count>65</ssl_recurring_batch_count>

</txn>

Converge Developer Guide: Transaction Format CON-0002-N

Credit Card Update Recurring Transaction (ccupdaterecurring)

The ccupdaterecurring is a transaction that updates a credit card recurring record in

Converge. To perform a ccupdaterecurring, you must submit the recurring ID received from the original credit card recurring transaction.

Note: The ssl_show_form property does not apply on Update transactions.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_recurring_id ssl_card_number ssl_exp_date ssl_amount ssl_next_payment_date ssl_billing_cycle

Req? Description

Y Update Credit Card Recurring (ccupdaterecurring).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

The ID number of the recurring record to be updated. This value, was returned when the original recurring record was added. Alphanumeric.

Credit Card Number as it appears on the credit card.

Credit Card Expiry Date as it appears on credit card formatted as MMYY.

Transaction Amount. Number with 2 decimal places. This amount includes the Net amount and Sales Tax.

Next payment date. Format MM/DD/YYYY.

Billing cycle.

Valid returned values, all caps and no hyphens:



DAILY

 WEEKLY

 BIWEEKLY



SEMIMONTHLY

 MONTHLY



BIMONTHLY

 QUARTERLY



SEMESTER

 SEMIANNUALLY



ANNUALLY

 SUSPENDED

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_bill_on_half ssl_end_of_month ssl_skip_payment ssl_first_name ssl_last_name ssl_avs_zip ssl_avs_address ssl_invoice_number ssl_dynamic_dba ssl_customer_code ssl_salestax

Req? Description

C Half of the month or Semimonthly indicator.

Valid values are 1 and 2:

 1 = The 1st and the 15th of the month



2 = The 15th and the last day of the month

C End of month indicator. Valid values Y or N



30-Apr

 30-June



30-Sept

 30-Nov



28-Feb (non-leap year)

 29-Feb (leap year)

You also need to provide the end of the month indicator for the annually billing cycles when the start payment date is any of the following dates:

 28-Feb (non-leap year)



29-Feb (leap year)

N Skip Payment field.

Valid values: Y for yes or N for no. Defaulted to N.

Cardholder first name

Cardholder last name

Cardholder ZIP code.

Cardholder Address.

The invoice or ticket number.

User only with a terminal that is setup with DBA.

DBA Name provided by the merchant with each transaction.

The maximum allowable Length of DBA Name variable provided by Merchant can be 21, 17 or 12 based on the length setup for the DBA constant in the field setup.

Recommended for purchasing cards.

The Customer Code or PO Number that appears on the cardholder's credit card billing statement.

Recommended for purchasing cards.

Sales tax amount applied to this transaction in decimal. Tax exempt transactions can pass 0.00 to properly reflect a tax exempt transaction.

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_result ssl_result_message

Description

Outcome of a transaction. A response that contains ssl_result of 0 represents a successful transaction.

Transaction result message. A result of SUCCESS indicates the recurring was successfully updated. ERROR indicates the recurring was not updated successfully. ssl_amount ssl_billing_cycle ssl_card_number ssl_next_payment_date ssl_number_of_payments Current number of payments run so far. Numeric. Returned by

Converge. Represents the number of payments run on the system. ssl_recurring_batch_count Current number of transactions sitting in the recurring batch. ssl_recurring_id The ID number of the recurring record updated. Alphanumeric.

Returned on SUCCESS only.

This value is a unique tracking number that the application assigns internally to each recurring record in the database. ssl_start_payment_date

Recurring amount.

Billing cycle.

Card number. Returned in masked format.

Next payment due date. errorCode errorMessage errorName

Start payment date. Format MM/DD/YYYY. Date when the first payment started. If recently added, start date is same as next payment.

Error code returned only if an error occurred. Typically, when the transaction failed validation or the request is incorrect. This prevents the transaction from going to authorization. This is a

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred.

This field may be changed based on merchant configuration in the

user interface. Refer to the Error Codes section for more

information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Converge Developer Guide: Transaction Format CON-0002-N

Example

The following example demonstrates the key value pairs needed to pass the minimum required data to update a credit card recurring transaction and set the billing payment to Suspended. The recurring ID obtained from the original transaction must be passed. ssl_merchant_id=my_virtualmerchant_id ssl_user_id=my_user_id ssl_pin=my_pin ssl_transaction_type=ccupdaterecurring ssl_show_form=false ssl_recurring_id=AA484C3-B08B6F1B-4765-A1FF-C0BC-5722F21A0EB6 ssl_billing_cycle=SUSPENDED

Credit Card Delete Recurring Transaction (ccdeleterecurring)

The ccdeleterecurring is a transaction that deletes a credit card recurring record in

Converge. To perform a ccdeleterecurring, you must submit the recurring ID received from the original credit card recurring transaction.

Note: The ssl_show_form property does not apply on Delete transactions.

Request

Input Field Name Req? Description

ssl_transaction_type Y Delete Credit Card Recurring (ccdeleterecurring). ssl_merchant_id ssl_user_id ssl_pin ssl_recurring_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

The ID number of the recurring record to be updated. This value was returned when the original recurring record was added.

Alphanumeric.

Response

Output Field Name

ssl_result ssl_result_message

Description

Outcome of a transaction. A response that contains ssl_result of 0 represents a successful transaction.

Transaction result message. A result of SUCCESS indicates the recurring was successfully deleted. ERROR indicates the recurring was not deleted successfully.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name Description

ssl_recurring_batch_count Current number of transactions sitting in the recurring batch after the recurring transaction has been deleted. ssl_recurring_id errorCode

The ID number of the recurring record deleted. Alphanumeric.

Returned on SUCCESS only. If the recurring ID was successfully deleted from the database and is no longer showing in the current batch recurring. No Auth or automatic payment can be run on this

ID.

numeric field. Refer to the Error Codes section for more

information. errorMessage errorName

Detailed explanation of the error returned only if an error occurred.

This field may be changed based on merchant configuration in the

user interface. Refer to the Error Codes section for more

information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Credit Card Submit Recurring Payment (ccrecurringsale)

The ccrecurringsale is a transaction that allows you to run a credit card recurring payment outside of its billing cycle, this will increase the payment number. To perform a ccrecurringsale

, you must submit the recurring ID received from the original credit card recurring transaction.

Note: The ssl_show_form property does not apply when submitting payments.

Request

Input Field Name

ssl_transaction_type Y ssl_merchant_id

Req? Description

Submit Credit Card Recurring Payment (ccrecurringsale).

Converge ID as provided by Elavon. ssl_user_id ssl_pin

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive. ssl_recurring_id

Y The ID number of the recurring record to be submitted for payment. This value was returned when the original recurring record was added. Alphanumeric.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_get_token ssl_add_token

Req? Description

N Use only with a terminal that is setup with Tokenization.

Generate Token indicator, used to indicate if you wish to generate a token after processing the recurring sale. Valid value:

Y (generate a token), N (do not generate token). Defaulted to N.

Once generated, the token number can be stored and used as a substitute for a card number at later time.

N Use only with a terminal that is setup with Tokenization.

Add to Card Manager indicator, used to indicate if you wish to generate a token and store it in Card Manager. Valid value: Y

(add token) , N (do not add token) Defaulted to N

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id ssl_txn_time

Description

Outcome of a transaction. A response that contains an ssl_result of

0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized.

Transaction result message. Example: APPROVAL, PARTIAL APPROVAL.

Refer to the Authorization Response Codes section for an extensive list

of possible returned messages.

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 09/18/2011 10:34:10 AM. ssl_amount ssl_approval_code ssl_billing_cycle ssl_card_number ssl_exp_date

Transaction authorized or approved amount. Returned based on merchant setup.

Transaction approval code.

Billing cycle.

Masked card number.

Returned based on merchant setup. ssl_invoice_number ssl_next_payment_date

Invoice or ticket number sent originally on the request. Returned based on merchant setup.

Next payment due date. ssl_number_of_payments Current number of payments run so far. Numeric. Returned by

Converge. This number represents the number of payments run on the system.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_recurring_id errorCode errorMessage errorName

Description

ID number of the recurring record. Alphanumeric. Returned on

SUCCESS only.

Refer to the Error Codes section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user

interface. Refer to the Error Codes section for more information.

Error name or reason for the error returned only if an error occurred.

Refer to the Error Codes section for more information.

Example

The following example demonstrates the key value pairs needed to pass the minimum required data to send a recurring sale outside of the billing cycle. The recurring ID obtained from the original transaction must be passed. This transaction will increase the total payments. ssl_merchant_id=my_virtualmerchant_id ssl_user_id=my_user_id ssl_pin=my_pin ssl_transaction_type=ccrecurringsale ssl_show_form=false ssl_recurring_id=AA484C3-B08B6F1B-4765-A1FF-C0BC-5722F21A0EB6

Credit Card Add Installment Transactions (ccaddinstall)

The ccaddinstall is a transaction that adds a credit card installment record to Converge recurring batch. Once added, the transaction will run automatically within the specified billing cycle on the scheduled payment day without the need to send it for authorization.

To perform a ccaddinstall, you must submit either:



Card number and expiration date.



The original transaction ID of an approved Sale, Auth Only, Force or refund transaction.

(applicable to

processxml.do

only)

Converge Developer Guide: Transaction Format CON-0002-N

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_show_form ssl_card_number ssl_token ssl_exp_date ssl_txn_id ssl_amount ssl_total_installments Y ssl_next_payment_date Y ssl_billing_cycle Y

Req? Description

Y Add Credit Card Installment (ccaddinstall).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Set value to true to show the Converge Payment Form

(available only for process.do), set to false otherwise.

Required when adding an installment using a card number.

Credit Card Number as it appears on the credit card.

Required when adding an installment using a token. If token is stored in Card Manager then the expiration date, first name, last name and AVS data on file will be used.

Use only with a terminal that is setup with Tokenization.

Required when adding an installment using a card number.

Credit Card Expiry Date as it appears on credit card formatted as MMYY.

Required when adding an installment based on previously approved transaction.

Unique identifier returned on the original transaction, this value replaces the card number, expiration date, billing and shipping information if provided in the original request.

Transaction Amount. Number with 2 decimal places. This amount includes the Net amount and Sales Tax.

Number of payments, Numeric.

Next payment date. Format MM/DD/YYYY.

Billing cycle.

Valid returned values, all caps and no hyphens:



DAILY

 WEEKLY



BIWEEKLY

 SEMIMONTHLY



MONTHLY

 BIMONTHLY



QUARTERLY



SEMESTER



SEMIANNUALLY



ANNUALLY

 SUSPENDED

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_bill_on_half ssl_end_of_month ssl_skip_payment ssl_first_name ssl_last_name ssl_avs_zip ssl_avs_address ssl_invoice_number ssl_dynamic_dba ssl_customer_code ssl_salestax

Req? Description

C Half of the month or Semimonthly indicator.

Valid values are 1 and 2:

 1 = The 1st and the 15th of the month



2 = The 15th and the last day of the month

C End of month indicator. Valid values Y or N

You must indicate if the recurring transaction will be processed on the last day of the month for the monthly, bimonthly, quarterly, semester, and semi-annually billing cycles when the start payment date is any of the following dates:



30-Apr

 30-June



30-Sept

 30-Nov



28-Feb (non-leap year)

 29-Feb (leap year)

You also need to provide the end of the month indicator for the annually billing cycles when the start payment date is any of the following dates:

 28-Feb (non-leap year)



29-Feb (leap year)

N Skip Payment field.

Valid values: Y for yes or N for no. Defaulted to N.

Cardholder first name

Cardholder last name

Cardholder ZIP code.

Cardholder Address.

The invoice or ticket number.

User only with a terminal that is setup with DBA.

DBA Name provided by the merchant with each transaction.

The maximum allowable Length of DBA Name variable provided by Merchant can be 21, 17 or 12 based on the length setup for the DBA constant in the field setup.

Recommended for purchasing cards.

The Customer Code or PO Number that appears on the cardholder's credit card billing statement.

Recommended for purchasing cards.

Sales tax amount applied to this transaction in decimal. Tax exempt transactions can pass 0.00 to properly reflect a tax exempt transaction

136

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_result ssl_result_message ssl_amount

Description

Outcome of a transaction. A response that contains an ssl_result

of 0 represents a successful transaction.

Transaction result message. A result of SUCCESS indicates the installment was successfully added. ERROR indicates the installment was not added successfully.

Recurring amount. ssl_billing_cycle ssl_card_number ssl_installment_id ssl_next_payment_date Next payment due date. ssl_recurring_batch_count Current number of transactions sitting in the recurring batch after the installment transaction has been added. ssl_start_payment_date Start payment date. Format MM/DD/YYYY. Date when the first payment started. If recently added, start date is same as next payment. ssl_total_installments

Billing cycle.

Card number. Returned in masked format.

The ID number of the installment record added. Returned on

SUCCESS only. errorCode errorMessage errorName

Total number of payments. Numeric.

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred.

This field may be changed based on merchant configuration in the

user interface. Refer to the Error Codes section for more

information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Converge Developer Guide: Transaction Format CON-0002-N

Example

Example 1: process.do (true):

The following example demonstrates a basic request that collects and passes the minimum required data to setup an installment transaction twice a month for 10 total installments, starting from 01/01/2012 and processing on the 1st and 15th of every month. This code will call the payment form that displays the customer’s payment and asks for their credit card number and expiration date. After the user enters the information and clicks the process button, Converge will automatically add this customer to the recurring billing database and run the payment twice a month for 10 consecutive payments. The user is then taken directly to a response page. Shown below are the key value pairs from the header by themselves for this transaction: ssl_merchant_id=my_virtualmerchant_id ssl_user_id=my_user_id ssl_pin=my_pin ssl_transaction_type=ccaddinstall ssl_show_form=true ssl_billing_cycle=SEMIMONTHLY ssl_next_payment_date=01/01/2012 ssl_bill_on_half=1 ssl_amount=75.00 ssl_total_installments=10

Converge Developer Guide: Transaction Format

Example 2 processxml.do:

Request

xmldata=<txn>

<ssl_merchant_id>my_virtualmerchant_id</ssl_merchant_id>

<ssl_user_id>my_user_id</ssl_user_id>

<ssl_pin>my_pin</ssl_pin>

<ssl_card_number>0000000000000000</ssl_card_number>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_amount>5.00</ssl_amount>

<ssl_transaction_type>ccaddinstall</ssl_transaction_type>

<ssl_customer_code>FF1234</ssl_customer_code>

<ssl_billing_cycle>WEEKLY</ssl_billing_cycle>

<ssl_next_payment_date>01/30/2014</ssl_next_payment_date>

<ssl_total_installments>10</ssl_total_installments>

<ssl_first_name>John</ssl_first_name>

<ssl_last_name>Doe</ssl_last_name>

<ssl_avs_address>123 Main</ssl_avs_address>

<ssl_city>Atlanta</ssl_city>

<ssl_state>GA</ssl_state>

<ssl_avs_zip>30123</ssl_avs_zip>

<ssl_country>USA</ssl_country>

</txn>

CON-0002-N

Converge Developer Guide: Transaction Format CON-0002-N

Response

<txn>

<ssl_last_name>Doe</ssl_last_name>

<ssl_result_message>SUCCESS</ssl_result_message>

<ssl_country>USA</ssl_country>

<ssl_city>Atlanta</ssl_city>

<ssl_number_of_payments>0</ssl_number_of_payments>

<ssl_billing_cycle>WEEKLY</ssl_billing_cycle>

<ssl_start_payment_date>01/30/2014</ssl_start_payment_date>

<ssl_transaction_type>CCADDINSTALL</ssl_transaction_type>

<ssl_total_installments>10</ssl_total_installments>

<ssl_avs_zip>30123</ssl_avs_zip>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_avs_address>123 Main</ssl_avs_address>

<ssl_salestax>0</ssl_salestax>

<ssl_next_payment_date>01/30/2014</ssl_next_payment_date>

<ssl_address2/>

<ssl_skip_payment>N</ssl_skip_payment>

<ssl_first_name>John</ssl_first_name>

<ssl_recurring_batch_count>23</ssl_recurring_batch_count>

<ssl_amount>5.00</ssl_amount>

<ssl_state>GA</ssl_state>

<ssl_card_number>00**********0000</ssl_card_number>

<ssl_installment_id>AA49315-AB9B8587-ECE6-445A-A2A4-

3B00A9985C0A</ssl_installment_id>

</txn>

Converge Developer Guide: Transaction Format CON-0002-N

Credit Card Update Installment Transactions (ccupdateinstall)

The ccupdateinstall is a transaction that updates a credit card installment record in

Converge. To perform a ccupdateinstall, you must submit the installment ID received from the original credit card installment transaction.

Note: The ssl_show_form property does not apply on Update transactions.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_installment_id ssl_card_number ssl_exp_date ssl_amount ssl_total_installments N ssl_next_payment_date ssl_billing_cycle

Req? Description

Y Update Credit Card Installment (ccupdateinstall).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

The ID number of the installment record to be updated.

Alphanumeric.

Credit Card Number as it appears on the credit card.

Credit Card Expiry Date as it appears on credit card formatted as MMYY.

Transaction Amount. Number with 2 decimal places. This amount includes the Net amount and Sales Tax.

Number of payments, Numeric.

Next payment date. Format MM/DD/YYYY.

Billing cycle.

Valid returned values, all caps and no hyphens:

 DAILY



WEEKLY

 BIWEEKLY



SEMIMONTHLY

 MONTHLY



BIMONTHLY

 QUARTERLY



SEMESTER



SEMIANNUALLY



ANNUALLY



SUSPENDED

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_bill_on_half ssl_end_of_month ssl_skip_payment ssl_first_name ssl_last_name ssl_avs_zip ssl_avs_address ssl_invoice_number ssl_dynamic_dba ssl_customer_code ssl_salestax

Req? Description

C Half of the month or Semimonthly indicator.

Valid values are 1 and 2:

 1 = The 1st and the 15th of the month



2 = The 15th and the last day of the month

C End of month indicator. Valid values Y or N



30-Apr

 30-June



30-Sept

 30-Nov



28-Feb (non-leap year)

 29-Feb (leap year)

You also need to provide the end of the month indicator for the annually billing cycles when the start payment date is any of the following dates:

 28-Feb (non-leap year)



29-Feb (leap year)

N Skip Payment field.

Valid values: Y for yes or N for no. Defaulted to N.

Cardholder first name

Cardholder last name

Cardholder ZIP code.

Cardholder Address.

The invoice or ticket number.

User only with a terminal that is setup with DBA.

DBA Name provided by the merchant with each transaction.

The maximum allowable Length of DBA Name variable provided by Merchant can be 21, 17 or 12 based on the length setup for the DBA constant in the field setup.

Recommended for purchasing cards.

The Customer Code or PO Number that appears on the cardholder's credit card billing statement.

Recommended for purchasing cards.

Sales tax amount applied to this transaction in decimal. Tax exempt transactions can pass 0.00 to properly reflect a tax exempt transaction.

142

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_result ssl_result_message ssl_installment_id ssl_amount ssl_billing_cycle ssl_card_number

Description

Outcome of a transaction. A response that contains a ssl_result of 0 represents a successful transaction.

Transaction result message. A result of SUCCESS indicates the installment was successfully updated. ERROR indicates the installment was not updated successfully.

ID number of the installment record updated. Returned on

SUCCESS only.

Recurring amount.

Billing cycle.

Card number. Returned in masked format. ssl_next_payment_date ssl_number_of_payments ssl_recurring_batch_count Current number of transactions sitting in the recurring batch. ssl_start_payment_date ssl_total_installments

Start payment date. Format MM/DD/YYYY. Date when the first payment started. If recently added, start date is same as next payment.

Total number of payments. Numeric. errorCode

Next payment due date.

Current number of payments run so far. Numeric. Returned by

Converge. This number represent the number of payments run on the system. It is less than or equal to the total installments setup originally in the system. errorMessage errorName

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred.

This field may be changed based on merchant configuration in the

user interface. Refer to the Error Codes section for more

information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Converge Developer Guide: Transaction Format CON-0002-N

Credit Card Delete Installment Transactions (ccdeleteinstall)

The ccdeleteinstall is a transaction that deletes a credit card installment record in Converge.

To perform a ccdeleteinstall, you must submit the installment ID received from the original credit card installment transaction.

Note: The ssl_show_form property does not apply on Delete transactions.

Request

Input Field Name Req? Description

ssl_transaction_type

Y Delete Credit Card Installment (ccdeleteinstall). ssl_merchant_id ssl_pin

Converge ID as provided by Elavon.

Converge PIN as configured within Converge, case sensitive. ssl_user_id ssl_installment_id

Converge User ID as configured on Converge, case sensitive.

ID number of the recurring record to be deleted. Alphanumeric.

Response

Output Field Name

ssl_result errorName

Description

Outcome of a transaction. A response that contains ssl_result of 0 represents a successful transaction. ssl_result_message ssl_installment_id ID number of the installment record updated. Returned on

SUCCESS, only if the installment record was deleted successfully. ssl_recurring_batch_count Current number of transactions sitting in the recurring batch after the installment transaction has been deleted. errorCode

Transaction result message. A result of SUCCESS indicates the installment was successfully deleted. ERROR indicates the installment was not deleted successfully.

numeric field. Refer to the Error Codes section for more

information. errorMessage Detailed explanation of the error returned only if an error occurred.

This field may be changed based on merchant configuration in the

user interface. Refer to the Error Codes section for more

information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Converge Developer Guide: Transaction Format CON-0002-N

Credit Card Submit Installment Payment (ccinstallsale)

The ccinstallsale is a transaction that allows you to run a credit card installment payment outside of its billing cycle. This will increase the payment number. To perform a ccinstallsale, you must submit the installment ID received from the original credit card installment transaction.

Note: The ssl_show_form property does not apply when submitting payments.

Request

Input Field Name Req? Description

ssl_transaction_type

Y Submit Credit Card Installment Payment (ccinstallsale). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin ssl_installment_id

Converge PIN as configured within Converge, case sensitive.

ID number of the recurring record to be authorized.

Alphanumeric. ssl_get_token ssl_add_token

Use only with a terminal that is setup with Tokenization.

Generate Token indicator, used to indicate if you wish to generate a token after processing the installment. Valid value: Y

(generate a token), N (do not generate token). Defaulted to N.

Once generated, the token number can be stored and used as a substitute for a card number at later time.

Use only with a terminal that is setup with Tokenization.

Add to Card Manager indicator, used to indicate if you wish to generate a token and store it in Card Manager. Valid value: Y

(add token), N (do not add token) Defaulted to N

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_result

Description

Transaction result message. Example: APPROVAL, PARTIAL APPROVAL.

Refer to the Authorization Response Codes section for an extensive list

of possible returned messages.

Transaction authorized or approved amount. Returned based on merchant setup.

Transaction approval code.

Billing cycle. ssl_card_number ssl_exp_date ssl_installment_id

Masked card number.

Returned based on merchant setup.

The ID number of the installment record submitted. Returned on

SUCCESS, only if the installment record was deleted successfully. ssl_invoice_number ssl_next_payment_date

Invoice or ticket number sent originally on the request. Returned based on merchant setup.

Next payment due date. ssl_number_of_payments Current number of payments run so far. Numeric. Returned by

Converge. ssl_start_payment_date Date when the first payment started. If recently added, start date is same as next payment. ssl_total_installments Total number of payments. Numeric. ssl_txn_id Transaction identification number. This is a unique number used to identify the transaction. ssl_txn_time errorCode errorMessage

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 09/18/2011 10:34:10 AM.

Refer to the Error Codes section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user

interface. Refer to the Error Codes section for more information.

errorName Error name or reason for the error returned only if an error occurred.

Refer to the Error Codes section for more information.

Converge Developer Guide: Transaction Format CON-0002-N

Debit Card Transactions

Debit transactions require integration to a PIN pad that is injected with Elavon keys to retrieve the following information:



DUKPT Value: This is the value returned by the PIN pad device which was used to encrypt the cardholder’s PIN, using the Derived Unique Key per Transaction (DUKPT) method.



PIN Block: The encrypted PIN entered by a Debit/EBT cardholder as identification for a transaction.

Debit transactions may only be performed in a retail, service or face to face environments. Mail

Order/Telephone Order and e-Commerce businesses cannot perform online PIN based debit transactions.

Note: Track II card swipe is required. Manual entry is not allowed.

Debit Purchase (dbpurchase)

The dbpurchase causes the amount of the purchase to be deducted from the debit cardholder‘s checking or saving account, debiting the account immediately.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_track_data ssl_amount ssl_cashback_amount

Req? Description

Y Debit Purchase/Sale (dbpurchase).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

The raw Track I or Track II data from the magnetic strip on the card. The track data captured from the swipe device cannot be manipulated and must be passed at the time of the transaction. This includes the beginning and ending sentinels that are included in the track data. Raw track data cannot be stored under any circumstances.

Transaction base amount must be sent on request. This amount does not include the cash back amount or tip amount which must be sent separately. The system will then compute the total to send for authorization. For example:

1.00.

Cash back. The amount of cash back that the customer will receive. Must be a number with two decimal places, if sent.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_tip_amount ssl_server ssl_shift ssl_account_type ssl_dukpt ssl_key_pointer ssl_pin_block

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id ssl_txn_time ssl_account_type ssl_amount ssl_base_amount

Req? Description

N Tip or gratuity amount to be added to the transaction sale amount. Number with two decimal places, can be 0.00 to indicate no tip was provided. Only used in a Service market segment.

N Server ID, this is the clerk, cashier, and waiter or waitress identification number. Only used in a Service market segment.

Alphanumeric, Example: Jack.

N Shift, can refer to or be used to identify time period, course or type of service, Only used in a Service market segment.

Alphanumeric, Example: Lunch.

Account Type (0 = checking, 1 = saving).

This is the value returned by the PIN pad device, which was used to encrypt the cardholder’s Personal Identification

Number (PIN) using the Derived Unique Key Per Transaction

(DUKPT) method. This value cannot be stored.

Triple-DES DUKPT pointer that indicates to Elavon which encryption key was used for US Debit transactions. Value must be set to T.

The encrypted PIN block as returned from the PIN pad device. This value cannot be stored.

Description

Outcome of a transaction. A response that contains ssl_result

of 0 represents an approved transaction.

Transaction result message. For example: APPROVAL. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized.

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. For example: 03/18/2010

10:34:10.AM.

Account Type (0 = checking, 1 = saving).

Transaction total amount including surcharge or cash back.

Returned based on merchant setup.

Base amount. The amount sent originally on the request.

Converge Developer Guide: Transaction Format

Output Field Name

ssl_surcharge_amount ssl_cashback_amount ssl_base_amount ssl_tip_amount ssl_approval_code ssl_reference_number ssl_card_number ssl_exp_date ssl_server ssl_shift ssl_email ssl_promo_list errorCode errorMessage

CON-0002-N

Description

Surcharge amount. The fee that a merchant can charge for transactions as a cost for doing business. It is configurable in the application.

Cash back. The amount of cash back that the customer will receive.

Base amount. Transaction amount sent originally on the request.

Returned based on merchant setup. Only used in a Service market segment.

Tip or gratuity amount that was added or updated. Returned based on merchant setup. Only used in a Service market segment.

Transaction approval code.

Transaction reference number.

Masked card number.

Returned based on merchant setup.

Server ID submitted with the request. Only returned on Service market segment based on the merchant setup.

Shift information submitted with the request. Only returned on

Service market segment based on the merchant setup.

Returned based on merchant setup.

The promo list will contain 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

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant

configuration in the user interface. Refer to the Error Codes

section for more information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

errorName

Converge Developer Guide: Transaction Format CON-0002-N

Debit Return (dbreturn)

The dbreturn causes the amount of the transaction to be refunded back to the debit cardholder‘s checking or saving account. The balance is reflected in the account immediately. The

Reference Number, Date and Time of Original Transaction must be passed.

Note: The merchant must contact Elavon to make sure that Debit refunds are enabled for the terminal.

Request

Input Field Names Req? Description

ssl_transaction_type Y

Debit Return (dbreturn). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin ssl_track_data

Converge PIN as configured within Converge, case sensitive.

The raw Track I or Track II data from the magnetic strip on the card. The track data captured from the swipe device cannot be manipulated and must be passed at the time of the transaction.

This includes the beginning and ending sentinels that are included in the track data. Raw track data cannot be stored under any circumstance. ssl_amount ssl_account_type ssl_dukpt ssl_pin_block

Transaction amount to refund.

The debit account type (0 = checking, 1 = saving).

Value returned by the PIN pad device, which was used to encrypt the cardholder’s Personal Identification Number (PIN) using the

Derived Unique Key Per Transaction (DUKPT) method. This value cannot be stored under any circumstance.

Encrypted PIN block as returned from the PIN pad device. This value cannot be stored under any circumstances. ssl_key_pointer ssl_original_date ssl_original_time

Y ssl_reference_number Y

Triple-DES DUKPT pointer that indicates to Elavon which encryption key was used for US Debit transactions. Value must be set to T.

Date of original transaction in MMDDYY format.

Time of original transaction in HHMMSS format.

Transaction reference number is returned in the authorization response message.

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id ssl_txn_time

Description

Transaction result message. For example: APPROVAL.

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM. ssl_amount ssl_approval_code ssl_card_number ssl_cashback_amount errorName

Transaction amount. Returned based on merchant setup.

Transaction approval code.

Masked card number.

Cash back. The amount of cash back that the customer will receive. ssl_email Returned based on merchant setup. ssl_reference_number Transaction reference number. errorCode Error code returned only if an error occurred. 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. Refer

interface. Refer to the Error Codes section for more information.

errorMessage Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user

Error name or reason for the error returned only if an error occurred. Refer

Debit Inquiry (dbbainquiry)

The dbbainquiry returns the balance available in the cardholder‘s checking or saving account.

Note: Track II card swipe is required. Manual entry is not allowed.

Converge Developer Guide: Transaction Format CON-0002-N

Request

Input Field Name Req? Description

ssl_transaction_type Y Debit Inquiry (dbbainquiry). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin ssl_track_data

Y ssl_account_type ssl_dukpt ssl_pin_block ssl_key_pointer

Converge PIN as configured within Converge, case sensitive.

The raw Track I or Track II data from the magnetic strip on the card. The track data captured from the swipe device cannot be manipulated and must be passed at the time of the transaction.

This includes the beginning and ending sentinels that are included in the track data. Raw track data cannot be stored under any circumstances.

Account Type (0 = checking, 1 = saving).

This is the value returned by the PIN pad device which was used to encrypt the cardholder’s Personal Identification Number (PIN) using the Derived Unique Key Per Transaction (DUKPT) method.

This value cannot be stored.

The encrypted PIN Block as returned from the PIN pad device.

This value cannot be stored.

Triple-DES DUKPT pointer that indicates to Elavon which encryption key was used for US Debit transactions. Value must be set to T.

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id ssl_account_balance ssl_approval_code ssl_card_number ssl_email

Description

Outcome of a transaction. A response that contains a ssl_result of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized.

Transaction result message. Example: APPROVAL.

Transaction identification number. This is a unique number used to identify the transaction.

Balance on the card.

Transaction approval code.

Masked card number.

Returned based on merchant setup. ssl_exp_date Returned based on merchant setup. ssl_reference_number Transaction reference number. ssl_txn_time Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

errorCode errorMessage errorName

Description

interface. Refer to the Error Codes section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user

Error name or reason for the error returned only if an error occurred. Refer

PIN transaction, refer the EMV section.

EMV Credit/ Debit Card Transactions

This message format is used to process encrypted chip credit or debit cards using an EMV capable device. For more information on the processes and flows related to processing Chip and

Important Notes:



Region Support



This format is supported in the US region only.



Chip transactions are only applicable for retail and service market with a terminal that is setup with EMV.



API Support



This format is only supported when using processxml.do for XML formatted requests.



This format is limited to Sale, Auth only and reversal transactions; to support other transaction types as swiped or keyed, you can consult various sections under the

“Transaction format” chapter.



Only the minimum required fields, are shown in this section. Additional fields may be passed at transaction run time. Required fields are based on the merchant account configuration within Converge. For an extensive list of available XML value

pair input fields, refer to the

Supported Transaction Input Fields

section.



Credentials

A unique API user different from the Merchant Admin (MA) user ID must be used.

Converge Developer Guide: Transaction Format CON-0002-N



Card data

You must pass one of the following fields:

 Track data in the ssl_track_data for swiped or contactless (MSD) transactions.

 The encrypted data value in the ssl_tlv_enc

for chip transactions.



Contactless (MSD)

(proximity capable) and ssl_entry_mode of 04 (proximity read). Those values are defaulted to swiped when track data is sent alone.



Tip Processing

For Service market segment, the tip amount must be sent along with the transaction amount. The transaction amount must reflect the total amount to be authorized which includes the tip. This is applicable for EMV Chip Sale

(emvchipsale) and EMV Swipe Sale (emvswipesale).

For chip transactions, you must pass the tip at the time of the authorization; updating the tip after the transaction is not allowed with emvchipsale (Cashierbased processing only)

For swiped transactions with emvswipesale, you can pass the tip at the time of the authorization (Cashier-based processing) and update the tip after authorization (Server-based processing) if needed.



Device support



The integrator must be familiar with the processes involved in communicating with a chip card and a device. Developers must integrate with a supported Ingenico device in order to extract the encrypted tag length value (TLV) for a chip read transaction or encrypted track data for fallback or swipe.



The following types of devices are supported:



Ingenico Smart Terminals: Multi lane such as the isc250 touch or PINpads such as the ipp320 PINpad running on RBA 14.X operating system

 Ingenico Mobile Solutions: Mobile smart terminal such as an iCMP device or mPOS card reader such as RP457 or RP350



Encryption: device must use the generic TDES DUKPT encryption scheme



Ingenico RBA devices support display and prompting of tip in the device prior to prompting to insert or swipe.



EMV certification to the supported association is required once the integration is completed.

Converge Developer Guide: Transaction Format CON-0002-N

EMV Chip Sale (emvchipsale)

The emvchipsale transaction is used to obtain real-time Sale authorization for a chip credit card or debit card. When the authorization is obtained, the transaction is entered into the unsettled batch.

Notes:

 An emvchipupdatetxn transaction must be sent once an emvchipsale has been completed and Chip card has returned additional data.

 POS system will need to update the chip/device with the issuer script received from the authorization.



The emvreverse transaction must be sent to reverse an approved authorization from a chip Sale after a “decline by card” is received from the Chip.

 An emvkeyexchange transaction must be sent if ssl_update_emv_keys equals value of Y is returned in the emvchipsale response.



The amount sent in the authorisation must include the tip amount for Service market segment.

 The tip amount cannot be modified for a chip transaction.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_tlv_enc ssl_enc_track_data_format C ssl_invoice_number ssl_customer_code

Req? Description

Y EMV Chip Sale (emvchipsale).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Encrypted Tag Length Value data defining this EMV record. This value also includes the total amount sent for authorization which includes the tip.

Required only if card is read from a ROAM device. Valid value: ROAM_GENERIC_TDES_EMV

The invoice or ticket number.

Recommended for purchasing cards.

The Customer Code or PO Number that appears on the cardholder's credit card billing statement.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_salestax ssl_tip_amount ssl_decline_offline ssl_get_token

Req? Description

N Recommended for purchasing cards.

Sales tax amount applied to this transaction in decimal.

Tax exempt transactions can pass 0.00 to properly reflect a tax exempt transaction.

Use only in a Service market segment

Tip or gratuity applied to this transaction in decimal. The gratuity amount is included in the amount sent in the tlv value.

Decline Offline indicator defaulted to N when not sent.

Valid values are



Y: The chip card or chip reader has declined this transaction. Converge will not attempt to authorize and will show a decline under the error batch.



N: No Decline from Chip or device.

N ssl_partial_auth_indicator

Use only with a terminal that is setup with Tokenization.

Generate Token indicator, used to indicate if you wish to generate a token after processing the transaction.

Valid value: Y (generate a token), N (do not generate token). Defaulted to N.

Once generated, the token number can be stored and used as a substitute for a card number at later time.

The partial indicator flag must be sent to indicate that the application supports partial approval.

Valid values:



0 – Partial Auth not supported

 1 – Partial Auth supported

Response

Output Field Name

ssl_transaction_type ssl_result ssl_result_message ssl_txn_id

Description

emvchipsale

Outcome of a transaction. A response that contains ssl_result

of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized.

Transaction result message. Example: APPROVAL. Refer to the

Authorization Response Codes section for an extensive list of

possible returned messages.

Transaction identification number. This is a unique number used to identify the transaction.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_txn_time ssl_approval_code ssl_amount ssl_base_amount ssl_tip_amount ssl_card_number ssl_invoice_number ssl_icc_issuerscript ssl_icc_csn ssl_icc_atc ssl_issuer_response ssl_icc_arpc ssl_update_emv_keys ssl_icc_cardtype ssl_icc_cvmr ssl_icc_aid ssl_icc_tvr ssl_icc_tsi ssl_icc_arc ssl_icc_app_name ssl_card_scheme ssl_debit_response_code

Description

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10

AM.

Transaction approval code.

The total transaction authorized or approved amount. Returned based on merchant setup.

Base amount. Transaction amount sent originally on the request.

Returned based on merchant setup. Returned in a Service market segment.

Tip or gratuity amount. Returned based on merchant setup.

Returned in a Service market segment.

Masked card number for this transaction.

The invoice or ticket number sent originally on the request.

Returned based on merchant setup.

This value is used to return the Issuer back to the POS in the authorization response message.

Card Sequence Number. This value is used to differentiate chip cards using the same Primary Account Number (PAN).

This is an incrementing counter value that is managed by the application in the chip card.

Two character response from the issuer.

This value contains data sent to the chip card for online issuer authentication.

This value will indicate if a key exchange is needed. Valid values are Y or N. If the value is equal to Y, the issuer keys have changed and the client needs to perform an EMV key exchange.

Transaction card type (credit/debit)

Card verification method result.

Application ID used.

Terminal verification result.

Transaction status information.

Authorization response code.

Name of the application used.

The long name of the Association as defined in Converge BIN file.

This value is the response returned by the debit gateway for a

Canadian debit authorization attempt.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

errorCode errorMessage errorName

Description

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant

configuration in the user interface. Refer to the Error Codes

section for more information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

EMV Chip Auth Only (emvchipauthonly)

The emvchipauthonly transaction is used to obtain real-time Auth Only authorization for a chip credit card. This transaction will guarantee that the funds are available on the card and reduce the cardholder‘s limit to buy for only a predetermined amount of time. To place the transaction in the open batch, it must be converted to Sale using cccomplete, or reversed using ccdelete

to restore the funds back to the card.

Notes:



An emvchipupdatetxn transaction must be sent once an emvchipauthonly has been completed and Chip card has returned additional data.



POS system will need to update the chip/device with the issuer script received from the authorization.

 The emvreverse transaction must be sent to reverse an approved authorization from a chip after a “decline by card” is received from the Chip.



An emvkeyexchange transaction must be sent if ssl_update_emv_keys equals value of Y is returned in the emvchipsale response.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin

Req? Description

EMV Chip Auth Only (emvchipauthonly).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Y Converge PIN as configured within Converge, case sensitive.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_tlv_enc

Req? Description

Y ssl_enc_track_data_format C

Encrypted Tag Length Value data defining this EMV record.

Required only if card is read from a ROAM device. Valid value: ROAM_GENERIC_TDES_EMV ssl_invoice_number ssl_customer_code

N ssl_salestax ssl_decline_offline ssl_get_token

N ssl_partial_auth_indicator N

The invoice or ticket number.

Recommended for purchasing cards.

The Customer Code or PO Number that appears on the cardholder's credit card billing statement.

Recommended for purchasing cards.

Sales tax amount applied to this transaction in decimal.

Tax exempt transactions can pass 0.00 to properly reflect a tax exempt transaction.

Decline Offline indicator defaulted to N when not sent.

Valid values are

 Y: The chip card or chip reader has declined this transaction. Converge will not attempt to authorize and will show a decline under the error batch.



N: No Decline from Chip or device.

Use only with a terminal that is setup with Tokenization.

Generate Token indicator, used to indicate if you wish to generate a token after processing the transaction.

Valid value: Y (generate a token), N (do not generate token). Defaulted to N.

Once generated, the token number can be stored and used as a substitute for a card number at later time.

The partial indicator flag must be sent to indicate that the application supports partial approval.

Valid values:



0 – Partial Auth not supported



1 – Partial Auth supported

Response

Output Field Name

ssl_transaction_type ssl_result

Description

emvchipauthonly

Outcome of a transaction. A response that contains ssl_result

of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_result_message ssl_txn_id ssl_txn_time ssl_approval_code ssl_amount ssl_card_number ssl_invoice_number ssl_icc_issuerscript ssl_icc_csn ssl_icc_atc ssl_issuer_response ssl_icc_arpc ssl_update_emv_keys ssl_icc_cardtype ssl_icc_cvmr ssl_icc_aid ssl_icc_tvr ssl_icc_tsi ssl_icc_arc ssl_icc_app_name ssl_card_scheme ssl_debit_response_code

Description

Transaction result message. Example: APPROVAL. Refer to the

Authorization Response Codes section for an extensive list of

possible returned messages.

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10

AM.

Transaction approval code.

The total transaction authorized or approved amount. Returned based on merchant setup.

Masked card number for this transaction.

The invoice or ticket number sent originally on the request.

Returned based on merchant setup.

This value is used to return the Issuer back to the POS in the authorization response message.

Card Sequence Number. This value is used to differentiate chip cards using the same Primary Account Number (PAN).

This is an incrementing counter value that is managed by the application in the chip card.

Two character response from the issuer.

This value contains data sent to the chip card for online issuer authentication.

This value will indicate if a key exchange is needed. Valid values are Y or N. If the value is equal to Y, the issuer keys have changed and the client needs to perform an EMV key exchange.

Transaction card type (credit/debit)

Card verification method result.

Application ID used.

Terminal verification result.

Transaction status information.

Authorization response code.

Name of the application used.

The long name of the Association as defined in Converge BIN file.

This value is the response returned by the debit gateway for a

Canadian debit authorization attempt.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

errorCode errorMessage errorName

Description

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant

configuration in the user interface. Refer to the Error Codes

section for more information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

EMV Swipe Sale (emvswipesale)

The emvswipesale transaction is used to obtain real-time Sale authorization for a swiped credit or debit card for an EMV terminal. This format will cover chip cards in a fall back situation, regular swiped cards as well as any non-supported chip cards. When the authorization is obtained, the transaction is entered into the unsettled batch.

Notes:



An emvchipupdatetxn transaction must be sent once an emvchipsale has been completed and Chip card has returned additional data.

 POS system will need to update the chip/device with the issuer script received from the authorization.



The emvreverse transaction must be sent to reverse an approved authorization from a chip Sale after a “decline by card” is received from the Chip.



An emvkeyexchange transaction must be sent if ssl_update_emv_keys equals value of Y is returned in the emvchipsale response.



The amount sent in the authorisation must include the tip amount for Service market segment.



The tip amount can be modified after approval using ccupdatetip.

Converge Developer Guide: Transaction Format CON-0002-N

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_enc_track_data ssl_enc_track_data_format ssl_ksn ssl_amount ssl_icc_fallback

Req? Description

Y EMV Swipe Sale (emvswipesale).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Full encrypted track data required for swiped transactions.

Required only if card is read from a ROAM device. Valid value: ROAM_GENERIC_TDES_EMV

Required when sending track data from an encrypting device for payment cards.

(DUKPT) method. It is a 10 byte composite field that is transmitted as 20 alphanumeric character fixed length.

The total sale amount in decimal, include tax or tip amount if applicable. For example: 1.00.

Fallback indicator defaulted to N when not sent. Valid values are

 Y : chip read was attempted and failed



N: Swipe ssl_invoice_number ssl_customer_code ssl_salestax ssl_tip_amount ssl_dukpt

The invoice or ticket number.

Recommended for purchasing cards.

The Customer Code or PO Number that appears on the cardholder's credit card billing statement.

Recommended for purchasing cards.

Sales tax amount applied to this transaction in decimal.

Tax exempt transactions can pass 0.00 to properly reflect a tax exempt transaction.

Use only in a Service market segment

Tip or gratuity applied to this transaction in decimal. The gratuity amount is already included in the amount.

Required for debit transactions. This is the value returned by the PIN pad device, which was used to encrypt the cardholder’s Personal Identification Number (PIN) using the Derived Unique Key Per Transaction (DUKPT) method. This value cannot be stored.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_pin_block

Req? Description

C Required for debit transactions. The encrypted PIN block as returned from the PIN pad device. This value cannot be stored. ssl_partial_auth_indicator N The partial indicator flag must be sent to indicate that the application supports partial approval.

Valid values:

 0 – Partial Auth not supported



1 – Partial Auth supported

Response

Output Field Name

ssl_transaction_type ssl_result ssl_result_message ssl_txn_id ssl_txn_time ssl_approval_code ssl_amount ssl_base_amount ssl_tip_amount ssl_card_number ssl_invoice_number

Description

emvswipesale

Outcome of a transaction. A response that contains ssl_result

of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized.

Transaction result message. Example: APPROVAL, PARTIAL

APPROVAL. Refer to the Authorization Response Codes section

for an extensive list of possible returned messages.

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10

AM.

Transaction approval code.

The total transaction authorized or approved amount. Returned based on merchant setup.

Base amount. Transaction amount sent originally on the request.

Returned based on merchant setup. Returned in a Service market segment.

Tip or gratuity amount. Returned based on merchant setup.

Returned in a Service market segment.

Masked card number for this transaction. Only first 2 / last 4 digits will be returned for regular PAN or the last four (4) digits from the actual card number if it is an association token

(Example: ApplePay).

The invoice or ticket number sent originally on the request.

Returned based on merchant setup.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

errorCode errorMessage errorName

Description

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant

configuration in the user interface. Refer to the Error Codes

section for more information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

EMV Swipe Auth Only (emvswipeauthonly)

The emvswipeauthonly transaction is used to obtain real-time Auth Only authorization for a swiped credit for an EMV terminal. This format will cover chip cards in a fall back situation, regular swiped cards as well as any non-supported chip cards. This transaction will guarantee that the funds are available on the card and reduce the cardholder‘s limit to buy for only a predetermined amount of time.

To place the transaction in the open batch, it must be converted to Sale using cccomplete, or reversed using ccdelete to restore the funds back to the card.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_enc_track_data ssl_enc_track_data_format

Req? Description

Y EMV Swipe Auth Only (emvswipeauthonly).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Full encrypted track data required for swiped transactions.

Required only if card is read from a ROAM device. Valid value: ROAM_GENERIC_TDES_EMV

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_ksn ssl_amount ssl_icc_fallback ssl_invoice_number ssl_customer_code ssl_salestax ssl_dukpt ssl_pin_block ssl_partial_auth_indicator

Req? Description

Y Required when sending track data from an encrypting device for payment cards.

(DUKPT) method. It is a 10 byte composite field that is transmitted as 20 alphanumeric character fixed length.

Y Transaction sale amount, number with two decimal places. For example: 1.00.

N Fallback indicator defaulted to N when not sent. Valid values are



Y : chip read was attempted and failed



N: Swipe

The invoice or ticket number.

Recommended for purchasing cards.

The Customer Code or PO Number that appears on the cardholder's credit card billing statement.

Recommended for purchasing cards.

Sales tax amount applied to this transaction in decimal.

Tax exempt transactions can pass 0.00 to properly reflect a tax exempt transaction.

Required for debit transactions. The encrypted PIN block as returned from the PIN pad device. This value cannot be stored.

The partial indicator flag must be sent to indicate that the application supports partial approval.

Valid values:

 0 – Partial Auth not supported



1 – Partial Auth supported

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_transaction_type ssl_result ssl_result_message ssl_txn_id ssl_txn_time ssl_approval_code ssl_amount ssl_card_number ssl_invoice_number errorCode errorMessage errorName

Description

emvswipeauthonly

Outcome of a transaction. A response that contains ssl_result

of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized.

Transaction result message. Example: APPROVAL, PARTIAL

APPROVAL. Refer to the Authorization Response Codes section

for an extensive list of possible returned messages.

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10

AM.

Transaction approval code.

The total transaction authorized or approved amount. This amount will include tip if tip has been provided in the request.

Returned based on merchant setup.

Masked card number for this transaction. Only first 2 / last 4 digits will be returned for regular PAN or the last four (4) digits from the actual card number if it is an association token

(Example: ApplePay).

The invoice or ticket number sent originally on the request.

Returned based on merchant setup.

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant

configuration in the user interface. Refer to the Error Codes

section for more information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Converge Developer Guide: Transaction Format CON-0002-N

EMV Card Update (emvchipupdatetxn)

The emvchipupdatetxn transaction is used to update the system with information from the chip card. The Chip card may update the transaction data after issuer information has been received from the emvchipsale results.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_txn_id ssl_image_type ssl_signature_image ssl_icc_isr ssl_icc_tsi

Req? Description

EMV Chip Update (emvchipupdatetxn)

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Y Converge PIN as configured within Converge, case sensitive.

Unique identifier returned on the original transaction.

Required if signature is requested. Image format.

Possible values, must be capital:

 GIF



TIF

 JPG



PNG

Required if signature is requested. BASE 64 Encoded version of an IMAGE.

Issuer Script Results. This value is used to identify the results of the terminal script processing.

Transaction Status Information

Response

Output Field Name

ssl_transaction_type ssl_result ssl_result_message ssl_txn_id

Description

emvchipupdatetxn

Request result code. A result of 0 indicates the update was successful.

Update result message. A result of SUCCESS indicates the transaction was updated successfully.

Transaction identification number. This is a unique number used to identify the transaction.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

errorCode errorMessage errorName

Description

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant

configuration in the user interface. Refer to the Error Codes

section for more information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

EMV Reversal (emvreverse)

The emvreverse transaction is used to reverse an approved authorization from a chip Sale after a “decline by card” is received from the Chip. The chip card may decline the transaction data even after an issuer approval, in this case a reversal must be sent to restore the funds back to the card.

This action can be performed within 5mn after an emvchipsale.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_txn_id

Req? Description

Y EMV Reversal (emvreverse)

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Unique identifier returned on the original emvchipsale transaction.

Response

Output Field Name

ssl_transaction_type ssl_result ssl_result_message

Description

emvreverse

Request result code. A result of 0 indicates the update was successful.

Reversal result message. A result of SUCCESS indicates the transaction was updated successfully.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_txn_id errorCode errorMessage errorName

Description

Transaction identification number. This is a unique number used to identify the transaction.

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant

configuration in the user interface. Refer to the Error Codes

section for more information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

EMV Key Exchange (emvkeyexchange)

The emvkeyexchange transaction is used to request EMV keys to update the device. This transaction needs to be performed initially to get the EMV keys and when an EMV sale transaction response returns an ssl_update_emv_keys

value of Y. Additionally the POS system must update the device with the EMV keys once obtained from Converge.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin

Req? Description

EMV Key Exchange ( emvkeyexchange

)

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Response

Output Field Name

ssl_transaction_type ssl_result ssl_result_message ssl_emv_key_date

Description

emvkeyexchange

Request result code. A result of 0 indicates the update was successful.

Request result message. A result of SUCCESS indicates the transaction was updated successfully.

Date of Last Host EMV Key Update in MMDDYYYY format.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

emv_key_collection emv_key public_key_index hash_id signature_id public_key public_key_length exponent ssl_txn_id errorCode errorMessage errorName

Description

Parent element of emv_key collection (children)

Parent element of key definition

Identifies the Public key in conjunction with the RID

Identifies the hash algorithm used to produce the hash results in the digital signature scheme

Identifies the digital signature algorithm to be used with the

Public Key

01 = Default (always)

Value of the Public Key

This is one of the elements of the public key used to confirm the size of the public key in the cryptography process.

Value of the exponent part of the Public Key

Transaction identification number. This is a unique number used to identify the transaction.

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant

configuration in the user interface. Refer to the Error Codes

section for more information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

EBT Transactions

EBT transactions require integration to a PIN pad to retrieve the PIN Block and the Key serial number. The PIN pad must be injected with Elavon encryption keys. EBT Transactions may only be performed in a retail, service or face-to-face environments. Mail Order/Telephone Order and e-

Commerce businesses cannot perform EBT transactions. There are two types of EBT transactions:

Food Stamp and Cash Benefits.

Converge Developer Guide: Transaction Format CON-0002-N

Food Stamp Purchase (fspurchase)

The fspurchase is a transaction in which an authorization is obtained on an EBT card. This message is for an EBT Food Stamp Card Purchase transaction, either magnetic stripe read (Track

II) or hand keyed. This transaction reduces the cardholder's limit to buy, and places the transaction into the open batch.

Request

Input Field Name Req? Description

ssl_transaction_type Y

Food Stamp Purchase (fspurchase). ssl_merchant_id Y Converge ID as provided by Elavon. ssl_user_id ssl_pin

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive. ssl_track_data Y ssl_amount ssl_dukpt

The raw track I or II data only as read from the magnetic strip on the card. The track data captured from the swipe device cannot be manipulated and must be passed at the time of the transaction. This includes the beginning and ending sentinels that are included in the track data. Raw track data cannot be stored under any circumstances.

Transaction Amount, must be number with two decimal places.

This is the value returned by the PIN pad device, which was used to encrypt the cardholder’s Personal Identification Number (PIN) using the Derived Unique Key Per Transaction (DUKPT) method.

This value cannot be stored. ssl_key_pointer ssl_pin_block

Triple-DES DUKPT pointer that indicates to Elavon which encryption key was used for EBT transactions. Value must be set to T.

The encrypted PIN Block as returned from the PIN pad device.

This value cannot be stored.

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id ssl_amount ssl_approval_code

Description

Outcome of a transaction. A response that contains ssl_result of 0 represents an Approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized.

Transaction result message. Example: APPROVAL.

Transaction identification number. This is a unique number used to identify the transaction.

Transaction amount. Returned based on merchant setup.

Transaction approval code.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_card_number ssl_email

Description

Masked card number.

Returned based on merchant setup. ssl_exp_date Returned based on merchant setup. ssl_reference_number Transaction reference number. ssl_txn_time errorCode

Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM.

interface. Refer to the Error Codes section for more information.

errorMessage errorName

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user

Error name or reason for the error returned only if an error occurred. Refer

Food Stamp Return (fsreturn)

The fsreturn is used to refund money to the cardholder. A return transaction will increase the cardholder's limit to buy once the batch containing the return has been settled or closed. Use this transaction type to process a food stamp transaction to credit money back onto the EBT card. This transaction can be either magnetic stripe read (Track II) or hand keyed. The Reference Number,

Date and Time of Original Transaction are recommended to be passed.

Request

Input Field Name Req? Description

ssl_transaction_type Y Food Stamp return (fsreturn). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin ssl_track_data ssl_amount

Converge PIN as configured within Converge, case sensitive.

Raw Track I or II data from the magnetic strip on the card. The track data captured from the swipe device cannot be manipulated and must be passed at the time of the transaction.

This includes the beginning and ending sentinels that are included in the track data. Raw track data cannot be stored under any circumstances.

Transaction Amount. Must be number with 2 decimal places.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_dukpt ssl_pin_block ssl_key_pointer ssl_original_date ssl_original_time ssl_reference_number Y

Req? Description

Y Value returned by the PIN pad device, which was used to encrypt the cardholder’s Personal Identification Number (PIN) using the

Derived Unique Key Per Transaction (DUKPT) method. This value cannot be stored.

Y Encrypted PIN Block as returned from the PIN pad device. This value cannot be stored.

Y Triple-DES DUKPT pointer that indicates to Elavon which encryption key was used for US Debit transactions, value must be set to T.

Date of original transaction in MMDDYY format.

Time of original transaction in HHMMSS format.

Transaction reference number is returned in the authorization response message.

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id

Description

Transaction result message. Example: APPROVAL.

Transaction identification number. This is a unique number used to identify the transaction. ssl_txn_time ssl_amount ssl_approval_code ssl_card_number

Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM.

Transaction amount. Returned based on merchant setup.

Transaction approval code.

Masked card number. ssl_email Returned based on merchant setup. ssl_exp_date

Returned based on merchant setup. ssl_reference_number Transaction reference number.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

errorCode errorMessage errorName

Description

Error code returned only if an error occurred, 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. Refer

interface. Refer to the Error Codes

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user

section for more information.

Error name or reason for the error returned only if an error occurred. Refer

Food Stamp Inquiry (fsbainquiry)

This transaction allows the merchant to check the balance of a customer's account and to verify the amount of funds available. A Track II card swipe is required (no manual entry).

Request

Input Field Name Req? Description

ssl_transaction_type

Y Food Stamp Inquiry (fsbainquiry). ssl_merchant_id Y Converge ID as provided by Elavon. ssl_user_id ssl_pin ssl_track_data

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

The raw Track I or II data from the magnetic strip on the card.

The track data captured from the swipe device cannot be manipulated and must be passed at the time of the transaction.

This includes the beginning and ending sentinels that are included in the track data. Raw track data cannot be stored under any circumstances. ssl_dukpt

Y ssl_pin_block ssl_key_pointer

This is the value returned by the PIN Pad device, which was used to encrypt the cardholder’s Personal Identification Number (PIN) using the Derived Unique Key Per Transaction (DUKPT) method.

This value cannot be stored.

The encrypted PIN Block as returned from the PIN pad device.

This value cannot be stored.

Triple-DES DUKPT pointer that indicates to Elavon which encryption key was used for US Debit transactions. Value must be set to T.

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id ssl_txn_time

Description

Transaction result message. Example: APPROVAL.

Transaction identification number. This field is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM. ssl_account_balance ssl_approval_code ssl_card_number ssl_email errorName

Remaining balance on the gift card.

Transaction approval code.

Masked card number.

Returned based on merchant setup. ssl_exp_date Returned based on merchant setup. ssl_reference_number The Transaction Reference Number. errorCode Error code returned only if an error occurred, 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. Refer

interface. Refer to the Error Codes section for more information.

errorMessage Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant configuration in the user

Error name or reason for the error returned only if an error occurred. Refer

Food Stamp Force Purchase (fsforcepurchase)

This is the completion transaction for an EBT Food Stamp Purchase authorization obtained using the phone. This is a hand keyed card only. This transaction requires a 15-digit Voucher Clear

Number from the Merchant’s EBT Food Stamp sales slip and the Voucher Clear Approval Code obtained previously using the phone. The PIN number is not prompted for on the Voucher Clear transactions.

Request

Input Field Name Req? Description

ssl_transaction_type Y Food Stamp Force Purchase (fsforcepurchase). ssl_merchant_id Y Converge ID as provided by Elavon.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_user_id ssl_pin ssl_card_number ssl_exp_date ssl_amount ssl_approval_code ssl_voucher_number

Req? Description

Y Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Required for hand-keyed transactions.

Credit Card Number as it appears on the credit card.

Required for hand-keyed transactions.

Credit Card Expiry Date as it appears on credit card formatted as

MMYY.

Transaction Amount. Must be number with two decimal places.

Voucher Clear Approval Code obtained previously using the phone.

The 15-digit Voucher Clear Number from Merchant’s EBT Food

Stamp sales slip.

Response

Output Field Name

ssl_result ssl_result_message ssl_amount ssl_approval_code ssl_card_number ssl_email ssl_exp_date

Description

Transaction result message. Example: APPROVAL.

Transaction amount. Returned based on merchant setup.

Transaction approval code.

Masked card number.

Returned based on merchant setup.

Returned based on merchant setup. ssl_reference_number The Transaction Reference Number. ssl_txn_id

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

errorCode errorMessage errorName

Description

interface. Refer to the Error Codes section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user

Error name or reason for the error returned only if an error occurred. Refer

Food Stamp Force Return (fsforcereturn)

This message format is used to hand key a Food Stamp Voucher Clear Return transaction. This is the completion transaction for an EBT Food Stamp Refund authorization obtained using the phone. This transaction requires a 15-digit Voucher Clear Number from Merchant’s EBT Food

Stamp sales slip and the Voucher Clear Approval Code obtained previously using the phone. The

PIN number is not prompted for on the Voucher Clear transactions.

Request

Input Field Name Req? Description

ssl_transaction_type

Y Food Stamp Force Return (fsforcereturn). ssl_merchant_id Y Converge ID as provided by Elavon. ssl_user_id ssl_pin

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive. ssl_card_number Y ssl_exp_date ssl_amount ssl_approval_code

Required for hand-keyed transactions.

Credit Card Number as it appears on the credit card.

Required for hand-keyed transactions.

Credit Card Expiry Date as it appears on credit card formatted as

MMYY.

Transaction amount. Must be number with two decimal places. ssl_voucher_number Y

The voucher clear approval code obtained previously using the phone.

The 15-digit voucher clear number from the Merchant’s EBT

Food Stamp sales slip.

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_result ssl_result_message ssl_amount ssl_approval_code ssl_card_number

Description

Transaction result message. Example: APPROVAL.

Transaction amount. Returned based on merchant setup.

Transaction approval code.

Masked card number. ssl_email ssl_exp_date ssl_reference_number The Transaction Reference Number. ssl_txn_id ssl_txn_time

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM. ssl_voucher_number

Returned based on merchant setup.

Returned based on merchant setup. errorCode errorMessage errorName

The voucher clear number.

interface. Refer to the Error Codes section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user

Error name or reason for the error returned only if an error occurred. Refer

Cash Benefit Purchase (cbpurchase)

All EBT purchases that are not food stamp related should be processed as Cash EBT purchases.

Cash EBT transactions are very similar to debit transactions because customers can receive cash back from these transactions. This message format is for the EBT Cash Benefit Purchase transaction for either a magnetic stripe read (Track II) or hand keyed card.

Note: You must pass one of the following fields: ssl_track_data or ssl_card_number.

Converge Developer Guide: Transaction Format CON-0002-N

Request

Input Field Name Req? Description

ssl_transaction_type Y Cash Benefit Purchase (cbpurchase). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin ssl_track_data

Y ssl_card_number ssl_exp_date ssl_amount

Converge PIN as configured within Converge, case sensitive.

Required for swiped or contactless (MSD) transactions.

The raw track I and/or II data from the magnetic strip on the card. The track data captured from the swipe device cannot be manipulated and must be passed at the time of the transaction.

Required for hand-keyed transactions.

Credit Card Number as it appears on the credit card.

Required for hand-keyed transactions.

Credit Card Expiry Date as it appears on credit card formatted as

MMYY.

Transaction total Amount including surcharge or cash back. Must be a number with two decimal places. ssl_cashback_amount ssl_dukpt ssl_key_pointer ssl_pin_block

Cash back. The amount of cash back that the customer will receive. Must be a number with two decimal places, if sent.

Value returned by the PIN pad device, which was used to encrypt the cardholder’s Personal Identification Number (PIN) using the

Derived Unique Key Per Transaction (DUKPT) method. This value cannot be stored.

Triple-DES DUKPT pointer that indicates to Elavon which encryption key was used for EBT transactions. Value must be set to T.

Encrypted PIN Block as returned from the PIN pad device. This value cannot be stored.

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_result ssl_result_message ssl_amount ssl_approval_code ssl_base_amount ssl_card_number ssl_cashback_amount

Description

Transaction result message. Example: APPROVAL.

Transaction amount. Returned based on merchant setup.

Transaction approval code.

Base amount, the amount sent originally on the request.

Masked card number.

Cash back. The amount of cash back that the customer will receive passed from the original request. ssl_email Returned based on merchant setup. ssl_reference_number Transaction reference number. ssl_surcharge_amount Surcharge amount as configured by merchant. ssl_txn_id ssl_txn_time

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM. errorCode errorMessage errorName

interface. Refer to the Error Codes section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user

Error name or reason for the error returned only if an error occurred. Refer

Cash Benefit Inquiry (cbbainquiry)

This transaction allows a merchant inquiry into the current available balance in specified EBT accounts. A Track II card swipe is required (no manual entry).

Request

Input Field Name Req? Description

ssl_transaction_type Y

Cash Benefit Inquiry (cbbainquiry). ssl_merchant_id

Y Converge ID as provided by Elavon.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_user_id ssl_pin ssl_track_data ssl_dukpt ssl_key_pointer ssl_pin_block

Req? Description

Y Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Required for swiped or contactless (MSD) transactions.

The raw track I and/or II data from the magnetic strip on the card. The track data captured from the swipe device cannot be manipulated and must be passed at the time of the transaction.

This includes the beginning and ending sentinels that are included in the track data. Raw track data cannot be stored under any circumstance. Expiration date is included with a track data.

First and last name of the Cardholder is also included with the

Track I data.

Value returned by the PIN pad device, which was used to encrypt the cardholder’s Personal Identification Number (PIN) using the

Derived Unique Key Per Transaction (DUKPT) method. This value cannot be stored.

Triple-DES DUKPT pointer that indicates to Elavon which encryption key was used for EBT transactions. Value must be set to T.

Encrypted PIN Block as returned from the PIN pad device. This value cannot be stored.

Response

Output Field Name

ssl_result ssl_result_message

Description

Transaction result message. Example: APPROVAL. ssl_txn_id ssl_txn_time

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM. ssl_account_balance ssl_approval_code

Remaining balance on the gift card.

Transaction approval code. ssl_card_number Masked card number. ssl_email

Returned based on merchant setup. ssl_reference_number Transaction reference number.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

errorCode errorMessage errorName

Description

interface. Refer to the Error Codes section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user

Error name or reason for the error returned only if an error occurred. Refer

(MagneSafe encryption). Refer to the Encryption section for more information.

Gift Card Transactions

This message format is for either a whole track, track 1 or track 2 magnetic stripe read or hand keyed gift card transactions (EGC) available for all supported market segments.

Notes:

You must pass one of the following fields:

 Track data in the ssl_track_data for swiped or contactless (MSD) transactions.



The encrypted track data for swiped or contactless (MSD) transactions:



Track 1 data in the ssl_encrypted_track1_data field and/or track 2 data in the ssl_encrypted_track2_data

field, extracted from the Magtek readers

 Entire track data in the ssl_enc_track_data field captured from the Ingenico

device (3DES DUKPT encryption). Refer to the Encryption section for more

information.



The card number in the ssl_card_number for hand-keyed transactions.



The token in the ssl_token from a previously tokenized card number.

Converge Developer Guide: Transaction Format CON-0002-N

Gift Card Activation (egcactivation)

Gift cards must be activated prior to use.

Request

Input Field Name Req? Description

ssl_transaction_type Y Gift Card Activation (egcactivation). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin ssl_show_form ssl_track_data ssl_ksn

Converge PIN as configured within Converge, case sensitive.

Set value to true to show the Converge Payment Form (Available only for process.do), set to false otherwise.

Required for swiped transactions.

The raw track I and/or II data from the magnetic strip on the card. The track data captured from the swipe device cannot be manipulated and must be passed at the time of the transaction.

This includes the beginning and ending sentinels that are included in the track data. Raw track data cannot be stored under any circumstance. Expiration date is included with a track data.

First and last name of the Cardholder is also included with the

Track I data.

Notes:

 If using a Magtek encrypting device, pass the encrypted track data in the ssl_encrypted_track1_data and/or ssl_encrypted_track2_data.



If using an Ingenico encrypting device, pass the encrypted track data in the ssl_enc_track_data.



Refer to the Encryption section for more information.

Required when sending track data from an encrypting device for payment cards.

The Key Serial Number generated from the swiped payment card, this is the value returned by the encrypting device. This value is used to encrypt the PAN data, using the Derived Unique Key Per

Transaction (DUKPT) method. It is a 10 byte composite field that is transmitted as 20 alphanumeric character fixed length.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_card_number ssl_token ssl_exp_date ssl_amount ssl_egc_tender_type ssl_get_token

Req? Description

Y Required for hand-keyed transactions.

Gift card number as it appears on the gift card.

C Required for hand-keyed transaction if gift card number is not sent.

Use only with a terminal that is setup with Tokenization.

Gift Card Token, previously generated from a gift card number. A token can be stored and used as a substitute for a card number.

Required for hand-keyed transactions.

Gift card expiry date as it appears on gift card.

Transaction sale amount, number with two decimal places. For example: 1.00.

This field is used to pass the tender type used to pay for the gift card.

Valid Values are as follows:



0 = cash

 1 = credit



2 = debit

 3 = check

Use only with a terminal that is setup with Tokenization.

Generate Token indicator, used to indicate if you wish to generate a token after processing the installment. Valid value: Y

(generate a token), N (do not generate token). Defaulted to N.

Once generated, the token number can be stored and used as a substitute for a card number at later time.

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id ssl_txn_time

Description

Transaction result message. Example: APPROVAL.

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM. ssl_account_balance Remaining balance on the gift card. ssl_amount Transaction amount. Returned based on merchant setup.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_approval_code ssl_card_number ssl_egc_tender_type This field is used to pass the tender type used to pay for the gift card. ssl_email

Valid Values are as follows:



Cash

 Credit



Debit

 Check

Returned based on merchant setup. ssl_exp_date Returned based on merchant setup. ssl_token

Description

Transaction approval code.

Masked card number. ssl_token_response errorCode errorMessage

Gift Card Token generated from the card number. A token can be stored and used as a substitute for a card number.

Returned only if generating a token is requested in a terminal that setup for

Tokenization.

Outcome of the token generation. This value will be SUCCESS if a token has been generated. Other possible returned values are FAILURE, Action Not

Permitted, Invalid Token, Not Permitted, Acct Verification Failed.

Returned only if generating a token is requested in a terminal that setup for

Tokenization.

Error code returned only if an error occurred, 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. Refer to the Error Codes

section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on Merchant configuration in the user

interface. Refer to the Error Codes section for more information.

errorName Error name or reason for the error returned only if an error occurred. Refer

Refer to the Encryption section for more information.

Converge Developer Guide: Transaction Format CON-0002-N

Gift Card Sale/Redemption (egcsale)

The gift card Redemption transaction is used to make a purchase using the balance on the gift card account.

Request

Input Field Name Req? Description

ssl_transaction_type Y Gift Card Sale/Redemption (egcsale). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin ssl_show_form ssl_track_data ssl_ksn ssl_card_number

Converge PIN as configured within Converge, case sensitive.

Set value to true to show the Converge payment form (available only for process.do), set to false otherwise.

Required for swiped transactions.

The raw track I and/or II data from the magnetic strip on the card. The track data captured from the swipe device cannot be manipulated and must be passed at the time of the transaction.

This includes the beginning and ending sentinels that are included in the track data. Raw track data cannot be stored under any circumstance. Expiration date is included with a track data.

First and last name of the Cardholder is also included with the

Track I data.

Notes:

 If using a Magtek encrypting device, pass the encrypted track data in the ssl_encrypted_track1_data and/or ssl_encrypted_track2_data.



If using an Ingenico encrypting device, pass the encrypted track data in the ssl_enc_track_data.



Required when sending track data from an encrypting device for payment cards.

The Key Serial Number generated from the swiped payment card, this is the value returned by the encrypting device. This value is used to encrypt the PAN data, using the Derived Unique Key Per

Transaction (DUKPT) method. It is a 10 byte composite field that is transmitted as 20 alphanumeric character fixed length.

Required for hand-keyed transactions.

Gift card number as it appears on the gift card.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_token ssl_exp_date ssl_amount ssl_tip_amount ssl_server ssl_shift ssl_get_token

Req? Description

C Required for hand-keyed transaction if gift card number is not sent.

Use only with a terminal that is setup with Tokenization.

Gift Card Token, previously generated from a gift card number. A token can be stored and used as a substitute for a card number.

Required for hand-keyed transactions.

Gift card expiry date as it appears on gift card.

Transaction sale amount, number with 2 decimal places. This amount does not include the tip amount which must be sent separately if needed. For example: 1.00.

Tip or gratuity amount to be added to the transaction sale amount. Number with 2 decimal places, can be 0.00 to indicate no tip was provided. Only used in a Service market segment.

Server ID, this is the clerk, cashier, and waiter or waitress identification number. Only used in a Service market segment.

Alphanumeric, Example: Jack.

Shift, can refer to or be used to identify time period, course or type of service, Only used in a Service market segment.

Alphanumeric, Example: Lunch.

Use only with a terminal that is setup with Tokenization.

Generate Token indicator, used to indicate if you wish to generate a token after processing the installment. Valid value: Y

(generate a token), N (do not generate token). Defaulted to N.

Once generated, the token number can be stored and used as a substitute for a card number at later time.

Response

Output Field Name

ssl_result ssl_result_message

Description

Transaction result message. Example: APPROVAL. ssl_txn_id ssl_txn_time

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM. ssl_account_balance Remaining balance on the gift card. ssl_amount The total transaction amount. Returned based on merchant setup.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_base_amount ssl_tip_amount ssl_approval_code ssl_card_number ssl_exp_date ssl_email ssl_server ssl_shift ssl_token ssl_token_response errorCode errorMessage errorName

Description

Base amount. Transaction amount sent originally on the request. Returned based on merchant setup. Only used in a Service market segment.

Tip or gratuity amount that was added or updated. Returned based on merchant setup. Only used in a Service market segment.

Transaction approval code.

Masked card number.

Returned based on merchant setup.

Server Id submitted with the request. Only returned on Service market segment based on the merchant setup.

Shift information submitted with the request. Only returned on Service market segment based on the merchant setup.

Gift Card Token generated from the card number. A token can be stored and used as a substitute for a card number.

Returned only if generating a token is requested in a terminal that setup for

Tokenization.

Outcome of the token generation. This value will be SUCCESS if a token has been generated. Other possible returned values are FAILURE, Action Not

Permitted, Invalid Token, Not Permitted, Acct Verification Failed.

Returned only if generating a token is requested in a terminal that setup for

Tokenization.

Error code returned only if an error occurred, 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. Refer to the Error Codes

section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on Merchant configuration in the user

interface. Refer to the Error Codes section for more information.

Error name or reason for the error returned only if an error occurred. Refer

Refer to the Encryption section for more information.

Converge Developer Guide: Transaction Format CON-0002-N

Gift Card Refund (egccardrefund)

This transaction is used to reset the balance of a gift card account to zero, and the card is no longer usable.

Request

Input Field Name Req? Description

ssl_transaction_type Y Gift Card Refund (egccardrefund). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin ssl_show_form ssl_track_data ssl_ksn ssl_card_number

Converge PIN as configured within Converge, case sensitive.

Set value to true to show the Converge payment form (available only for process.do). Set to false otherwise.

Required for swiped transactions.

The raw track I and/or II data from the magnetic strip on the card. The track data captured from the swipe device cannot be manipulated and must be passed at the time of the transaction.

This includes the beginning and ending sentinels that are included in the track data. Raw track data cannot be stored under any circumstance. Expiration date is included with a track data.

First and last name of the Cardholder is also included with the

Track I data.

Notes:

 If using a Magtek encrypting device, pass the encrypted track data in the ssl_encrypted_track1_data and/or ssl_encrypted_track2_data.



If using an Ingenico encrypting device, pass the encrypted track data in the ssl_enc_track_data.



Required when sending track data from an encrypting device for payment cards.

The Key Serial Number generated from the swiped payment card, this is the value returned by the encrypting device. This value is used to encrypt the PAN data, using the Derived Unique Key Per

Transaction (DUKPT) method. It is a 10 byte composite field that is transmitted as 20 alphanumeric character fixed length.

Required for hand-keyed transactions.

Gift Card Number as it appears on the gift card.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_token ssl_exp_date ssl_get_token

Req? Description

C Required for hand-keyed transaction if gift card number is not sent.

Use only with a terminal that is setup with Tokenization.

Gift Card Token, previously generated from a gift card number. A token can be stored and used as a substitute for a card number.

Required for hand-keyed transactions.

Gift Card Expiry date as it appears on gift card.

Use only with a terminal that is setup with Tokenization.

Generate Token indicator, used to indicate if you wish to generate a token after processing the installment. Valid value: Y

(generate a token), N (do not generate token). Defaulted to N.

Once generated, the token number can be stored and used as a substitute for a card number at later time.

Response

Output Field Name

ssl_result

Description

Outcome of a transaction. A response that contains ssl_result of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized. ssl_result_message ssl_txn_id ssl_txn_time Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM. ssl_account_balance

Remaining balance on the gift card. ssl_approval_code Transaction approval code. ssl_card_number

Transaction result message. Example: APPROVAL.

Transaction identification number. This is a unique number used to identify the transaction. ssl_email ssl_exp_date

Masked card number.

Returned based on merchant setup.

Returned based on merchant setup. ssl_token Gift Card Token generated from the card number. A token can be stored and used as a substitute for a card number.

Returned only if generating a token is requested in a terminal that setup for

Tokenization.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_token_response errorCode errorMessage errorName

Description

Outcome of the token generation. This value will be SUCCESS if a token has been generated. Other possible returned values are FAILURE, Action Not

Permitted, Invalid Token, Not Permitted, Acct Verification Failed.

Returned only if generating a token is requested in a terminal that setup for

Tokenization.

Error code returned only if an error occurred, 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. Refer to the Error Codes

section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user

interface. Refer to the Error Codes section for more information.

Error name or reason for the error returned only if an error occurred. Refer

from going to authorization. This is a numeric field. Refer to the Error Codes

Gift Card Replenishment/Reload (egcreload)

This transaction is used to increase the current balance of the gift card account.

Request

Input Field Name Req? Description

ssl_transaction_type Y

Gift Card Replenishment/Reload (egcreload). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin ssl_show_form

Converge PIN as configured within Converge, case sensitive.

Set value to true to show the Converge payment form (Available only for process.do), set to false otherwise. ssl_track_data ssl_card_number

Required for swiped transactions.

The raw track I and/or II data from the magnetic strip on the card. The track data captured from the swipe device cannot be manipulated and must be passed at the time of the transaction.

This includes the beginning and ending sentinels that are included in the track data. Raw track data cannot be stored under any circumstance. Expiration date is included with a track data.

First and last name of the Cardholder is also included with the

Track I data.

Required for hand-keyed transactions.

Gift card number as it appears on the gift card.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_token ssl_exp_date ssl_amount ssl_egc_tender_type ssl_get_token

Req? Description

C Required for hand-keyed transaction if gift card number is not sent.

Use only with a terminal that is setup with Tokenization.

Gift Card Token, previously generated from a gift card number. A token can be stored and used as a substitute for a card number.

Y Required for hand-keyed transactions.

Gift card expiry date as it appears on gift card.

Transaction sale amount, number with two decimal places. For example: 1.00.

This field is used to pass the tender type used to pay for the gift card.

Valid Values are as follows:

 0 = Cash



1 = Credit

 2 = Debit



3 = Check

Use only with a terminal that is setup with Tokenization.

Generate Token indicator, used to indicate if you wish to generate a token after processing the installment. Valid value: Y

(generate a token), N (do not generate token). Defaulted to N.

Once generated, the token number can be stored and used as a substitute for a card number at later time.

Response

Output Field Name

ssl_result ssl_result_message

Description

Transaction result message. Example: APPROVAL. ssl_txn_id ssl_txn_time ssl_card_number

Transaction identification number. This is a unique number used to identify the transaction.

Masked card number.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name Description

ssl_egc_tender_type This field is used to pass the tender type used to pay for the gift card.

Valid values are as follows:

 Cash



Credit

 Debit



Check ssl_email Returned based on merchant setup. ssl_exp_date ssl_token

Returned based on merchant setup.

Gift Card Token generated from the card number. A token can be stored and used as a substitute for a card number.

Returned only if generating a token is requested in a terminal that setup for

Tokenization. ssl_token_response errorCode errorMessage errorName

Outcome of the token generation. This value will be SUCCESS if a token has been generated. Other possible returned values are FAILURE, Action Not

Permitted, Invalid Token, Not Permitted, Acct Verification Failed.

Returned only if generating a token is requested in a terminal that setup for

Tokenization.

Error code returned only if an error occurred, typically when the transaction failed validation or the request is incorrect. This will prevent the transaction

section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user

interface. Refer to the Error Codes section for more information.

Error name or reason for the error returned only if an error occurred. Refer

Refer to the Encryption section for more information.

Gift Card Balance Inquiry (egcbalinquiry)

This option is used to check the current balance of a gift card account.

Request

Input Field Name Req? Description

ssl_transaction_type Y Gift Card Balance Inquiry (egcbalinquiry). ssl_merchant_id ssl_user_id ssl_pin

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_show_form ssl_track_data ssl_ksn ssl_card_number ssl_token ssl_exp_date ssl_get_token

Req? Description

N Set value to true to show the Converge Payment Form (Available only for process.do), set to false otherwise.

Required for swiped transactions.

The raw track I and/or II data from the magnetic strip on the card. The track data captured from the swipe device cannot be manipulated and must be passed at the time of the transaction.

This includes the beginning and ending sentinels that are included in the track data. Raw track data cannot be stored under any circumstance. Expiration date is included with a track data.

First and last name of the Cardholder is also included with the

Track I data.

Notes:

 If using a Magtek encrypting device, pass the encrypted track data in the ssl_encrypted_track1_data and/or ssl_encrypted_track2_data.

 If using an Ingenico encrypting device, pass the encrypted track data in the ssl_enc_track_data.



Required when sending track data from an encrypting device for payment cards.

The Key Serial Number generated from the swiped payment card, this is the value returned by the encrypting device. This value is used to encrypt the PAN data, using the Derived Unique Key Per

Transaction (DUKPT) method. It is a 10 byte composite field that is transmitted as 20 alphanumeric character fixed length.

Required for hand-keyed transactions.

Gift card number as it appears on the gift card.

Required for hand-keyed transaction if gift card number is not sent.

Use only with a terminal that is setup with Tokenization.

Gift Card Token, previously generated from a gift card number. A token can be stored and used as a substitute for a card number.

Required for hand-keyed transactions.

Gift card expiry date as it appears on gift card.

Use only with a terminal that is setup with Tokenization.

Generate Token indicator, used to indicate if you wish to generate a token after processing the installment. Valid value: Y

(generate a token), N (do not generate token). Defaulted to N.

Once generated, the token number can be stored and used as a substitute for a card number at later time.

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_result ssl_result_message

Description

Transaction result message. Example: APPROVAL. ssl_txn_id ssl_txn_time

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM. ssl_account_balance Remaining balance on the gift card. ssl_approval_code

Transaction approval code. ssl_card_number Masked card number. ssl_email Returned based on merchant setup. ssl_exp_date ssl_token ssl_token_response errorCode errorMessage

Returned based on merchant setup.

Gift Card Token generated from the card number. A token can be stored and used as a substitute for a card number.

Returned only if generating a token is requested in a terminal that setup for

Tokenization.

Outcome of the token generation. This value will be SUCCESS if a token has been generated. Other possible returned values are FAILURE, Action Not

Permitted, Invalid Token, Not Permitted, Acct Verification Failed.

Returned only if generating a token is requested in a terminal that setup for

Tokenization.

Error Codes section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user

interface. Refer to the Error Codes section for more information.

errorName Error name or reason for the error returned only if an error occurred. Refer

Refer to the Encryption section for more information.

Converge Developer Guide: Transaction Format CON-0002-N

Gift Card Credit (egccredit)

This transaction is used to refund money back to a gift card account.

Request

Input Field Name Req? Description

ssl_transaction_type Y Gift Card Credit (egccredit). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin ssl_show_form ssl_track_data ssl_card_number

Converge PIN as configured within Converge, case sensitive.

Set value to true to show the Converge Payment Form (Available only for process.do), set to false otherwise.

Required for swiped transactions.

The raw track I and/or II data from the magnetic strip on the card. The track data captured from the swipe device cannot be manipulated and must be passed at the time of the transaction.

Notes:

 If using a Magtek encrypting device, pass the encrypted track data in the ssl_encrypted_track1_data and/or ssl_encrypted_track2_data.



If using an Ingenico encrypting device, pass the encrypted track data in the ssl_enc_track_data.



Required for hand-keyed transactions.

Gift Card Number as it appears on the gift card. ssl_ksn ssl_token

Required when sending track data from an encrypting device for payment cards.

The Key Serial Number generated from the swiped payment card, this is the value returned by the encrypting device. This value is used to encrypt the PAN data, using the Derived Unique Key Per

Transaction (DUKPT) method. It is a 10 byte composite field that is transmitted as 20 alphanumeric character fixed length.

Required for hand-keyed transaction if gift card number is not sent.

Use only with a terminal that is setup with Tokenization.

Gift Card Token, previously generated from a gift card number. A token can be stored and used as a substitute for a card number.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_exp_date ssl_amount ssl_get_token

Req? Description

C Required for hand-keyed transactions.

Gift Card Expiry date as it appears on gift card.

Transaction Sale Amount, number with 2 decimal places. For example: 1.00.

Use only with a terminal that is setup with Tokenization.

Generate Token indicator, used to indicate if you wish to generate a token after processing the installment. Valid value: Y

(generate a token), N (do not generate token). Defaulted to N.

Once generated, the token number can be stored and used as a substitute for a card number at later time.

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id Transaction identification number. This is a unique number used to identify the transaction. ssl_txn_time

Transaction amount. Returned based on merchant setup.

Transaction approval code.

Masked card number.

Returned based on merchant setup. ssl_exp_date

Description

Transaction result message. Example: APPROVAL. ssl_token ssl_token_response

Returned based on merchant setup.

Gift Card Token generated from the card number. A token can be stored and used as a substitute for a card number.

Returned only if generating a token is requested in a terminal that setup for

Tokenization.

Outcome of the token generation. This value will be SUCCESS if a token has been generated. Other possible returned values are FAILURE, Action Not

Permitted, Invalid Token, Not Permitted, Acct Verification Failed.

Returned only if generating a token is requested in a terminal that setup for

Tokenization.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

errorCode errorMessage errorName

Description

Error code returned only if an error occurred, 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. Refer to the Error Codes

section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user

interface. Refer to the Error Codes section for more information.

Error name or reason for the error returned only if an error occurred. Refer

Tokenization section for more information.

Gift Card Generate Token (egcgettoken)

The egcgettoken is a transaction that generates a token from a gift card number. The token generated can be used in place of a gift card number in any subsequent transactions. This transaction type is supported only when a terminal is setup for tokenization; refer to the

To perform an egcgettoken, you must pass one of the following fields:



Card number and expiration date for hand keyed transaction



The encrypted track data for swiped or contactless (MSD) transactions:



Track 1 data in the ssl_encrypted_track1_data field and/or track 2 data in the ssl_encrypted_track2_data

field, extracted from the Magtek readers (MagneSafe

encryption). Refer to the Encryption section for more information.

 Entire track data in the ssl_enc_track_data field captured from the Ingenico device

(3DES DUKPT encryption). Refer to the Encryption section for more information.

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_show_form

Req? Description

Y Gift Card Generate Token (egcgettoken).

Converge ID as provided by Elavon.

Converge User ID as configured within Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Set value to true to show the Converge Payment Form

(available only for process.do), set to false otherwise.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_card_number ssl_exp_date

Req? Description

C Required when generating token from hand keyed card.

Gift Card Number as it appears on the gift card.

C Required when generating token from hand keyed card.

Gift Card Expiry Date as it appears on gift card formatted as

MMYY. ssl_encrypted_track1_data C

Required for generating token using swiped or contactless

(MSD) gift cards from a Magtek encrypting reader.

This is the encrypted Track 1 data only of the gift card extracted from the encrypting device. ssl_encrypted_track2_data C ssl_enc_track_data ssl_ksn

Required for generating token using swiped or contactless

(MSD) gift cards from a Magtek encrypting reader.

This is the encrypted Track 2 data only of the gift card extracted from the encrypting device.

Required for generating token using swiped or contactless

(MSD) gift card from an Ingenico encrypting device.

This is the entire encrypted Track data combined into a single cipher text that was extracted from the Ingenico encrypting device.

Required for all encrypting devices for payment cards when swipe data is sent.

The Key Serial Number generated from the swiped payment card, this is the value returned by the encrypting device.

This value is used to encrypt the PAN data, using the

Derived Unique Key Per Transaction (DUKPT) method. It is a

10 byte composite field that is transmitted as 20 alphanumeric character fixed length.

Converge Developer Guide: Transaction Format CON-0002-N

Loyalty Card Transactions

This message format is for either a whole track, track 1 or track 2 magnetic stripe read or hand keyed loyalty card transactions (LT) available for all supported market segments.

Note:

You must pass one of the following fields:



Track data in the ssl_loyalty_track_data field for swiped or contactless (MSD) transactions



The encrypted track data for swiped or contactless (MSD) loyalty transactions:

 Track 1 data in the ssl_encrypted_loyalty_track1_data field and/or track 2 data in the ssl_encrypted_loyalty_track2_data field, extracted from the

Magtek readers (MagneSafe encryption). Refer to the Encryption section for more

information.

 Entire track data in the ssl_enc_loyalty_track_data field captured from the

Ingenico device (3DES DUKPT encryption). Refer to the Encryption section for more

information.



The card number in the ssl_loyalty_card_number field for hand keyed transactions



The phone number in the ssl_phone field (phone numbers are required for enrollment)

Loyalty Card Enrollment (ltenrollment)

Loyalty cards must be activated prior to use, a phone number must be obtained. Cardholder has the option to be enrolled using a phone number only or enrolled using a loyalty card number and have the phone number linked to it.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_show_form

Req? Description

Loyalty Card Enrollment (ltenrollment).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Set value to true to show the Converge Payment Form

(Available only for process.do), set to false otherwise.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_phone ssl_enrollment ssl_loyalty_track_data ssl_ksn

Req? Description

Y Required for all enrollments, when enrolling a loyalty card the phone number must be passed. This will allow accessing the loyalty information based on phone number for future transactions when a loyalty card is not available. Max 10 digits, no spaces or dashes.

Y Required to indicate enrollment action. The possible values listed as follows:



02 – Enroll and link loyalty card and phone number

 03 – Enroll and link only phone number

Required with linking loyalty card enrollment option for hand keyed loyalty card.

The raw track I and/or II data as read from the magnetic strip on the loyalty card, including the beginning and ending sentinels. The expiration date, first and last names of the cardholder are included with the Track I data.

Notes:

 If using a MagTek encrypting device (MagneSafe), pass the encrypted loyalty track1 data in the ssl_encrypted_loyalty_track1_data

and/or the encrypted loyalty track 2 data in the ssl_encrypted_loyalty_track2_data



If using an Ingenico encrypting device (Generic

TDES DUKPT), pass the entire encrypted track data of the loyalty card combined into a single cipher text in the ssl_enc_loyalty_track_data.



APPROVAL. Refer to the Authorization Response Codes section

information.

Required when sending track data from an encrypting device for payment cards.

The Key Serial Number generated from the swiped payment card, this is the value returned by the encrypting device. This value is used to encrypt the PAN data, using the Derived

Unique Key Per Transaction (DUKPT) method. It is a 10 byte composite field that is transmitted as 20 alphanumeric character fixed length.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name Req? Description

ssl_loyalty_card_number C Required with linking loyalty card enrollment option for hand keyed loyalty card.

If loyalty card is available, hand keyed data can be passed.

Loyalty card number as it appears on the loyalty card. ssl_loyalty_exp_date N ssl_amount

Optional when a loyalty card is available for hand-keyed transactions. If not sent it is defaulted to 1249.

Loyalty card expiry date as it appears on loyalty card.

Format: MMYY.

Optional, if not sent it is defaulted to 0.00.

Transaction amount, number with two decimal places.

Purchase is not necessary for enrollment. For example: 1.00.

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id ssl_txn_time

Description

Outcome of a transaction. A response that contains ssl_result

of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized.

Transaction result message. Example: APPROVAL, PARTIAL

for an extensive list of possible returned messages.

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10

AM. ssl_loyalty_account_balance Remaining balance on the loyalty card. ssl_amount

Transaction amount. Returned based on the merchant setup. ssl_approval_code Transaction approval code. ssl_loyalty_card_number ssl_loyalty_exp_date

Masked card number.

Returned based on merchant setup. ssl_phone ssl_loyalty_program ssl_access_code

The phone number.

This value is used to return the merchant’s loyalty program description to be printed on the consumer’s receipt.

This value is used to identify the randomly generated access code that is tied to the primary customer for the account created as part of the loyalty program.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_promo_list errorCode errorMessage errorName

Description

The promo list will contain 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

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant

configuration in the user interface. Refer to the Error Codes

section for more information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Loyalty Card Redemption (ltredeem)

Loyalty card redemption transaction is used to redeem points; either a phone number or a loyalty card data can be used.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_show_form ssl_phone

Req? Description

Loyalty Card Redemption (ltredeem).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Set value to true to show the Converge Payment Form

(available only for process.do), set to false otherwise.

Required when a loyalty card is not available, this will allow accessing the loyalty information based on phone number.

Max 10 digits, no spaces or dashes.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_loyalty_track_data ssl_ksn ssl_loyalty_card_number ssl_loyalty_exp_date

Req? Description

C Required when a loyalty card is available for swiped transactions.

Notes:

 If using a MagTek encrypting device (MagneSafe), pass the encrypted loyalty track1 data in the ssl_encrypted_loyalty_track1_data

and/or the encrypted loyalty track 2 data in the ssl_encrypted_loyalty_track2_data



If using an Ingenico encrypting device (Generic

TDES DUKPT), pass the entire encrypted track data of the loyalty card combined into a single cipher text in the ssl_enc_loyalty_track_data.



Authorization Response Codes section for an extensive list of

information.

Required when sending track data from an encrypting device for payment cards.

The Key Serial Number generated from the swiped payment card, this is the value returned by the encrypting device. This value is used to encrypt the PAN data, using the Derived

Unique Key Per Transaction (DUKPT) method. It is a 10 byte composite field that is transmitted as 20 alphanumeric character fixed length.

Required when a loyalty card is available for hand-keyed transactions.

Loyalty card number as it appears on the loyalty card.

Optional when a loyalty card is available for hand-keyed transactions. If not sent it is defaulted to 1249.

Loyalty card expiry date as it appears on loyalty card.

Format: MMYY. ssl_amount ssl_promo_code

Transaction sale amount, number with two decimal places.

For example: 1.00.

Promo code to use. Once used it cannot be used again.

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id

Description

Outcome of a transaction. A response that contains ssl_result

of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized.

Transaction result message. Example: APPROVAL. Refer to the

possible returned messages.

Transaction identification number. This is a unique number used to identify the transaction. ssl_txn_time ssl_loyalty_card_number

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10

AM. ssl_loyalty_account_balance Remaining balance on the loyalty card. ssl_amount Transaction amount. Returned based on the merchant setup. ssl_approval_code Transaction approval code.

Masked card number. ssl_loyalty_exp_date ssl_phone

Returned based on merchant setup.

The phone number. ssl_promo_code ssl_loyalty_program ssl_access_code ssl_promo_list

Promo code used in this transaction.

This value is used to return the merchant’s loyalty program description to be printed on the consumer’s receipt.

This value is used to identify the randomly generated access code that is tied to the primary customer for the account created as part of the loyalty program.

The promo list will contain 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

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

errorCode errorMessage errorName

Description

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant

configuration in the user interface. Refer to the Error Codes

section for more information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Loyalty Card Return (ltreturn)

Loyalty card return transaction is used to return points to the loyalty card, either a phone number or a loyalty card data can be used. Promo code can only be consumed once and cannot be returned.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_show_form ssl_phone

Req? Description

Loyalty Card Return (ltreturn).

Y Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Set value to true to show the Converge Payment Form

(Available only for process.do), set to false otherwise.

Required when a loyalty card is not available, this will allow accessing the loyalty information based on phone number.

Max 10 digits, no spaces or dashes.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_loyalty_track_data ssl_ksn ssl_loyalty_card_number ssl_loyalty_exp_date ssl_amount

Req? Description

C Required when a loyalty card is available for swiped transactions.

Notes:

 If using a MagTek encrypting device (MagneSafe), pass the encrypted loyalty track1 data in the ssl_encrypted_loyalty_track1_data

and/or the encrypted loyalty track 2 data in the ssl_encrypted_loyalty_track2_data



If using an Ingenico encrypting device (Generic

TDES DUKPT), pass the entire encrypted track data of the loyalty card combined into a single cipher text in the ssl_enc_loyalty_track_data.



Authorization Response Codes section for an extensive list of

information.

Required when sending track data from an encrypting device for payment cards.

The Key Serial Number generated from the swiped payment card, this is the value returned by the encrypting device. This value is used to encrypt the PAN data, using the Derived

Unique Key Per Transaction (DUKPT) method. It is a 10 byte composite field that is transmitted as 20 alphanumeric character fixed length.

Required when a loyalty card is available for hand-keyed transactions.

Loyalty card number as it appears on the loyalty card.

Optional when a loyalty card is available for hand-keyed transactions. If not sent it is defaulted to 1249.

Loyalty card expiry date as it appears on loyalty card.

Format: MMYY.

Transaction amount, number with two decimal places. For example: 1.00.

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id

Description

Outcome of a transaction. A response that contains ssl_result

of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized.

Transaction result message. Example: APPROVAL. Refer to the

possible returned messages.

Transaction identification number. This is a unique number used to identify the transaction. ssl_txn_time ssl_loyalty_card_number

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10

AM. ssl_loyalty_account_balance Remaining balance on the loyalty card. ssl_amount Transaction amount. Returned based on the merchant setup. ssl_approval_code Transaction approval code.

Masked card number. ssl_loyalty_exp_date ssl_phone

Returned based on merchant setup.

The phone number. ssl_loyalty_program ssl_access_code ssl_promo_list

This value is used to return the merchant’s loyalty program description to be printed on the consumer’s receipt.

This value is used to identify the randomly generated access code that is tied to the primary customer for the account created as part of the loyalty program.

The promo list will contain 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

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

errorCode errorMessage errorName

Description

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant

configuration in the user interface. Refer to the Error Codes

section for more information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Loyalty Card Add Points (ltaddpoints)

This transaction type is used to add points to the loyalty card, either a phone number or a loyalty card data can be used. Points are added to the card and returned in the response.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_show_form ssl_phone

Req? Description

Y Loyalty Card Add Points (ltaddpoints).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Set value to true to show the Converge Payment Form

(Available only for process.do), set to false otherwise.

Required when a loyalty card is not available, this will allow accessing the loyalty information based on phone number.

Max 10 digits, no spaces or dashes.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_loyalty_track_data

Req? Description

C Required when a loyalty card is available for swiped transactions.

Notes:

 If using a MagTek encrypting device (MagneSafe), pass the encrypted loyalty track1 data in the ssl_encrypted_loyalty_track1_data

and/or the encrypted loyalty track 2 data in the ssl_encrypted_loyalty_track2_data



If using an Ingenico encrypting device (Generic

TDES DUKPT), pass the entire encrypted track data of the loyalty card combined into a single cipher text in the ssl_enc_loyalty_track_data.



Authorization Response Codes section for an extensive list of

information. ssl_loyalty_card_number C ssl_loyalty_exp_date ssl_amount

Required when a loyalty card is available for hand-keyed transactions.

Loyalty card number as it appears on the loyalty card.

Optional when a loyalty card is available for hand-keyed transactions. If not sent it is defaulted to 1249.

Loyalty card expiry date as it appears on loyalty card.

Format: MMYY.

Transaction sale amount, number with two decimal places.

For example: 1.00.

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id

Description

Outcome of a transaction. A response that contains ssl_result

of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized.

Transaction result message. Example: APPROVAL. Refer to the

possible returned messages.

Transaction identification number. This is a unique number used to identify the transaction. ssl_txn_time ssl_loyalty_card_number

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10

AM. ssl_loyalty_account_balance Remaining balance on the loyalty card. ssl_amount Transaction amount. Returned based on the merchant setup. ssl_approval_code Transaction approval code

Masked card number. ssl_loyalty_exp_date ssl_phone

Returned based on merchant setup.

The phone number. ssl_loyalty_program ssl_access_code ssl_promo_list

This value is used to return the merchant’s loyalty program description to be printed on the consumer’s receipt.

This value is used to identify the randomly generated access code that is tied to the primary customer for the account created as part of the loyalty program.

The promo list will contain 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

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

errorCode errorMessage errorName

Description

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant

configuration in the user interface. Refer to the Error Codes

section for more information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Loyalty Card Balance Inquiry (ltinquiry)

Loyalty card inquiry transaction is used to get current balance and any current rewards or offers are available for this loyalty card, either a phone number or a loyalty card data can be used.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_show_form ssl_phone

Req? Description

Y Loyalty Card Balance Inquiry (ltinquiry).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Set value to true to show the Converge Payment Form

(Available only for process.do), set to false otherwise.

Required when a loyalty card is not available, this will allow accessing the loyalty information based on phone number.

Max 10 digits, no spaces or dashes.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_loyalty_track_data ssl_ksn ssl_loyalty_card_number ssl_loyalty_exp_date

Req? Description

C Required when a loyalty card is available for swiped transactions.

Notes:

 If using a MagTek encrypting device (MagneSafe), pass the encrypted loyalty track1 data in the ssl_encrypted_loyalty_track1_data

and/or the encrypted loyalty track 2 data in the ssl_encrypted_loyalty_track2_data



If using an Ingenico encrypting device (Generic

TDES DUKPT), pass the entire encrypted track data of the loyalty card combined into a single cipher text in the ssl_enc_loyalty_track_data.



Authorization Response Codes section for an extensive list of

information.

Required when sending track data from an encrypting device for payment cards.

The Key Serial Number generated from the swiped payment card, this is the value returned by the encrypting device. This value is used to encrypt the PAN data, using the Derived

Unique Key Per Transaction (DUKPT) method. It is a 10 byte composite field that is transmitted as 20 alphanumeric character fixed length.

Required when a loyalty card is available for hand-keyed transactions.

Loyalty card number as it appears on the loyalty card.

Optional when a loyalty card is available for hand-keyed transactions. If not sent it is defaulted to 1249.

Loyalty card expiry date as it appears on loyalty card.

Format: MMYY.

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id

Description

Outcome of a transaction. A response that contains ssl_result

of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized.

Transaction result message. Example: APPROVAL. Refer to the

possible returned messages.

Transaction identification number. This is a unique number used to identify the transaction. ssl_txn_time ssl_loyalty_exp_date

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10

AM. ssl_loyalty_account_balance Remaining balance on the loyalty card. ssl_approval_code Transaction approval code. ssl_loyalty_card_number Masked card number.

Returned based on merchant setup. ssl_phone ssl_loyalty_program

The phone number.

This value is used to return the merchant’s loyalty program description to be printed on the consumer’s receipt. ssl_access_code ssl_promo_list errorCode errorMessage errorName

This value is used to identify the randomly generated access code that is tied to the primary customer for the account created as part of the loyalty program.

The promo list will contain 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

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant

configuration in the user interface. Refer to the Error Codes

section for more information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Converge Developer Guide: Transaction Format CON-0002-N

Loyalty Card Lead Inquiry (ltleadinquiry)

Lead Inquiry transaction is used to determine if a payment card is enrolled in the loyalty program and has any current offers\rewards available for redemption. If the payment card is not enrolled and the cardholder wishes to enroll the application can link the card using a Credit Card Sale

(ccsale). This transaction type requires a credit card number.

Request

Input Field Name Req? Description

ssl_transaction_type Y

Loyalty Card Inquiry (ltinquiry). ssl_merchant_id Y Converge ID as provided by Elavon. ssl_user_id ssl_pin

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive. ssl_show_form N ssl_track_data ssl_ksn

Set value to true to show the Converge Payment Form (Available only for process.do), set to false otherwise.

Required for swiped transactions.

The raw track I and/or II data from the magnetic strip on the payment card including beginning and ending sentinels.

Expiration date, first and last name of the cardholder are included with the Track I data.

Notes:

 If using a Magtek encrypting device, pass the encrypted track data in the ssl_encrypted_track1_data and/or ssl_encrypted_track2_data.



If using an Ingenico encrypting device, pass the encrypted track data in the ssl_enc_track_data.



Refer to the Encryption section for more information.

Required when sending track data from an encrypting device for payment cards.

The Key Serial Number generated from the swiped payment card, this is the value returned by the encrypting device. This value is used to encrypt the PAN data, using the Derived Unique Key Per

Transaction (DUKPT) method. It is a 10 byte composite field that is transmitted as 20 alphanumeric character fixed length.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_card_number ssl_exp_date ssl_amount

Req? Description

C Required for hand-keyed transactions.

Credit Card Number as it appears on the credit card.

C Required for hand-keyed transactions.

Credit Card Expiry Date as it appears on credit card formatted as

MMYY.

Note: Do not send an expiration date with a token that is stored in the Card Manager.

Y Required, the transaction sale amount. Number with 2 decimal places. This amount includes the Net amount and Sales Tax.

Note: When payment card is associated to a loyalty program and has points, rewards or discounts available, the cardholder can opt to use the rewards towards current sale. In this case a new transaction amount is calculated.

Response

Output Field Name

ssl_result ssl_result_message

Description

Outcome of a transaction. A response that contains ssl_result

of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized.

Transaction result message. Example: APPROVAL. Refer to the

Authorization Response Codes section for an extensive list of

possible returned messages. ssl_txn_id ssl_txn_time ssl_card_number

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10

AM. ssl_approval_code Transaction approval code. ssl_loyalty_account_balance

Remaining balance on the loyalty card. ssl_account_balance Balance on the payment card. ssl_amount Transaction amount. Returned based on the merchant setup.

Masked card number. ssl_loyalty_program ssl_access_code

This value is used to return the merchant’s loyalty program description to be printed on the consumer’s receipt.

This value is used to identify the randomly generated access code that is tied to the primary customer for the account created as part of the loyalty program.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_account_status ssl_loyalty_prompt

Description

Status of account

 1 = Setup (Lead)



2 = Active

 3 = Suspended



4 = Expired

 5 = Closed

Determine if the point of Sale application should prompt the consumer to enroll or not.

 N = Do not prompt



Y = Prompt to enroll ssl_tender_amount ssl_promo_code ssl_promo_code_name

The new discounted amount, this value is used to identify the transaction amount less the discount for the current offer, if available.

Promotion/offer code.

Promotion/offer name. ssl_promo_code_description Promotion/offer description. ssl_promo_code_issue_points Issue points for this promotional code. ssl_promo_list The promo list will contain 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

. errorCode Error code returned only if an error occurred. 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. Refer to the Error Codes section for more

information. errorMessage errorName

Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant

configuration in the user interface. Refer to the Error Codes

section for more information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Converge Developer Guide: Transaction Format CON-0002-N

Loyalty Card Member Inquiry (ltmemberinquiry)

Member Inquiry transaction is used to determine if a payment card or phone number is registered to a member and has any current offers\rewards available for redemption. If the loyalty card or the phone number is not enrolled and the cardholder wishes to enroll, the application can link the card or phone number using an enrollment (ltenrollment). Either a phone number or the loyalty card data can be used.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_show_form ssl_phone ssl_loyalty_track_data

Req? Description

Loyalty Member Inquiry l(tmemberinquiry).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Set value to true to show the Converge Payment Form

(Available only for process.do), set to false otherwise.

Required when a loyalty card is not available, this will allow accessing the loyalty information based on phone number.

Max 10 digits, no spaces or dashes.

Required when a loyalty card is available for swiped transactions.

Notes:



If using a MagTek encrypting device (MagneSafe), pass the encrypted loyalty track1 data in the ssl_encrypted_loyalty_track1_data

and/or the encrypted loyalty track 2 data in the ssl_encrypted_loyalty_track2_data

 If using an Ingenico encrypting device (Generic

TDES DUKPT), pass the entire encrypted track data of the loyalty card combined into a single cipher text in the ssl_enc_loyalty_track_data.



Authorization Response Codes section for an extensive list of

information.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_ksn

Req? Description

C Required when sending track data from an encrypting device for payment cards.

The Key Serial Number generated from the swiped payment card, this is the value returned by the encrypting device. This value is used to encrypt the PAN data, using the Derived

Unique Key Per Transaction (DUKPT) method. It is a 10 byte composite field that is transmitted as 20 alphanumeric character fixed length. ssl_loyalty_card_number C Required when a loyalty card is available for hand-keyed transactions.

Loyalty card number as it appears on the loyalty card. ssl_loyalty_exp_date C Required when a loyalty card is available for hand-keyed transactions.

Loyalty card expiry date as it appears on loyalty card. ssl_amount Y Required, the transaction sale amount. Number with 2 decimal places. This amount includes the Net amount and

Sales Tax.

Note: When loyalty card is associated to a loyalty program and has points, rewards or discounts available, the cardholder can opt to use the rewards towards current sale. In this case a new transaction amount is calculated.

Response

Output Field Name

ssl_result ssl_result_message

Description

Outcome of a transaction. A response that contains ssl_result

of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized.

Transaction result message. Example: APPROVAL. Refer to the

possible returned messages. ssl_txn_id ssl_txn_time

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10

AM. ssl_approval_code Transaction approval code. ssl_loyalty_account_balance

Remaining balance on the loyalty card. ssl_amount Transaction amount. Returned based on the merchant setup.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_loyalty_card_number ssl_loyalty_exp_date ssl_phone ssl_loyalty_program ssl_access_code ssl_account_status

Description

Masked card number.

Returned based on merchant setup.

The phone number.

This value is used to return the merchant’s loyalty program description to be printed on the consumer’s receipt.

This value is used to identify the randomly generated access code that is tied to the primary customer for the account created as part of the loyalty program.

Status of account:



1= Not a Loyalty Program Member based on Payment

Card

 2 = Already Enrolled for Loyalty Based on Payment

Card



3 = Suspended Loyalty Card

 4 = Expired Loyalty Card



5 = Closed Loyalty Card ssl_tender_amount ssl_promo_code ssl_promo_code_name

The new discounted amount, this value is used to identify the transaction amount less the discount for the current offer, if available.

Promotion/offer code.

Promotion/offer name. ssl_promo_code_description Promotion/offer description. ssl_promo_code_issue_points

Issue points for this promotional code. ssl_promo_list The promo list will contain 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

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

errorCode errorMessage errorName

Description

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant

configuration in the user interface. Refer to the Error Codes

section for more information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Loyalty Card Void (ltvoid)

The ltvoid is a transaction that removes a loyalty transaction from the open batch and restores the points or promo code back to the card. The ltvoid command is typically used for same day returns or to correct cashier mistakes. This action can only be performed before the batch is settled. To perform an ltvoid, you must submit the transaction ID received from the original loyalty transaction.

Note: The ssl_show_form property does not apply on Void transactions.

Request

Input Field Name

ssl_transaction_type Y ssl_merchant_id

Req? Description

Loyalty Void (ltvoid).

Converge ID as provided by Elavon. ssl_user_id ssl_pin

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive. ssl_txn_id

Y Unique identifier returned on the original loyalty transaction.

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id errorName

Description

Outcome of a transaction. A response that contains ssl_result

of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized.

Transaction result message. Example: APPROVAL. Refer to the

Authorization Response Codes section for an extensive list of

possible returned messages.

Transaction identification number. This is a unique number used to identify the transaction. ssl_txn_time ssl_loyalty_exp_date

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10

AM. ssl_approval_code Transaction approval code. ssl_loyalty_account_balance Remaining balance on the loyalty card. ssl_loyalty_card_number Masked card number.

Returned based on merchant setup. ssl_phone ssl_promo_code

The phone number.

Promo code used in this transaction. ssl_loyalty_program ssl_access_code errorCode

This value is used to return the merchant’s loyalty program description to be printed on the consumer’s receipt.

This value is used to identify the randomly generated access code that is tied to the primary customer for the account created as part of the loyalty program.

numeric field. Refer to the Error Codes section for more

information. errorMessage Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant

configuration in the user interface. Refer to the Error Codes

section for more information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Converge Developer Guide: Transaction Format CON-0002-N

Loyalty Card Delete (ltdelete)

The ltdelete is a transaction that attempts a reversal on a loyalty authorization, once successful it deletes the transaction from the loyalty batch. A transaction that has been deleted from the batch cannot be recovered.

Reversals restore the previous points or promo on a card and removes the transaction from the batch so there is no record. For all cashier mistakes it is recommended to use the loyalty voids instead. To perform an ltreversal, you must submit the transaction ID received from the original transaction.

Note: The ssl_show_form property does not apply on Delete transactions.

Request

Input Field Name Req? Description

ssl_transaction_type Y Loyalty Card Delete (ltdelete). ssl_merchant_id ssl_pin

Converge ID as provided by Elavon.

Converge PIN as configured within Converge, case sensitive. ssl_user_id ssl_txn_id

Converge User ID as configured on Converge, case sensitive.

Unique identifier returned on the original transaction.

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id ssl_txn_time

Description

Outcome of a transaction. A response that contains ssl_result

of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized.

Transaction result message. Example: APPROVAL. Refer to the

Authorization Response Codes section for an extensive list of

possible returned messages.

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10

AM. ssl_approval_code Transaction approval code. ssl_loyalty_account_balance Remaining balance on the loyalty card. ssl_loyalty_card_number Masked card number. ssl_loyalty_exp_date Returned based on merchant setup.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_phone ssl_promo_code ssl_loyalty_program ssl_access_code errorCode errorMessage errorName

Description

The phone number.

Promo code used in this transaction.

This value is used to return the merchant’s loyalty program description to be printed on the consumer’s receipt.

This value is used to identify the randomly generated access code that is tied to the primary customer for the account created as part of the loyalty program.

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant

configuration in the user interface. Refer to the Error Codes

section for more information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Electronic Check Transactions

Electronic Checks Service (ECS) supports two types of check processing: check present ECS Paper

Check and check not present ACH ECheck.

Important Notes:

 Credentials

A unique API user different from the Merchant Admin (MA) user ID must be used.

 Check Data

You must pass one of the following fields:

 MICR check data and image, electronically captured from a check reader for ECS Paper

Check Conversion: POP, BOC, and ARC.



Hand-keyed check information for ACH ECheck: WEB, TEL, PPD, CCD. Refer to the

Electronic Check ACH ECheck section for more information and best practices.



Recurring

No MICR data or check images are allowed when setting up recurring payments for electronic checks.

Converge Developer Guide: Transaction Format CON-0002-N

Electronic Check Purchase (ecspurchase)

The ecspurchase is a transaction in which money is debited from a checking account using a check. Data is either captured manually (ACH ECheck : WEB, TEL, PPD, CCD) or from a paper check

(ECS Paper Conversion: POP, BOC and ARC) using a check reader device.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_micr_data ssl_check_image ssl_aba_number ssl_bank_account_number

Req? Description

Y Check Sale (ecspurchase).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Required only for ECS Paper Check conversion.

MICR number as read through the check reader.

The unformatted Magnetic Ink Character Recognition

(MICR) data will be the exact MICR line from the check, including spaces, except that the MICR symbols will be replaced as follows (raw TOAD format):



The Transit symbol ( ) must be replaced by the letter (T) in either upper or lower case.

 The On-US symbol ( ) must be replaced by the letter (O) in either upper or lower case.



The Amount symbol ( ) must be replaced by the letter (A) in either upper or lower case.



The Dash symbol ( ) must be replaced by the letter (D) in either upper or lower case.

Required only for ECS Paper Check conversion.

Check Image Data base 64 TIFF image. Failure to properly format the image in a BASE64 encode message will result in an error when attempting to post the message.

Required only for ACH ECheck.

Routing/Transit Number as printed on the Check.

Required only for ACH ECheck.

Bank account number as printed on the Check. Not applicable for Paper Check conversion.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_check_number ssl_bank_account_type ssl_agree ssl_amount ssl_ecs_product_code ssl_first_name ssl_last_name ssl_company ssl_drivers_license_number ssl_drivers_license_ phone_number ssl_drivers_license_state

Req? Description

N Optional for ACH ECheck. (Not applicable Paper Check conversion.)

The check Number as printed on the Check. Check number is rarely used for ACH ECheck.

C Required only for ACH ECheck.

The bank account type. One numeric digit value, valid values are: 0 for Personal, 1 for Business.

Required only for ACH ECheck.

The agreement flag. One numeric digit value, valid values are: 1 for I agree, 0 for I do not Agree.

Transaction Sale Amount. Must be number with 2 decimal places. This amount does not include the tip amount which must be sent separately if needed.

Optional for ACH ECheck. Not applicable for Paper Check conversion.

The ACH type. 3 alpha value, valid values are: WEB, TEL,

PPD, sent only when account type is personal to indicate the type of ACH transaction to process. This value is automatically set to CCD when the check is business.

Required for ACH ECheck with Personal Checks.

The Consumer first name. Alphanumeric.

Required for ACH ECheck with Personal Checks.

The Consumer last name.

Required for ACH ECheck with Business Checks.

Company Name.

Required with ECS Paper Check – Guarantee.

Driver’s License number as entered by the user.

Alphanumeric.

Required with ECS Paper Check – Guarantee.

Customers 10 digit Phone number including the area code.

Required with ECS Paper Check – Guarantee.

State Code

Converge Developer Guide: Transaction Format

Input Field Name

ssl_tip_amount ssl_server ssl_shift

CON-0002-N

Req? Description

N Only used in a Service market segment.

Tip or gratuity amount to be added to the transaction sale amount. Number with 2 decimal places, can be 0.00 to indicate no tip was provided.

Only used in a Service market segment.

Server ID, this is the clerk, cashier, and waiter or waitress identification number.

Alphanumeric, Example: Jack.

Only used in a Service market segment.

Shift, can refer to or used to identify time period, course or type of service.

Alphanumeric, Example: Lunch.

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id ssl_txn_time ssl_amount ssl_base_amount ssl_tip_amount ssl_approval_code ssl_reference_number ssl_bank_account_number ssl_check_number

Description

Outcome of a transaction. A response that contains ssl_result

of 0 represents an Approved transaction. A response containing any other value for ssl_result represents a Declined transaction preventing it from being authorized.

Transaction result message. Example: APPROVAL.

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed.

Format: MM/DD/YYYY hh:mm:ss PM/AM. Example:

03/18/2010 10:34:10 AM.

The total transaction amount. Returned based on merchant setup.

Only used in a Service market segment.

Base amount. Transaction amount sent originally on the request. Returned based on merchant setup.

Only used in a Service market segment.

Tip or gratuity amount that was added or updated.

Returned based on merchant setup.

Transaction approval code.

The reference number.

Bank account number.

The check number.

227

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_drivers_license_number ssl_drivers_license_phone_number Customers 10 digit Phone number including the area code. ssl_drivers_license_state ssl_aba_number

State Code.

Routing/Transit Number from the parsed MICR data. ssl_server

Description

The driver’s license number as entered by the user. ssl_shift

Server Id submitted with the request. Only returned on

Service market segment based on the merchant setup.

Shift information submitted with the request. Only returned on Service market segment based on the merchant setup. ssl_email errorCode errorMessage errorName

Returned based on merchant setup.

Error code returned only if an error occurred, 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. Refer to the Error

Codes section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant

configuration in the user interface. Refer to the Error

Codes section for more information.

Error name or reason for the error returned only if an

error occurred. Refer to the Error Codes section for more

information.

Converge Developer Guide: Transaction Format CON-0002-N

Electronic Check Void (ecsvoid)

The ecsvoid is a transaction that reverses a Check Sale. No funds will be deposited into the merchant’s bank account. The ecsvoid command is typically used to correct cashier mistakes.

There is a 10-minute limited window in which a Check Card void can be completed. To perform an ecsvoid you must submit the transaction ID submitted in the original transaction.

Note: The ssl_show_form property does not apply on Void transactions.

Request

Input Field Name Req? Description

ssl_transaction_type

Y Check Void (ecsvoid). ssl_merchant_id Y Converge ID as provided by Elavon. ssl_user_id ssl_pin ssl_txn_id

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Unique identifier returned on the original transaction.

Response

Output Field Name

ssl_result ssl_result_message Transaction result message. Example: APPROVAL. ssl_txn_id

Transaction identification number. This is a unique number used to identify the transaction. ssl_approval_code Transaction approval code. ssl_txn_time Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM. errorCode

Error code returned only if an error occurred, 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. Refer to the Error Codes

section for more information. errorMessage Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant configuration in the user interface.

Refer to the Error Codes section for more information.

errorName

Description

Outcome of a transaction. A response that contains ssl_result of 0 represents an Approved transaction. A response containing any other value for ssl_result represents a Declined transaction.

Error name or reason for the error returned only if an error occurred. Refer to

numeric field. Refer to the Error Codes section for more

Converge Developer Guide: Transaction Format CON-0002-N

ACH ECheck Add Recurring Transaction (ecsaddrecurring)

The ecsaddrecurring is a transaction that adds an electronic check (ACH ECheck) recurring payment to the Converge recurring batch. Once added, the transaction will run automatically within the specified billing cycle on the scheduled payment day without the need to send it for authorization.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_show_form ssl_aba_number ssl_bank_account_number ssl_bank_account_type ssl_agree ssl_amount ssl_first_name ssl_last_name ssl_company ssl_next_payment_date

Req? Description

Add ACH ECheck Recurring (ecsaddrecurring).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

N Set value to true to show the Converge Payment Form

(available only for process.do), set to false otherwise.

Routing/Transit Number as printed on the Check.

Bank account number as printed on the Check.

The bank account type. One numeric digit value, valid values are: 0 for Personal, 1 for Business.

The agreement flag. One numeric digit value, valid values are: 1 for I agree, 0 for I do not Agree.

Transaction Amount. Must be number with 2 decimal places.

Required for ACH ECheck with Personal Checks.

The Consumer first name. Alphanumeric.

Required for ACH ECheck with Personal Checks.

The Consumer last name. Alphanumeric.

Required for ACH ECheck with Business Checks.

Company Name. Alphanumeric.

Next payment date. Format MM/DD/YYYY.

Converge Developer Guide: Transaction Format

Input Field Name

ssl_billing_cycle ssl_bill_on_half ssl_end_of_month ssl_skip_payment ssl_description

CON-0002-N

Req? Description

Y Billing cycle.

Valid returned values, all caps and no hyphens:

 DAILY



WEEKLY

 BIWEEKLY



SEMIMONTHLY

 MONTHLY



BIMONTHLY



QUARTERLY



SEMESTER

 SEMIANNUALLY



ANNUALLY



SUSPENDED

Half of the month or Semimonthly indicator.

Valid values are 1 and 2:

 1 = the 1st and the 15th of the month



2 = the 15th and the last day of the month

End of month indicator. Valid values Y or N



30-Apr



30-June



30-Sept



30-Nov

 28-Feb (non-leap year)



29-Feb (leap year)

You also need to provide the end of the month indicator for the annually billing cycles when the start payment date is any of the following dates:

 28-Feb (non-leap year)



29-Feb (leap year)

Skip Payment field. Valid values: Y for yes or N for no.

Defaulted to N.

The description, merchant defined value.

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_result ssl_result_message

Description

Outcome of a transaction. A response that contains ssl_result of 0 represents a successful recurring transaction.

Transaction result message. A result of SUCCESS indicates the recurring was successfully added. ssl_recurring_id ssl_amount ssl_billing_cycle ssl_next_payment_date

The ID number of the ACH ECheck recurring record added returned on SUCCESS only.

Recurring amount.

Billing cycle.

Next payment due date. ssl_recurring_batch_count Current number of transactions sitting in the recurring batch after the recurring transaction has been added. ssl_start_payment_date Start payment date. Format MM/DD/YYYY. Date when the first payment started. If recently added, start date is same as next payment. ssl_aba_number

Routing/Transit Number. ssl_bank_account_number

Bank account number masked. ssl_bank_account_type ssl_first_name

The bank account type.

Returned based on the merchant setup. ssl_last_name

Returned based on the merchant setup. ssl_company ssl_description errorCode errorMessage errorName

Returned based on the merchant setup.

information.

Detailed explanation of the error returned only if an error occurred.

This field may be changed based on merchant configuration in the

user interface. Refer to the Error Codes section for more

information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Converge Developer Guide: Transaction Format CON-0002-N

Example

Example 1: process.do(false)

Shown below are the key value pairs from the header by themselves for adding an ACH ECheck recurring transaction. ssl_merchant_id=xxxxxx ssl_user_id=xxxxxxx ssl_pin=xxxxxx ssl_show_form=false ssl_transaction_type=ecsaddrecurring ssl_aba_number=123456789 ssl_bank_account_number=1234567890 ssl_bank_account_type=1 ssl_agree=1 ssl_amount=10.00 ssl_company=Elavon ssl_billing_cycle=MONTHLY ssl_next_payment_date=09/15/2014 ssl_skip_payment=Y

Converge then returns a response to the POST by specifying the http://www.url.com/cgibin/testtran.cgi

URL in the ssl_apprvl_get_url field for the redirect for the transaction above, the following values are returned for the successful transaction.

Shown below are the key value pairs returned when successfully adding a recurring transaction. ssl_start_payment_date=09/15/2014 ssl_transaction_type=ECSADDRECURRING ssl_aba_number=123456789 ssl_bank_account_number=12**********7890 ssl_amount=10.00 ssl_next_payment_date=09/15/2014 ssl_billing_cycle=MONTHLY ssl_result_message=SUCCESS ssl_recurring_id=190115A15-E123C27A-CC10-44E6-811E-185097739FD2 ssl_skip_payment=N ssl_recurring_batch_count=23

Converge Developer Guide: Transaction Format CON-0002-N

Based on the billing cycle and the start date supplied, the recurring transaction will run automatically in the system without further action from the merchant.

By specifying the http://www.url.com/cgi-bin/testtran.cgi URL in the ssl_error_url

field for the redirect for the transaction above, for example, the following error is returned if one of the credentials in the request is invalid: errorCode=4025 errorName=Invalid Credentials errorMessage=The credentials supplied in the authorization request are invalid

ACH ECheck Update Recurring Transaction (ecsupdaterecurring)

The ecsupdaterecurring is a transaction that updates an existing electronic check (ACH

ECheck) recurring payment in the Converge recurring batch. To perform an ecsupdaterecurring

, you must submit the recurring ID received when the ACH ECheck recurring payment was initially added to the system.

Note: The ssl_show_form property does not apply on Update transactions.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_recurring_id ssl_agree ssl_aba_number

Req? Description

Update ACH ECheck Recurring (ecsupdaterecurring).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

The ID number of the recurring record to be updated. This value, was returned when the original recurring record was added. Alphanumeric.

The agreement flag. One numeric digit value, valid values are:

1 for I agree, 0 for I do not Agree.

To update the Routing/Transit Number. ssl_bank_account_number N

To update the bank account number. ssl_bank_account_type N ssl_amount N

To update the bank account type. One numeric digit value, valid values are: 0 for Personal, 1 for Business.

To update the transaction Amount. Must be number with 2 decimal places.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_first_name ssl_last_name ssl_company ssl_next_payment_date ssl_billing_cycle ssl_bill_on_half ssl_end_of_month

Req? Description

C To update the first name, this is only required for personal

Checks. Alphanumeric.

To update the last name, this is only required for personal

Checks. Alphanumeric.

To update the company, this is only required for business

Checks. Alphanumeric.

To update the Next payment date. Format MM/DD/YYYY.

To update the Billing cycle. Valid returned values, all caps and no hyphens:



DAILY

 WEEKLY



BIWEEKLY



SEMIMONTHLY



MONTHLY



BIMONTHLY

 QUARTERLY



SEMESTER

 SEMIANNUALLY



ANNUALLY

 SUSPENDED

Half of the month or Semimonthly indicator.

Valid values are 1 and 2:

 1 = the 1st and the 15th of the month



2 = the 15th and the last day of the month

End of month indicator. Valid values Y or N



30-Apr

 30-June



30-Sept

 30-Nov



28-Feb (non-leap year)

 29-Feb (leap year)

You also need to provide the end of the month indicator for the annually billing cycles when the start payment date is any of the following dates:

 28-Feb (non-leap year)



29-Feb (leap year)

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_skip_payment ssl_description

Req? Description

N Skip Payment field. Valid values: Y for yes or N for no.

Defaulted to N.

N To update or add a description, merchant defined value.

Response

Output Field Name

ssl_result ssl_result_message ssl_recurring_id ssl_amount ssl_billing_cycle

Description

Outcome of a transaction. A response that contains ssl_result of 0 represents a successful recurring transaction.

Transaction result message. A result of SUCCESS indicates the recurring was successfully updated.

The ID number of the updated recurring record returned on

SUCCESS only.

Recurring amount.

Billing cycle. ssl_next_payment_date Next payment due date. ssl_recurring_batch_count

Current number of transactions sitting in the recurring batch.. ssl_start_payment_date Start payment date. Format MM/DD/YYYY. Date when the first payment started. If recently added, start date is same as next payment. ssl_aba_number

Routing/Transit Number. ssl_bank_account_number

Bank account number masked. ssl_bank_account_type ssl_first_name

The bank account type.

Returned based on the merchant setup. ssl_last_name

Returned based on the merchant setup. ssl_company ssl_description errorCode errorMessage errorName

Returned based on the merchant setup.

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred.

This field may be changed based on merchant configuration in the

user interface. Refer to the Error Codes section for more

information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Converge Developer Guide: Transaction Format CON-0002-N

Example

The following example demonstrates the key value pairs needed to pass the minimum required data to update a recurring transaction and set the billing payment to Suspended. The recurring ID obtained from the original ACH ECheck transaction must be passed. ssl_merchant_id=my_virtualmerchant_id ssl_user_id=my_user_id ssl_pin=my_pin ssl_transaction_type=ecsupdaterecurring ssl_show_form=false ssl_recurring_id=190115A15-E123C27A-CC10-44E6-811E-185097739FD2 ssl_billing_cycle=SUSPENDED

ACH ECheck Delete Recurring Transaction (ecsdeleterecurring)

The ecsdeleterecurring is a transaction that deletes an electronic check (ACH ECheck) recurring payment from the Converge recurring batch. To perform an ecsdeleterecurring, you must submit the recurring ID received when the ACH recurring payment was initially added to the system.

Note: The ssl_show_form property does not apply on Delete transactions.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_recurring_id

Req? Description

Y Delete ACH ECheck Recurring (ecsdeleterecurring).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

The ID number of the recurring record to be updated. This value was returned when the original recurring record was added.

Alphanumeric.

Response

Output Field Name

ssl_result ssl_result_message

Description

Outcome of a transaction. A response that contains ssl_result of 0 represents a successful recurring transaction.

Transaction result message. A result of SUCCESS indicates the recurring was successfully deleted.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_recurring_id ssl_amount ssl_billing_cycle ssl_next_payment_date

Description

The ID number of the updated recurring record returned on

SUCCESS only.

Recurring amount.

Billing cycle.

Next payment due date. ssl_recurring_batch_count Current number of transactions sitting in the recurring batch after the recurring transaction has been deleted. ssl_start_payment_date Start payment date. Format MM/DD/YYYY. Date when the first payment started. If recently added, start date is same as next payment. ssl_aba_number

Routing/Transit Number. ssl_bank_account_number

Bank account number masked. ssl_bank_account_type ssl_first_name

The bank account type.

Returned based on the merchant setup. ssl_last_name

Returned based on the merchant setup. ssl_company ssl_description errorCode errorMessage errorName

Returned based on the merchant setup.

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred.

This field may be changed based on merchant configuration in the

user interface. Refer to the Error Codes section for more

information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

ACH ECheck Submit Recurring Payment (ecsrecurringsale)

The ecsrecurringsale is a transaction that allows you to run an electronic check (ACH

ECheck) recurring payment outside of its billing cycle. This will increase the payment number. To perform an ecsrecurringsale, you must submit the recurring ID received when the ACH recurring payment was initially added to the system.

Note: The ssl_show_form property does not apply when submitting payments.

Converge Developer Guide: Transaction Format CON-0002-N

Request

Input Field Name Req? Description

ssl_transaction_type Y Submit ACH ECheck Recurring Payment (ecsrecurringsale). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin ssl_recurring_id

Converge PIN as configured within Converge, case sensitive.

The ID number of the recurring record to be submitted for payment. This value was returned when the original recurring record was added. Alphanumeric.

Response

Output Field Name

ssl_result

Description

Transaction result message. Example: APPROVAL. ssl_result_message ssl_txn_id ssl_txn_time ssl_recurring_id

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 09/18/2014 10:34:10

AM.

The ID number of the recurring record sent for payment. ssl_amount ssl_approval_code ssl_billing_cycle ssl_next_payment_date

Transaction authorized or approved amount. Returned based on merchant setup.

Transaction approval code.

Billing cycle.

Next payment due date. ssl_recurring_batch_count Current number of transactions sitting in the recurring batch. ssl_start_payment_date

Start payment date. Format MM/DD/YYYY. Date when the first payment started. If recently added, start date is same as next payment. ssl_aba_number

Routing/Transit Number. ssl_bank_account_number

Bank account number masked. ssl_bank_account_type ssl_first_name

The bank account type.

Returned based on the merchant setup. ssl_last_name

Returned based on the merchant setup.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_company ssl_description errorCode errorMessage errorName

Description

Returned based on the merchant setup.

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred.

This field may be changed based on merchant configuration in the

user interface. Refer to the Error Codes section for more

information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Example

The following example demonstrates the key value pairs needed to pass the minimum required data to send a recurring sale outside of the billing cycle. The recurring ID obtained from the original transaction must be passed. This transaction will increase the total payments. ssl_merchant_id=my_virtualmerchant_id ssl_user_id=my_user_id ssl_pin=my_pin ssl_transaction_type=ecsrecurringsale ssl_show_form=false ssl_recurring_id=AB404C6-C08B6F1B-4799-A5FF-C0BK-5882F21A0EB9

Converge Developer Guide: Transaction Format CON-0002-N

ACH ECheck Add Installment Transaction (ecsaddinstall)

The ecsaddinstall is a transaction that adds an electronic check (ACH ECheck) installment to the Converge recurring batch. Once added, the transaction will run automatically for the number of installments specified within the specified billing cycle on the scheduled payment day without the need to send it for authorization. Once the total number of installments is reached the payments will stop running.

Request

Input Field Name

Req? Description

Add ACH ECheck Installment (ecsaddinstall).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Set value to true to show the Converge Payment Form

(available only for process.do), set to false otherwise.

Routing/Transit Number as printed on the Check.

Bank account number as printed on the Check.

The bank account type. One numeric digit value, valid values are: 0 for Personal, 1 for Business.

The agreement flag. One numeric digit value, valid values are: 1 for I agree, 0 for I do not Agree.

Transaction Amount. Must be number with 2 decimal places.

Required for ACH ECheck with Personal Checks.

The Consumer first name. Alphanumeric.

Required for ACH ECheck with Personal Checks.

The Consumer last name. Alphanumeric.

Required for ACH ECheck with Business Checks.

Company Name. Alphanumeric.

Next payment date. Format MM/DD/YYYY.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_billing_cycle ssl_total_installments ssl_bill_on_half ssl_end_of_month ssl_skip_payment ssl_description

Req? Description

Y Billing cycle.

Valid returned values, all caps and no hyphens:

 DAILY



WEEKLY

 BIWEEKLY



SEMIMONTHLY

 MONTHLY



BIMONTHLY



QUARTERLY



SEMESTER

 SEMIANNUALLY



ANNUALLY



SUSPENDED

Number of payments, Numeric. Example: 12

Half of the month or Semimonthly indicator.

Valid values are 1 and 2:



1 = the 1st and the 15th of the month

 2 = the 15th and the last day of the month

End of month indicator. Valid values Y or N

You must indicate if the installment transaction will be processed on the last day of the month for the monthly, bi-monthly, quarterly, semester, and semi-annually billing cycles when the start payment date is any of the following dates:

 30-Apr



30-June

 30-Sept



30-Nov



28-Feb (non-leap year)



29-Feb (leap year)

You also need to provide the end of the month indicator for the annually billing cycles when the start payment date is any of the following dates:



28-Feb (non-leap year)

 29-Feb (leap year)

Skip Payment field. Valid values: Y for yes or N for no.

Defaulted to N.

The description, merchant defined value.

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_result ssl_result_message

Description

Outcome of a transaction. A response that contains ssl_result of 0 represents a successful installment transaction.

Transaction result message. A result of SUCCESS indicates the installment was successfully added. ssl_installment_id ssl_amount ssl_billing_cycle ssl_total_installments

The ID number of the installment record added returned on

SUCCESS only.

Installment amount.

Billing cycle.

Number of payments. ssl_next_payment_date Next payment due date. ssl_recurring_batch_count Current number of transactions sitting in the recurring batch after the installment transaction has been added. ssl_start_payment_date Start payment date. Format MM/DD/YYYY. Date when the first payment started. If recently added, start date is same as next payment. ssl_aba_number

Routing/Transit Number. ssl_bank_account_number

Bank account number masked. ssl_bank_account_type ssl_first_name

The bank account type.

Returned based on the merchant setup. ssl_last_name

Returned based on the merchant setup. ssl_company ssl_description errorCode errorMessage errorName

Returned based on the merchant setup.

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred.

This field may be changed based on merchant configuration in the

user interface. Refer to the Error Codes section for more

information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Converge Developer Guide: Transaction Format CON-0002-N

Example

Example 1: process.do(false)

Shown below are the key value pairs from the header by themselves for adding an ACH ECheck installment transaction. ssl_merchant_id=xxxxxx ssl_user_id=xxxxxxx ssl_pin=xxxxxx ssl_show_form=false ssl_transaction_type=ecsaddinstall ssl_aba_number=123456789 ssl_bank_account_number=1234567890 ssl_bank_account_type=1 ssl_agree=1 ssl_amount=10.00 ssl_company=Elavon ssl_billing_cycle=MONTHLY ssl_total_installments=12 ssl_next_payment_date=09/15/2014 ssl_skip_payment=Y

Converge Developer Guide: Transaction Format CON-0002-N

Converge then returns a response to the POST by specifying the http://www.url.com/cgibin/testtran.cgi

URL in the ssl_apprvl_get_url field for the redirect for the transaction above, the following values are returned for the successful transaction.

Shown below are the key value pairs returned when successfully adding an installment transaction. ssl_start_payment_date=09/15/2014 ssl_transaction_type=ECSADDINSTALL ssl_aba_number=123456789 ssl_bank_account_number=12**********7890 ssl_amount=10.00 ssl_next_payment_date=09/15/2014 ssl_billing_cycle=MONTHLY ssl_total_installments=12 ssl_result_message=SUCCESS ssl_installment_id=230135A23-E125C27A-AA10-44E6-811E-385097739FD5 ssl_skip_payment=N ssl_recurring_batch_count=24

Based on the billing cycle and the start date supplied, the installment transaction will run automatically in the system without further action from the merchant for 12 months.

By specifying the http://www.url.com/cgi-bin/testtran.cgi URL in the ssl_error_url

Converge Developer Guide: Transaction Format CON-0002-N

ACH ECheck Update Installment Transaction (ecsupdateinstall)

The ecsupdateinstall is a transaction that updates an existing electronic check (ACH ECheck) installment in the Converge recurring batch. To perform an ecsupdateinstall, you must submit the installment ID received when the ACH ECheck installment payment was initially added to the system.

Note: The ssl_show_form property does not apply on Update transactions.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_installment_id ssl_agree ssl_aba_number

Req? Description

Y Update ACH ECheck Installment (ecsupdateinstall).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

The ID number of the installment record to be updated. This value, was returned when the original installment record was added. Alphanumeric.

The agreement flag. One numeric digit value, valid values are:

1 for I agree, 0 for I do not Agree.

To update the Routing/Transit Number. ssl_bank_account_number N

To update the bank account number. ssl_bank_account_type N ssl_amount ssl_first_name

To update the bank account type. One numeric digit value, valid values are: 0 for Personal, 1 for Business.

To update the transaction Amount. Must be number with 2 decimal places.

To update the first name, this is only required for personal

Checks. Alphanumeric. ssl_last_name C ssl_company ssl_next_payment_date

To update the last name, this is only required for personal

Checks. Alphanumeric.

To update the company, this is only required for business

Checks. Alphanumeric.

To update the Next payment date. Format MM/DD/YYYY.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_billing_cycle ssl_total_installments ssl_bill_on_half ssl_end_of_month ssl_skip_payment ssl_description

Req? Description

To update the Billing cycle. Valid returned values, all caps and no hyphens:

 DAILY



WEEKLY

 BIWEEKLY



SEMIMONTHLY

 MONTHLY



BIMONTHLY



QUARTERLY



SEMESTER

 SEMIANNUALLY



ANNUALLY



SUSPENDED

Number of payments, Numeric. Example: 12

C Half of the month or Semimonthly indicator.

Valid values are 1 and 2:



1 = the 1st and the 15th of the month

 2 = the 15th and the last day of the month

End of month indicator. Valid values Y or N

You must indicate if the installment transaction will be processed on the last day of the month for the monthly, bimonthly, quarterly, semester, and semi-annually billing cycles when the start payment date is any of the following dates:

 30-Apr



30-June

 30-Sept



30-Nov



28-Feb (non-leap year)



29-Feb (leap year)

You also need to provide the end of the month indicator for the annually billing cycles when the start payment date is any of the following dates:



28-Feb (non-leap year)

 29-Feb (leap year)

Skip Payment field. Valid values: Y for yes or N for no.

Defaulted to N.

To update or add a description, merchant defined value.

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_result ssl_result_message ssl_installment_id ssl_amount ssl_billing_cycle ssl_total_installments

Description

Outcome of a transaction. A response that contains ssl_result of 0 represents a successful installment transaction.

Transaction result message. A result of SUCCESS indicates the installment was successfully updated.

The ID number of the updated installment record returned on

SUCCESS only.

Installment amount.

Billing cycle.

Total number of payments. ssl_number_of_payments ssl_next_payment_date

Number of payments that run so far.

Next payment due date. ssl_recurring_batch_count Current number of transactions sitting in the recurring batch. ssl_start_payment_date Start payment date. Format MM/DD/YYYY. Date when the first payment started. If recently added, start date is same as next payment. ssl_aba_number

Routing/Transit Number. ssl_bank_account_number

Bank account number masked. ssl_bank_account_type ssl_first_name

The bank account type.

Returned based on the merchant setup. ssl_last_name

Returned based on the merchant setup. ssl_company ssl_description errorCode errorMessage errorName

Returned based on the merchant setup.

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred.

This field may be changed based on merchant configuration in the

user interface. Refer to the Error Codes section for more

information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Converge Developer Guide: Transaction Format CON-0002-N

Example

The following example demonstrates the key value pairs needed to pass the minimum required data to update an installment transaction and set the billing number to10. The installment ID obtained from the original ACH ECheck transaction must be passed. ssl_merchant_id=my_virtualmerchant_id ssl_user_id=my_user_id ssl_pin=my_pin ssl_transaction_type=ecsupdateinstall ssl_show_form=false ssl_installment_id=230135A23-E125C27A-AA10-44E6-811E-385097739FD5 ssl_total_installments=10

ACH ECheck Delete Installment Transaction (ecsdeleteinstall)

The ecsdeleteinstall is a transaction that deletes an electronic check (ACH ECheck) installment from the Converge recurring batch. To perform an ecsdeleteinstall, you must submit the installment ID received when the ACH installment payment was initially added to the system.

Note: The ssl_show_form property does not apply on Delete transactions.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_installment_id

Req? Description

Y Delete ACH ECheck Installment (ecsdeleteinstall).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

The ID number of the installment record to be deleted. This value was returned when the original installment record was added.

Alphanumeric.

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_result ssl_result_message ssl_installment_id ssl_amount ssl_billing_cycle ssl_total_installments

Description

Outcome of a transaction. A response that contains ssl_result of 0 represents a successful installment transaction.

Transaction result message. A result of SUCCESS indicates the installment was successfully deleted.

The ID number of the updated installment record returned on

SUCCESS only.

Installment amount.

Billing cycle.

Total number of payments. ssl_number_of_payments ssl_next_payment_date

Number of payments that run so far.

Next payment due date. ssl_recurring_batch_count Current number of transactions sitting in the recurring batch after the installment transaction has been deleted. ssl_start_payment_date Start payment date. Format MM/DD/YYYY. Date when the first payment started. If recently added, start date is same as next payment. ssl_aba_number

Routing/Transit Number. ssl_bank_account_number

Bank account number masked. ssl_bank_account_type ssl_first_name

The bank account type.

Returned based on the merchant setup. ssl_last_name

Returned based on the merchant setup. ssl_company ssl_description errorCode errorMessage errorName

Returned based on the merchant setup.

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred.

This field may be changed based on merchant configuration in the

user interface. Refer to the Error Codes section for more

information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Converge Developer Guide: Transaction Format CON-0002-N

ACH ECheck Submit Installment Payment (ecsinstallsale)

The ecsinstallsale is a transaction that allows you to run an electronic check (ACH ECheck) installment payment outside of its billing cycle. This will increase the payment number. To perform an ecsinstallsale, you must submit the installment ID received when the ACH installment payment was initially added to the system.

Note: The ssl_show_form property does not apply when submitting payments.

Request

Input Field Name Req? Description

ssl_transaction_type

Y Submit ACH ECheck Installment Payment (ecsinstallsale). ssl_merchant_id Y Converge ID as provided by Elavon. ssl_user_id ssl_pin ssl_installment_id

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

The ID number of the installment record to be submitted for payment. This value was returned when the original installment record was added. Alphanumeric.

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_id ssl_txn_time ssl_installment_id ssl_amount ssl_approval_code ssl_billing_cycle ssl_total_installments ssl_number_of_payments ssl_next_payment_date

Description

Transaction result message. Example: APPROVAL.

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 09/18/2014 10:34:10

AM.

The ID number of the installment record sent for payment.

Transaction authorized or approved amount. Returned based on merchant setup.

Transaction approval code.

Billing cycle.

Total number of payments.

Number of payments that run so far.

Next payment due date.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name Description

ssl_recurring_batch_count Current number of transactions sitting in the recurring batch. ssl_start_payment_date Start payment date. Format MM/DD/YYYY. Date when the first payment started. If recently added, start date is same as next payment. ssl_aba_number

Routing/Transit Number. ssl_bank_account_number

Bank account number masked. ssl_bank_account_type ssl_first_name

The bank account type.

Returned based on the merchant setup. ssl_last_name

Returned based on the merchant setup. ssl_company ssl_description errorCode errorMessage errorName

Returned based on the merchant setup.

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred.

This field may be changed based on merchant configuration in the

user interface. Refer to the Error Codes section for more

information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Example

The following example demonstrates the key value pairs needed to pass the minimum required data to send an installment sale outside of the billing cycle. The installment ID obtained from the original transaction must be passed. This transaction will increase the total payments. ssl_merchant_id=my_virtualmerchant_id ssl_user_id=my_user_id ssl_pin=my_pin ssl_transaction_type=ecsinstallsale ssl_show_form=false ssl_installment_id=230135A23-E125C27A-AA10-44E6-811E-385097739FD5

Converge Developer Guide: Transaction Format CON-0002-N

PINLess Debit Transactions

This message format is for PINLess Debit Card transactions. Those types of debit transactions do not require a PIN pad or a PIN entry.

PINLess Debit Purchase (pldpurchase)

Transaction used to obtain a real-time authorization for a Debit Card sale transaction without PIN number input.

Request

Input Field Name Req? Description

ssl_transaction_type Y PINLess Debit Purchase (pldpurchase). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin ssl_show_form ssl_account_type ssl_amount

Converge PIN as configured within Converge, case sensitive.

Set value to true to show the Converge Payment form (Available only for process.do), set to false otherwise.

Account Type (0=checking, 1=saving).

Transaction base amount must be sent on request. This amount does not include the surcharge amount. Decimal, for example:

1.00. ssl_card_number ssl_exp_date ssl_customer_number

Debit Card Number as it appears on the debit card.

Debit Card Expiry date as it appears on debit card.

This value is used to submit the Customer Account Number or

Payee account number for PINLess Debit transactions.

Response

Output Field Name

ssl_result ssl_result_message ssl_amount ssl_account_type ssl_approval_code ssl_base_amount

Description

Transaction result message. Example: APPROVAL.

The total transaction amount including surcharge amount if any.

Account Type (checking = 0, saving = 1). Required.

Transaction approval code.

The base transaction amount.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_card_number ssl_customer_number

Description

Masked debit card number passed on the original request.

The customer number. ssl_surcharge_amount The surcharge amount as configured by merchant. ssl_txn_id Transaction identification number. This is a unique number used to identify the transaction. ssl_txn_time errorCode

Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM.

interface. Refer to the Error Codes section for more information.

errorMessage errorName

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user

Error name or reason for the error returned only if an error occurred. Refer

from going to authorization. This is a numeric field. Refer to the Error Codes

Cash Tender Transactions

This message format is used to enter cash transactions. When processing Cash transactions you may add description, billing information, shipping information, tip and custom fields if applicable.

Once processed, the Cash transaction will show under the Current Batches in the Cash Batch.

Once closed, all cash transactions will show under Settle Batches Cash.

All Cash transactions will auto close at the end the day during auto settlement for those terminals set for auto settle. For those terminals set for manually settlement, they are automatically closed at 3:00 AM EST. A transaction type settle can be used to settle those types of transactions.

Notes:

 The ssl_show_form property does not apply on cash transactions.



Cash transactions are not allowed for the e-Commerce market segment.

Converge Developer Guide: Transaction Format CON-0002-N

Cash Sale (cashsale)

The cashsale transaction is used to enter a purchase by cash.

Request

Input Field Name Req? Description

ssl_transaction_type Y Cash Sale (cashsale). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin ssl_amount ssl_salestax ssl_tip_amount

Converge PIN as configured within Converge, case sensitive.

Transaction Sale Amount. Number with 2 decimal places. This amount includes the Net amount and Sales Tax.

Recommended for purchasing cards.

Sales tax amount applied to this transaction in decimal. Tax exempt transactions can pass 0.00 to properly reflect a tax exempt transaction.

Use only in a Service market segment.

Tip or gratuity amount to be added, must be 2 decimal places, can be 0.00 to reset or remove the original tip from a transaction.

Example: 1.00. ssl_server ssl_shift

Use only in a Service market segment.

Server ID, this is the clerk, cashier, and waiter or waitress identification number.

Alphanumeric, Example: Jack.

Use only in a Service market segment.

Shift, can refer to or be used to identify time period, course or type of service.

Alphanumeric, Example: Lunch.

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_result ssl_result_message Transaction result message. Example: APPROVAL. ssl_txn_id

Transaction identification number. This is a unique number used to identify the transaction. ssl_txn_time Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM. ssl_amount The total transaction authorized or approved amount. This amount will include tip if tip has been provided in the request. Returned based on merchant setup. ssl_base_amount ssl_tip_amount

Base amount. Transaction amount sent originally on the request. Returned based on merchant setup, base amount includes tax. Returned in the Service market segment.

Tip or gratuity amount that was added or updated. Returned based on merchant setup. Returned in the Service market segment. errorCode errorMessage errorName

Description

Error code returned only if an error occurred, typically when the transaction failed validation or the request is incorrect. This will prevent the transaction

section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on Merchant configuration in the user interface.

Refer to the Error Codes section for more information.

Error name or reason for the error returned only if an error occurred. Refer to

from going to authorization. This is a numeric field. Refer to the Error Codes

Converge Developer Guide: Transaction Format

Example

The following is an XML example request for a $3 sale:

Request

<txn>

<ssl_merchant_id>My_Merchant_id</ssl_merchant_id>

<ssl_user_id>My_User</ssl_user_id>

<ssl_pin>XXXXXX</ssl_pin>

<ssl_transaction_type>CASHSALE</ssl_transaction_type>

<ssl_amount>3.00</ssl_amount>

<ssl_salestax>0.21</ssl_salestax>

<anotherCustomField>testAnother12</anotherCustomField>

</txn>

<ssl_show_form>false</ssl_show_form>

CON-0002-N

Response

<txn>

<anotherCustomField>testAnother12</anotherCustomField>

<ssl_txn_time>12/18/2013 09:03:36 AM</ssl_txn_time>

<ssl_txn_id>AA776F-3CEC01A7-B70A-4584-AC8C-

5040C0297354</ssl_txn_id>

</txn>

<ssl_amount>3.00</ssl_amount>

<ssl_result>0</ssl_result><ssl_salestax>0.21</ssl_salestax>

<anothercustom>testAnother12</anothercustom>

<ssl_result_message>APPROVAL</ssl_result_message>

Converge Developer Guide: Transaction Format CON-0002-N

Cash Return/Credit (cashcredit)

This transaction is used to enter a refund by cash. This refund is not tied to any previous purchases.

Request

Input Field Name Req? Description

ssl_transaction_type Y Cash Return or Cash Credit (cashcredit). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin ssl_amount ssl_salestax

Converge PIN as configured within Converge, case sensitive.

Transaction Amount to be refunded. Number with 2 decimal places. This amount includes the Net amount and Sales Tax.

Recommended for purchasing cards.

Sales tax amount applied to this transaction in decimal. Tax exempt transactions can pass 0.00 to properly reflect a tax exempt transaction.

Response

Output Field Name

ssl_result

Description

Outcome of a transaction. A response that contains ssl_result of 0 represents an approved transaction. A response containing any other value for ssl_result represents a declined transaction preventing it from being authorized. ssl_result_message Transaction result message. Example: APPROVAL. ssl_txn_id ssl_txn_time ssl_amount errorCode

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM.

The total transaction authorized or approved amount.

Error code returned only if an error occurred, typically when the transaction failed validation or the request is incorrect. This will prevent the transaction

section for more information. errorMessage errorName

Detailed explanation of the error returned only if an error occurred. This field may be changed based on Merchant configuration in the user interface.

Refer to the Error Codes section for more information.

Error name or reason for the error returned only if an error occurred. Refer to

Converge Developer Guide: Transaction Format

Example

The following is an XML example request for a $5.00 refund:

Request

<txn>

<ssl_merchant_id>My_Merchant_id</ssl_merchant_id>

<ssl_user_id>My_User</ssl_user_id>

<ssl_pin>XXXXXX</ssl_pin>

<ssl_transaction_type>CASHCREDIT</ssl_transaction_type>

<ssl_amount>5.00</ssl_amount>

<ssl_salestax>0.23</ssl_salestax>

<anotherCustomField>testAnother12</anotherCustomField>

</txn>

<ssl_show_form>false</ssl_show_form>

CON-0002-N

Response

<txn>

<anotherCustomField>testAnother12</anotherCustomField>

<ssl_txn_time>12/18/2013 09:13:24 AM</ssl_txn_time>

<ssl_txn_id>AA786F-4CEC21A7-B70A-4584-AC8C-

5040C0297354</ssl_txn_id>

<ssl_amount>5.00</ssl_amount>

<ssl_result>0</ssl_result>

<ssl_salestax>0.23</ssl_salestax>

<anothercustom>testAnother12</anothercustom>

<ssl_result_message>APPROVAL</ssl_result_message>

</txn>

Converge Developer Guide: Transaction Format CON-0002-N

Batch Import Transactions

This message format is for importing and processing batch files of credit card or recurring or installment transactions.

The ability to import batch files is only possible through processBatch.do through an HTTP

POST using one of the following transaction types:



ccimport

This transaction is used to process a file of Credit Cards transactions.



cctokenimport

This transaction is used to process a file of Credit Card information for token generation.



ccrecimport

This transaction is used to process a file of Credit Card Recurring transactions.

Every batch import HTTP request must include the enctype attribute of multipart/form-data, a properly formatted CSV or XML batch file along with the individual key value pairs formatted file.

The POST request does not support XML formatted data at this time.

Batch files must meet the following criteria:



File must be binary and the extension must be CSV or XML.



Only one file can be imported at any given time for any terminal.



There is a limit of five files per day per terminal.



The same file cannot be imported in the same terminal within a 24-hour period.



There is a limit of 500 transactions per file.



The CSV file must be formatted properly as follows:



The first line in the CSV file will contain a header with elements in lower cases. The elements in the header and what they mean are specified in the table below.



Remaining lines in the CSV file will contain the transaction data. Data for a transaction should be in a single line. Data for each new transaction must be in a new line.



Data that pertains to an element in a transaction will be separated by a comma delimiter.



Order of the values provided must follow the order of fields in the header. If no value is present to accommodate the element in the header, comma and double quotes without a value must be provided as placeholder.

 Use the double quotes to enclose each field and value.

Converge Developer Guide: Transaction Format CON-0002-N

 XML Files must be formatted properly as follows:



XML files must contain the root xml beginning and ending element <txnimport> for

Credit Batch Import or <txnrecimport> for Recurring Batch Import.



Data for each transaction will be nested and embedded between beginning and ending elements <txn>.



A transaction data that resides between beginning <txn> and ending </txn> will contain all needed XML elements and values to process a single transaction for that type of transaction as specified in the table below.



The order of the tags in the XML format is not important.

Credit Card Batch Import (ccimport)

The ccimport is a request that allows you to import and process a batch file of credit card transactions. This request should include the batch file to import in XML or CSV format. Once the file is uploaded, Converge will validate the file and return a response via processBatch.do. This response is simply to indicate if the file upload was successful or not. Transactions in the file will be sent for authorization and are shown in the appropriate batches in the User Interface. The import response files can be viewed and downloaded from the User Interface.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_import_file ssl_response_file ssl_do_merchant_email ssl_merchant_email

Req? Description

Y Credit Card Batch Import (ccimport).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Path and location and the name of the import file. The entire entry can have a maximum size of 255, the file name can only be 30 characters (including the extension) in length, and the extension can only be CSV or XML. The path must be sent along with the file name.

Example: C:\Program

Files\Elavon\Converge\Import\ImportFile.csv.

Response file friendly name, cannot be more than 30 characters and should not contain any of the following characters (\ / : * ? " < > | ).

Determine if the merchant would like an email when the import file is completed, possible values: T to send an email or F not to send.

Merchant's email address, if email is not specified and ssl_do_merchant_email

is set to T then an email will be sent to the terminal email.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_result_format

Req? Description

N Valid values: HTML, XML, ASCII. When set to ASCII Virtual

Merchant will generate a plain text key-value document.

Default is HTML if not sent. ssl_receipt_link_method N ssl_receipt_link_url ssl_error_url

Only valid option is REDG so no receipt is displayed and data redirected to the link defined in request in the ssl_receipt_link_url or terminal settings.

Target of the Redirect link for the batch import results.

Ignored when the ssl_result_format = ASCII and ssl_receipt_link_method

= REDG.

If present, the error will be redirected to the URL specified including the errorCode, errorName and errorMessage fields.

Response

Output Field Name

ssl_result ssl_result_message Batch Import Result message: a result of File upload successful indicates the file was imported successfully. File upload failed indicates the file was not imported successfully. ssl_transaction_type

Transaction type (ccimport). ssl_user_id

Description

Batch Import Result code: a result of 0 indicates the file was successfully imported. A result of 1 indicates that the file import failed. ssl_number_trans ssl_response_file errorCode

Converge User ID.

Number of transactions imported in the import file.

Response file name.

interface. Refer to the Error Codes section for more information.

errorMessage errorName

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user

Error name or reason for the error. Returned only if an error occurred.

Refer to the Error Codes section for more information.

Converge Developer Guide: Transaction Format CON-0002-N

Credit Batch Import File Format

A Credit Batch Import file is a properly formatted CSV or XML batch file of credit card transactions. This file must be uploaded with transaction type ccimport.

The first line in a CSV file is the header which contains the field names in lower case, as outlined in the table where each field in the header is enclosed within double quotes and separated by a comma.

Remaining lines in the file are for transaction data. Each transaction must be in a new line. The data in the transaction line must be placed in the same order as its corresponding field value in the header, enclosed within double quotes and separated by a comma.

The XML file contains one single <txnimport> element and multiple transaction <txn> nested elements, every transaction is a set of XML tags and its corresponding values as shown in the table. The number of <txn> corresponds to the number of transactions in the file. All elements are closed in the order that they were opened.

Notes:



CVV2/CVC/CID values and Track Data should never be stored, and therefore cannot be passed to Converge on the file.



You must provide either the card number ssl_card_number or the token ssl_token from a previously tokenized card number in each record.



A single file can have a mix of tokens and card numbers.

The file must be formatted as follows:

Header Field Name

ssl_card_number ssl_token ssl_exp_date ssl_amount

Req? Length Description

Credit card number.

Use only with a terminal that is setup with

Tokenization.

Credit Card Token, previously generated from a card number. A token can be stored and used as a substitute for a card number.

In MMYY format.

Must be in decimal form, no dollar sign.

Converge Developer Guide: Transaction Format CON-0002-N

Header Field Name Req? Length Description

ssl_transaction_currency N 3 Use only with a terminal that is setup with Multi-

Currency.

currencies are supported. Refer to the ISO

Currency Codes section for an extensive list of

available currencies. ssl_transaction_type Y 20 ssl_customer_code

Available transaction types:

 ccsale

(Sale)

 ccauthonly (Auth Only)

 ccavsonly (AVS Only)

 ccverify (Verification)

 cccredit (Credit)

 ccforce (Force)

Customer code for purchasing card transactions. ssl_salestax ssl_invoice_number ssl_approval_code

Sales tax for purchasing card transactions.

Invoice number.

Required for force transactions. ssl_description ssl_company ssl_first_name ssl_last_name

255

Transaction description.

Customer's company name.

Customer's first name.

Customer's last name. ssl_avs_address ssl_address2 ssl_city

Cardholder’s street address.

Customer's address line 2.

Customer's city. ssl_state ssl_avs_zip ssl_country ssl_phone

Customer's state.

Customer's ZIP code used to process AVS.

Customer's country.

Customer's phone number. ssl_email ssl_ship_to_company ssl_ship_to_first_name ssl_ship_to_last_name ssl_ship_to_address1

100

Customer's email address.

Ship To company name.

Ship To first name.

Ship To last name.

Ship To address line 1.

Converge Developer Guide: Transaction Format CON-0002-N

Header Field Name

ssl_ship_to_address2 ssl_ship_to_city ssl_ship_to_state ssl_ship_to_zip ssl_ship_to_country ssl_ship_to_phone

User Defined Field ssl_get_token

Req? Length Description

N 30 Ship To address line 2.

N 30 Ship To city.

Ship To state.

Ship To ZIP code.

Ship To country.

Ship To phone number.

User defined, user should be able to pass up to

25 user defined fields, the value passed in the file should match the field name specified in the

Terminal Setup | Merchant | Payment Fields |

Add New Field.

Use only with a terminal that is setup with

Tokenization.

Generate Token indicator, used to indicate if you wish to generate a token when passing card data. Valid values: Y (generate a token), N (do not generate token). Defaulted to N.

Once generated, the token number can be stored and used as a substitute for a card number at later time.

Examples

Batch Import Request

This is an example of a credit batch import request. The file contents must be sent in the ssl_import_file

. ssl_merchant_id=my_virtualmerchant_id ssl_user_id=my_user_id ssl_pin=my_pin ssl_transaction_type=ccimport ssl_import_file=C:\Program

Files\Elavon\VirtualMerchant\Import\ImportFile.csv ssl_response_file=ImportFile051410025559 ssl_result_format=HTML ssl_receipt_decl_method=REDG ssl_receipt_decl_get_url=http://www.website.com/decline.asp ssl_receipt_apprvl_method=REDG ssl_receipt_apprvl_get_url=http://www.website.com/approval.asp

Converge Developer Guide: Transaction Format CON-0002-N

Batch Import Response

The application has indicated that the file upload was successful. ssl_response_file=ImportFile051410025559 ssl_transaction_type=ccimport ssl_start_date=05142010073000 ssl_end_date=05142010073200 ssl_number_trans=000100 ssl_user_id= my_User_ID ssl_result=0 ssl_result_message=File Uploaded ssl_recurring_batch_count = 250

This is an example of an error in an attempt to import a file with 900 recurring (processxml.do)

<txn>

<errorName> File Exceeds Max Number of Transactions </errorName>

<errorMessage> File contains more than 500 transactions.<errorMessage>

</txn>

Credit Batch Import File Example CSV

The following example demonstrates a CSV file. The first line is a header, which contains the field names. The contents of this file can be copied and saved in a text document with a CSV extension for testing and can be sent with a ccimport request:

“ssl_card_number”,“ssl_exp_date”,“ssl_amount”,“ssl_transaction_type”,“ssl

_approval_code”,“ssl_description”

“0000000000000000”,”0514”,”5.00”,”ccsale”,””,”My First Sale”

“0000000000000000”,”0515”,”10.00”,”ccforce”,”12345”,”This is a force”

“0000000000000000”,0517”,”12.00”,”ccauthonly”,””,”Just Auth Only for now”

Converge Developer Guide: Transaction Format CON-0002-N

Credit Batch Import File Example XML

The following example demonstrates a properly nested XML file with two transactions. The contents of this file can be copied and saved in a text document with a CSV extension for testing and can be sent with a ccimport request:

<txn>

<ssl_card_number>0000000000000000</ssl_card_number>

<ssl_exp_date>1212</ssl_exp_date>

<ssl_amount>2.00</ssl_amount>

<ssl_transaction_type>ccsale</ssl_transaction_type>

</txn>

<txn>

<ssl_card_number>0000000000000000</ssl_card_number>

<ssl_exp_date>1213</ssl_exp_date>

<ssl_amount>5.00</ssl_amount>

<ssl_transaction_type>CCFORCE</ssl_transaction_type>

<ssl_customer_code> FF1234</ssl_customer_code>

<ssl_salestax>0.50</ssl_salestax>

<ssl_invoice_number>1234</ssl_invoice_number>

<ssl_approval_code>555555</ssl_approval_code>

<ssl_description>test a force</ssl_description>

<ssl_company/>

<ssl_first_name>John</ssl_first_name>

<ssl_last_name>Doe</ssl_last_name>

<ssl_avs_address>123 Main</ssl_avs_address>

<ssl_city>Atlanta</ssl_city>

<ssl_state>GA</ssl_state>

<ssl_avs_zip>30123</ssl_avs_zip>

<ssl_country>USA</ssl_country>

</txn>

</txnimport>

Converge Developer Guide: Transaction Format CON-0002-N

Credit Card Information Batch Import (cctokenimport)

The cctokenimport is a request that allows you to import and process a batch file of card numbers or recurring IDs in order to generate tokens; this is the bulk load of ccgettoken. This request should include the batch file to import in XML or CSV format. Once the file is uploaded,

Converge will validate the file and return a response through ProcessBatch.do. This response is simply to indicate if the file upload was successful or not. Transactions in the file will be sent for tokenization and are shown into the appropriate batches in the User Interface. The import response files can be viewed and downloaded from the User Interface.

This transaction type is supported only when a terminal is setup for tokenization; refer to the

Tokenization section for more information.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_import_file ssl_response_file ssl_do_merchant_email ssl_merchant_email ssl_result_format

Req? Description

Credit Card Information Batch Import (cctokenimport).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Example: C:\Program

Files\Elavon\Converge\Import\ImportFile.csv.

Response file friendly name, cannot be more than 30 characters and should not contain any of the following characters (\ / : * ? " < > | ).

Determine if the merchant would like an email when the import file is completed, possible values: T to send an email or F not to send.

Merchant's email address, if email is not specified and ssl_do_merchant_email is set to T then an email will be sent to the terminal email.

Valid values: HTML, XML, ASCII. When set to ASCII Virtual

Merchant will generate a plain text key-value document.

Default is HTML if not sent.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name Req? Description

ssl_receipt_link_method N Only valid option is REDG so no receipt is displayed and data redirected to the link defined in request in the ssl_receipt_link_url

or terminal settings. ssl_receipt_link_url N ssl_error_url

Target of the Redirect link for the batch import results.

Ignored when the ssl_result_format = ASCII and ssl_receipt_link_method

= REDG.

If present, the error will be redirected to the URL specified including the errorCode, errorName, and errorMessage fields.

Response

Output Field Name

ssl_result

Description

Batch Import Result code: a result of 0 indicates the file was successfully imported. A result of 1 indicates that the file import failed. ssl_result_message Batch Import Result message: a result of File upload successful indicates the file was imported successfully. File upload failed indicates the file was not imported successfully. ssl_user_id ssl_number_trans

Converge User ID.

Number of cards imported in the import file. ssl_response_file Response file name. errorCode errorMessage

Error code returned only if an error occurred. 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. Refer to the Error Codes

section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user interface.

Refer to the Error Codes section for more information.

errorName Error name or reason for the error. Returned only if an error occurred. Refer

numeric field. Refer to the Error Codes section for more

Converge Developer Guide: Transaction Format CON-0002-N

Credit Card Information Batch Import File Format

A Card Numbers Batch Import file is a properly formatted CSV or XML batch file of card numbers or recurring IDs or mix of both. This file must be uploaded with transaction type cctokenimport

The first line in a CSV file is the header which contains the field names and values as outlined in the table. Each field in the header must be enclosed within double quotes and separated by a comma. The remaining lines in the file are for transaction data. Each transaction must be in a newline. The data in the transaction line must be placed in the same order as its corresponding field value in the header, enclosed within double quotes and separated by a comma.

The XML file will contain one single <txnimport> element and multiple transaction <txn> nested elements, every transaction is a set of XML tags and its corresponding values as shown in the table. The number of <txn> corresponds to the number of transactions in the file. All elements are closed in the order that they were opened.

Note: CVV2/CVC/CID values and Track Data should never be stored, therefore cannot be passed to Converge on file.

The file must be formatted as follows:

Header Field Name Req? Length Description

ssl_transaction_type Y 20 ccgettoken

(Generate token) ssl_card_number C 19 ssl_exp_date ssl_recurring_id

Required for hand-keyed transactions.

Credit Card Number as it appears on the credit card.

Required for hand-keyed transactions.

Expiration date as it appears on the credit card.

Format MMYY

Required for recurring or installment transactions.

Account Verify indicator to indicate that account verification is needed prior to generating a token.

Valid values: Y, N.

Recommended with Account Verify indicator, required with Add to Card Manager indicator.

Cardholder’s Street Address

Converge Developer Guide: Transaction Format CON-0002-N

Header Field Name

ssl_avs_zip ssl_add_token ssl_first_name ssl_last_name

Req? Length Description

N 9 Recommended with Account Verify indicator, required with Add to Card Manager indicator.

Customer's ZIP code used to process AVS

N 1

C 20

Use only with a terminal that is setup with

Tokenization.

Add to Card Manager indicator, used to indicate if you wish to store the token generated in Card

Manager. Valid value: Y (add token) , N (do not add token) Defaulted to N

Required with Add to Card Manager indicator.

Cardholder’s first name.

C 20 Required with Add to Card Manager indicator.

Cardholder’s first name.

Examples

Credit Card Information File Example CSV

"ssl_card_number","ssl_transaction_type","ssl_exp_date","ssl_avs_addr ess”,”ssl_avs_zip”,”ssl_verify”,”ssl_add_token”

"0000000000000000","ccgettoken","1215","123 Main",”31307”,”Y”,”Y”

"0000000000000000","ccgettoken","1216","","",”N”

"50000000000000000","ccgettoken","1217","345 Main","99999",”Y”,”Y”

Converge Developer Guide: Transaction Format CON-0002-N

Credit Card Information File Example XML

The following example demonstrates a properly nested XML file with 3 card information. The contents of this file can be copied and saved in a text document with a XML extension for testing and can be sent with cctokenimport request:

<txn>

<ssl_card_number>0000000000000000</ssl_card_number>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_transaction_type>CCGETTOKEN</ssl_transaction_type>

<ssl_avs_address>123 Main</ssl_avs_address>

<ssl_avs_zip>30123</ssl_avs_zip>

<ssl_verify>Y</ssl_verify>

</txn>

<txn>

<ssl_card_number>0000000000000000</ssl_card_number>

<ssl_transaction_type>CCGETTOKEN</ssl_transaction_type>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_verify>N</ssl_verify>

</txn>

<txn>

<ssl_card_number>0000000000000000</ssl_card_number>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_transaction_type>CCGETTOKEN</ssl_transaction_type>

<ssl_verify>Y</ssl_verify>

<ssl_avs_address>123 Main</ssl_avs_address>

<ssl_avs_zip>30123</ssl_avs_zip>

<ssl_add_token>Y</ssl_add_token>

<ssl_first_name>john</ssl_first_name>

<ssl_last_name>Doe</ssl_last_name>

</txn>

</txnimport>

Converge Developer Guide: Transaction Format CON-0002-N

Credit Card Recurring Batch Import (ccrecimport)

The ccrecimport is a request that allows you to import and process a batch file of recurring and installment transactions. This request should include the batch file to import in XML or CSV format. Once the file is uploaded, Converge will validate the file and return a response via processBatch.do

, this response is simply to indicate if the file upload was successful or not.

Transactions in the file will be sent for authorization and are entered into the appropriate batches in the user interface. The import response files can be viewed and downloaded from the user interface.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_import_file ssl_response_file ssl_do_merchant_email ssl_merchant_email ssl_result_format

Req? Description

Y Recurring Batch Import (ccrecimport).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Path, location and name of the import file. The entire entry can have a maximum size of 255. The file name can only be

30 characters (including the extension) in length and the extension can only be CSV or XML. The path must be sent along with the file name.

Example: C:\Program

Files\Elavon\Converge\Import\ImportFile.csv.

Response file friendly name, cannot be more than 30 characters and should not contain any of the following characters (\ / : * ? " < > | ). .

Determine if the merchant would like an email when the import file is completed, possible values: T to send an email or F to not send.

Merchant's Email Address, if email not specified and ssl_do_merchant_email

is set to T then an email will be sent to the terminal email.

Valid values are HTML, XML, and ASCII. When set to ASCII

Virtual Merchant will generate a plain text key-value document. Default is HTML if not sent.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name Req? Description

ssl_receipt_link_method N Only valid option is REDG so no receipt is displayed and data redirected to the link defined in the request in the ssl_receipt_link_url

or terminal settings. ssl_receipt_link_url N ssl_error_url

Target of the redirect link for the batch import results.

Ignored when the ssl_result_format=ASCII and ssl_receipt_link_method

= REDG.

If present, the error will be redirected to the URL specified including the errorCode, and errorName and errorMessage

fields.

Response

Output Field Name

ssl_result ssl_result_message

Description

Batch import result code: a result of 0 indicates the file was successfully imported. A result of 1 indicates that the file import failed.

Batch import result message: a result of File upload successful indicates the file was imported successfully. File upload failed indicates the file was not imported successfully. ssl_transaction_type ssl_user_id

Transaction type (ccrecimport).

Converge User ID. ssl_number_trans Number of transactions imported in the import file. ssl_response_file Response file name. ssl_recurring_batch_count Current recurring transaction number in the recurring batch prior to processing the file. errorCode errorMessage

information.

Detailed explanation of the error returned only if an error occurred.

This field may be changed based on merchant configuration in the

user interface. Refer to the Error Codes section for more

information. errorName Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Converge Developer Guide: Transaction Format CON-0002-N

Recurring Batch Import File Format

A Recurring Batch Import file is a properly formatted CSV or XML batch file of recurring and installment transactions. This file must be uploaded with transaction type ccrecimport.

The first line in a CSV file is the header, which contains the field names and values as outlined in the table. Each field in the header should be enclosed within double quotes and separated by a comma. Remaining lines in the file are for transaction data. Each transaction must be in a new line. The data in the transaction line must be placed in the same order as its corresponding field value in the header, enclosed within double quote, and separated by a comma.

The XML file contains one single <txnrecimport> element and multiple transaction <txn> nested elements. Every transaction is a set of XML tags and its corresponding values as shown in the table. The number of <txn> corresponds to the number of transactions in the file. All elements are closed in the order that they were opened.

Note: CVV2/CVC/CID values and Track Data should never be stored, therefore cannot be passed to Converge on file.

The file must be formatted as follows:

Header Field Name

ssl_card_number ssl_exp_date ssl_amount ssl_transaction_type ssl_billing_cycle ssl_next_payment_date

Req? Length Value

Credit card number.

In MMYY format.

Must be a decimal, no dollar sign.

Available transaction types:

 ccaddrecurring (

Add Recurring)

 ccaddinstall

(Add Installment)

Billing cycle. Valid returned values, all caps and no hyphens:



DAILY

 WEEKLY



BIWEEKLY

 SEMIMONTHLY



MONTHLY

 BIMONTHLY



QUARTERLY

 SEMESTER



SEMIANNUALLY



ANNUALLY



SUSPENDED

Next payment date. Format MM/DD/YYYY.

Converge Developer Guide: Transaction Format CON-0002-N

Header Field Name

ssl_bill_on_half ssl_end_of_month ssl_skip_payment ssl_description ssl_invoice_number ssl_customer_code ssl_salestax ssl_company ssl_first_name ssl_last_name ssl_avs_address ssl_address2 ssl_city ssl_state ssl_avs_zip ssl_country ssl_phone

Req? Length Value

C 1 Half of the month indicator for semi-monthly billing cycles. Valid values are 1 and 2:

 1 = the 1st and the 15th of the month



2 = the 15th and the last day of the month

C 1 End of month indicator. Valid values Y or N



30-Apr

 30-June



30-Sept

 30-Nov



28-Feb (non-leap year)

 29-Feb (leap year)

You also need to provide the end of the month indicator for the annually billing cycles when the start payment date is any of the following dates:

 28-Feb (non-leap year)



29-Feb (leap year)

N 1

255

Skip Payment field.

Valid values: Y for yes or N for no. Defaulted to N.

Transaction description.

Invoice number for MOTO transactions.

Customer code for purchasing card transactions.

Sales tax for purchasing card transactions.

Customer's company name.

Customer's first name.

Customer's last name.

Cardholder’s street address.

Customer's address line two.

Customer's city.

Customer's state.

Customer's ZIP code used to process AVS.

Customer's country.

Customer's phone number.

276

Converge Developer Guide: Transaction Format CON-0002-N

Header Field Name

ssl_email ssl_ship_to_company ssl_ship_to_first_name N ssl_ship_to_last_name N ssl_ship_to_address1 ssl_ship_to_address2

N ssl_ship_to_city ssl_ship_to_state

Req? Length Value

N 100 Customer's email address.

N 50 Ship To company name.

Ship To first name.

Ship To last name.

Ship To address line 1.

Ship To address line 2.

Ship To city.

Ship To state. ssl_ship_to_zip ssl_ship_to_country ssl_ship_to_phone

User Defined Field

Ship To ZIP code.

Ship To country.

Ship To phone number.

User defined, user should be able to pass up to 25 user defined fields, the value passed in the file should match the field name specified in the

Terminal Setup | Merchant | Payment Fields |

Add New Field.

Converge Developer Guide: Transaction Format CON-0002-N

Example

Recurring Batch Import File Example CSV

The following example demonstrates a CSV file. The first line is a header, which contains fields.

The fields in the header as well as the data in each line are delimited by commas, and each value that corresponds to the field header is enclosed within double quote. The content of this file can be copied and saved in a text document with a CSV extension for testing with transaction type ccrecimport

"ssl_card_number","ssl_exp_date","ssl_amount","ssl_transaction_type","ss l_billing_cycle","ssl_next_payment_date","ssl_total_installments","ssl_s kip_payment","ssl_customer_code","ssl_salestax","ssl_invoice_number","ss l_description","ssl_company","ssl_first_name","ssl_last_name","ssl_avs_a ddress","ssl_address2","ssl_city","ssl_state","ssl_avs_zip","ssl_country

","ssl_phone","ssl_email","ssl_ship_to_company","ssl_ship_to_first_name"

,"ssl_ship_to_last_name","ssl_ship_to_address1","ssl_ship_to_address2"," ssl_ship_to_city","ssl_ship_to_state","ssl_ship_to_zip","ssl_ship_to_cou ntry","ssl_ship_to_phone"

"00**********0000","1212","15.00","CCADDRECURRING","WEEKLY","10/21/2012"

,"","N","C1234","1.00","IN123","weekly Sunday","My

Company","Joe","Doe","1234 Main Street","Suite

100","Atlanta","GA","30328","USA","999-999-

9999","[email protected]","","","","","","","","","USA","999-999-9999"

"00**********0000","1225","25.00","CCADDINSTALL","MONTHLY","06/21/

2012","10","Y","C44545","0.00","IN123","Monthly

Mag","","Jane","Doe","1234 Main

Street","","Atlanta","GA","30328","USA","9999999999","anyemail@ema il.com","","","","","","","","","USA","999-999-9999"

Converge Developer Guide: Transaction Format CON-0002-N

Recurring Batch Import File Example XML

The following example demonstrates a properly nested XML file with two recurring transactions.

All elements are closed in the order that they were opened. The root element txnrecimport contains the transaction element, and every transaction element has its own opening and closing

<txn>

tag:

<txn>

<ssl_card_number>00**********0000</ssl_card_number>

<ssl_exp_date>1212</ssl_exp_date>

<ssl_amount>2.00</ssl_amount>

<ssl_transaction_type>ccaddrecurring</ssl_transaction_type>

<ssl_customer_code>CC1234</ssl_customer_code>

<ssl_salestax>0.50</ssl_salestax>

<ssl_invoice_number>1234</ssl_invoice_number>

<ssl_description>test recurring</ssl_description>

<ssl_billing_cycle>MONTHLY</ssl_billing_cycle>

<ssl_next_payment_date>08/20/2012</ssl_next_payment_date>

<ssl_skip_payment>N</ssl_skip_payment>

<ssl_company>MyCompany</ssl_company>

<ssl_first_name>John</ssl_first_name>

<ssl_last_name>Doe</ssl_last_name>

<ssl_avs_address>123 Main</ssl_avs_address>

<ssl_city>Atlanta</ssl_city>

<ssl_state>GA</ssl_state>

<ssl_avs_zip>30123</ssl_avs_zip>

<ssl_country>USA</ssl_country>

</txn>

(continued)

Converge Developer Guide: Transaction Format CON-0002-N

<txn>

<ssl_card_number>00**********0000</ssl_card_number>

<ssl_exp_date>1213</ssl_exp_date>

<ssl_amount>5.00</ssl_amount>

<ssl_transaction_type>ccaddinstall</ssl_transaction_type>

<ssl_customer_code>FF1234</ssl_customer_code>

<ssl_billing_cycle>WEEKLY</ssl_billing_cycle>

<ssl_next_payment_date>08/20/2012</ssl_next_payment_date>

<ssl_total_installments>10</ssl_total_installments>

<ssl_first_name>John</ssl_first_name>

<ssl_last_name>Doe</ssl_last_name>

<ssl_avs_address>123 Main</ssl_avs_address>

<ssl_city>Atlanta</ssl_city>

<ssl_state>GA</ssl_state>

<ssl_avs_zip>30123</ssl_avs_zip>

<ssl_country>USA</ssl_country>

</txn>

</txnrecimport>

(end)

Card Manager Transactions

This message format is for card manager transactions. The card manager stores information associated to a token generated from a credit card.

Notes:



Terminal must be setup for tokenization.



Card Manager transactions are applicable to Credit Card tokens only. Gift Card tokens can be stored in the Card Manager using the user interface only. Gift tokens cannot be added, modified, or deleted using Card Manager transaction types.

Token Query (ccquerytoken)

This request is used to retrieve the information associated to a token. Token must be present in the card manager.

Note: The ssl_show_form property does not apply

Converge Developer Guide: Transaction Format CON-0002-N

Request

Input Field Name Req? Description

ssl_transaction_type Y Token Query (ccquerytoken). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin ssl_token

Converge PIN as configured within Converge, case sensitive.

Use only with a terminal that is setup with Tokenization.

Credit Card Token, previously generated from a card number and stored in the card manager. A token can be stored and used as a substitute for a card number.

Response

Output Field Name Description

ssl_card_type The card type. Available card types: LOYALTY, CASHBENEFIT, CASH,

DEBITCARD, FOODSTAMP, CREDITCARD, GIFTCARD, ELECTRONICCHECK. ssl_token Credit Card Token supplied in the authorization. ssl_card_number Masked card number. ssl_exp_date Expiration date. Returned based on merchant setup. ssl_company Company name. Returned based on merchant setup. ssl_customer_id

Customer ID. Returned based on merchant setup. ssl_first_name Customer’s first name. Returned based on merchant setup. ssl_last_name Customer’s last name. Returned based on merchant setup. ssl_avs_address Customer's address. Returned based on merchant setup. ssl_address2 Customer's address line 2. Returned based on merchant setup. ssl_avs_zip Customer's ZIP code. Returned based on merchant setup. ssl_city ssl_state ssl_country

Customer's city. Returned based on merchant setup.

Customer's state. Returned based on merchant setup.

Customer's country. Returned based on merchant setup. ssl_phone Customer's phone number. Returned based on merchant setup. ssl_email

Customer's email address. Returned based on merchant setup. ssl_description Transaction description. Returned based on merchant setup.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name Description

errorCode Error code returned only if an error occurred. 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. Refer to the Error Codes

section for more information. errorMessage errorName

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user interface. Refer

Error name or reason for the error returned only if an error occurred. Refer to

APPROVAL, DECLINE. Refer to the Authorization Response Codes section for

Token Update (ccupdatetoken)

This request is used to update the information associated to a token. Token must be present in the card manager.

Notes:



Only the information you wish to update along with the token should be sent



If card number is sent, a new token will be generated



Some entries in the card manager can be set to null by sending empty values, first and last names cannot be sent null as they are required



You can verify the account before update, if card is declined the token will not be updated



The ssl_show_form property does not apply

Request

Input Field Name Req? Description

ssl_transaction_type Y Token Update (ccupdatetoken). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin ssl_token

Converge PIN as configured within Converge, case sensitive. ssl_card_number ssl_exp_date

Credit Card Token to be updated

Credit Card Number as it appears on the credit card. ssl_company N

Credit Card Expiry Date as it appears on credit card formatted as

MMYY.

Company name.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_customer_id ssl_first_name ssl_last_name ssl_avs_zip ssl_avs_address ssl_address2 ssl_city ssl_state ssl_country ssl_email ssl_phone ssl_description ssl_verify

Req? Description

N Customer identifier as set by the merchant.

N Cardholder first name.

Cardholder last name.

Cardholder ZIP code.

Cardholder Address.

Customer's address line 2.

Customer's city.

Customer's state.

Customer's country.

Customer's email address.

Customer's phone number. ssl_description

Account Verify indicator to indicate that account verification is needed prior to updating a token. Valid values: Y, N.

Response

Output Field Name

ssl_result

Description

Update Token Result code. A result of 0 indicates that the token was generated; 1 indicates that the token was not generated. Returned only when account verification is requested. ssl_result_message The account verification transaction result message returned only when the token update is requested with Account verification flag. Example:

an extensive list of possible returned messages. Returned only when account verification is requested. ssl_token Credit Card Token supplied in the authorization. ssl_token_response Outcome of the token update. This value will be SUCCESS if a token has been generated. Other possible returned values are FAILURE, Action Not

Permitted, Invalid Token, Not Permitted, Acct Verification Failed. ssl_txn_id ssl_txn_time

Transaction identification number, returned only when an account verification is requested. This is a unique number used to identify the transaction.

Date and time when the transaction was processed, returned only when account verification is requested. Format: MM/DD/YYYY hh:mm:ss PM/AM.

Example: 03/18/2010 10:34:10 AM. ssl_approval_code Transaction approval code. Returned only when account verification is requested.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_avs_response ssl_customer_id

Description

The Address Verification Response Code (refer to the AVS Response Codes

section for a complete list of AVS response codes). Returned only when account verification is requested. ssl_cvv2_response

The Card Verification Response Code (refer to the CVV2/CVC2 Response

Codes section for a complete list of CVV/CVC2 response codes). Returned

only when account verification is requested. ssl_card_number ssl_exp_date

Masked card number.

Expiration date. Returned based on merchant setup. ssl_company Company name. Returned based on merchant setup.

Customer ID. Returned based on merchant setup. ssl_first_name ssl_last_name ssl_avs_address

Customer’s first name. Returned based on merchant setup.

Customer’s last name. Returned based on merchant setup.

Customer's address. Returned based on merchant setup. ssl_address2 ssl_avs_zip ssl_city

Customer's address line 2. Returned based on merchant setup.

Customer's ZIP code. Returned based on merchant setup.

Customer's city. Returned based on merchant setup. ssl_state ssl_country ssl_phone ssl_email ssl_description errorCode errorMessage errorName

Customer's state. Returned based on merchant setup.

Customer's country. Returned based on merchant setup.

Customer's phone number. Returned based on merchant setup.

Customer's email address. Returned based on merchant setup.

Transaction description. Returned based on merchant setup.

Error code returned only if an error occurred. 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. Refer to the Error Codes

section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user interface.

Refer to the Error Codes section for more information.

Error name or reason for the error returned only if an error occurred. Refer to

Token Delete (ccdeletetoken)

This request is used to delete a token from the card manager; all the information associated with that token will be removed.

Note: The ssl_show_form property does not apply.

Converge Developer Guide: Transaction Format CON-0002-N

Request

Input Field Name Req? Description

ssl_transaction_type Y Token Delete (ccdeletetoken). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin ssl_token

Converge PIN as configured within Converge, case sensitive.

Credit Card Token, previously generated from a card number and stored in the card manager. A token can be stored and used as a substitute for a card number.

Response

Output Field Name

ssl_token

Description

The token value deleted from the card manager. ssl_token_response Outcome of the token deletion. This value will be a SUCCESS if a token has been deleted. Other possible returned values are FAILURE, Action Not

Permitted, Invalid Token. errorMessage errorName

Detailed explanation of the error returned ONLY if an error occurred. This field may be changed based on merchant configuration in the user interface. Refer

Error name or reason for the error returned ONLY if an error occurred. Refer to

from going to authorization. This is a numeric field. Refer to the Error Codes

End of Day Transactions

This message format is for End of Day transactions. Those functions consist of resending email/ receipt, searching for a transaction, running a summary report , or settling transactions.

Converge Developer Guide: Transaction Format CON-0002-N

Transaction Email (txnemail)

The txnemail is used to initiate or resend an email to the merchant or customer for a specific transaction. Optionally, the request can include a new customer email address if different from the original transaction or if the original transaction did not have an email address.

Notes:

 The ssl_show_form property does not apply for these transactions.

 An error is sent if the terminal is not setup for emails.

 If the original transaction contains a customer email, both merchant and customer emails will be sent, specific flags can be sent to control if the email should be sent to only the customer or only to the merchant.

 A flag can be sent to update the email address on file with the new one sent with the email request. The terminal must be setup to receive email.

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_pin ssl_user_id ssl_txn_id ssl_email

Req? Description

Y Transaction Email (txnemail).

Converge ID as provided by Elavon.

Converge PIN as configured within Converge, case sensitive.

Converge User ID as configured on Converge, case sensitive.

Unique identifier returned on the original transaction.

Customer’s email address. Send this value if the existing transaction did not have a customer email or if the email needs to be sent to a different email address. If value not sent the system will attempt to send an email to the email address stored from the original transaction

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_update_email

Req? Description

N Email update flag indicated if email needs to be updated after the email is resent. The new customer email must be sent in the ssl_email

field. Valid values: Y or N. Default is N. ssl_do_customer_email N Indicates if email needs to be sent to the customer, if not passed and customer email is present in the original transaction, it will be defaulted to True.

Valid values are:



T = True



F = False ssl_do_merchant_email N Indicates if email needs to be sent to the merchant, if not passed defaulted to True. Valid values are:

 T = True



F = False

Response

Output Field Name Description

ssl_result Outcome of a transaction. A response that contains ssl_result of 0 represents an Approved transaction. A response containing any other value for ssl_result represents a Declined transaction preventing it from being authorized. ssl_result_message Transaction result message. Example: SUCCESS. ssl_txn_id ssl_txn_time

Transaction identification number. This is a unique number used to identify the transaction.

Date and time when the transaction was processed, Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 A.M. errorCode errorMessage

Error code returned only if an error occurred. Typically, when the transaction failed validation or the request is incorrect. This will prevent the transaction

section for more information.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user interface.

Refer to the Error Codes section for more information.

errorName Error name or reason for the error returned only if an error occurred. Refer to

APPROVAL. Refer to the Authorization Response Codes section for

Converge Developer Guide: Transaction Format CON-0002-N

Transaction Query (txnquery)

This request is used to search for a transaction based on a date range or card data or combination of both. One of the following fields must be provided:



Card information providing one of the following fields:

 ssl_card_number

 ssl_track_data

 ssl_card_suffix

And/Or

 Date range ssl_search_start_date and ssl_search_end_date

 Transaction identifier ssl_txn_id

1. When searching based on the transaction identifier:

 The result will contain one single unique transaction



The signature can be included by adding the signature indicator in the ssl_include_signature field, valid value: true.

2. When searching based on card information and/or card range:



Date range cannot exceed 31 days at the time in a single request. For example you can run a query to run transactions from 01/01/2014 to 01/02/2014



One date at minimum must be provided.



If you submit a start date without an end date, the end date will be set to start date plus

31 days (not the current date). If you submit an end date without a start date, the start date will be set to end date minus 31 days.



The result can only have a limit up to 1000 unique transactions at one time; if there is more than 1000 transactions, Converge will return the timestamp of the last transaction in the next set in the field ssl_next_txn_time, the application then must send consecutive requests with the new time stamps in order to get next data in the set of data.



The result will always include the number of transactions in the ssl_txn_count field and the detailed response of each transaction when more than a single transaction is returned.



The detail response will contain the original response along with a transaction status in the ssl_trans_status field to indicate if the transaction status (opened, settled, pending, and so on). All types of transactions for all payment types, approved or declined within the provided date range will be returned and will be listed in descending date/time order

(the latest transaction processed showing first).

3. When searching based on card information and/or card range, you may provide additional information to narrow your search using the following fields:

Converge Developer Guide: Transaction Format CON-0002-N

 The first name in the ssl_search_first_name field



The last name in the ssl_search_last_name field



The description in the ssl_search_description field



The description in the ssl_search_transaction_type field, examples of valid values: VOID,

SALE, FORCE



The Transaction minimum amount in the ssl_search_min_amount, this amount has to be decimal and less or equal then the max amount



The Transaction maximum amount in the ssl_search_max_amount, this amount has to be decimal and greater than the minimum amount



The transaction type in the ssl_search_card_type field, examples of valid values:

CREDITCARD, DEBITCARD, GIFTCARD, LOYALTY, FOODSTAMP, CASH



The card description in the ssl_search_card_short_description field, examples of valid values: VISA, MC, AMEX, CUP



The taxed transactions indicator in the ssl_search_taxed field, values are true or false, results will have those transactions with sales tax value higher than 0.00 (ssl_salestax >

0.00)



The tip indicator in the ssl_search_tipped field, values are true or false, results will have those transactions with tip higher than 0.00 (ssl_tip_amount > 0.00)

Notes:



Search is allowed using one single card information or a date range or combination of both. Passing multiple card information data in a single request is not allowed.

 When searching based on a card number, track data or a card suffix, the search will return a list of all matching transactions within the last two months from the Open and Settled batches.

 When searching based on combination of card information and date range, the search will return a list of all matching transactions within the specified date range from the

Open and Settled batches.



All transactions are listed in descending date/time order.

 The ssl_show_form property does not apply.

Converge Developer Guide: Transaction Format

Request

Input Field Name

ssl_transaction_type ssl_merchant_id ssl_user_id ssl_pin ssl_txn_id ssl_card_number ssl_track_data ssl_card_suffix ssl_search_start_date ssl_search_end_date ssl_search_first_name ssl_search_last_name ssl_search_description

CON-0002-N

Req? Description

Y Transaction Query (txnquery).

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Unique identifier returned on the original transaction.

Credit Card Number as it appears on the credit card.

The raw track I and/or II data from the magnetic strip on the card.

The last 4 digits of the card number.

Start date of the search window. Format

MM/DD/YYYY or MM/DD/YYYY hh:mm:ss AM or

MM/DD/YYYY hh:mm:ss PM. Example:

04/28/2015 08:00:34 AM, 04/28/2015

End date of the search window. Format

MM/DD/YYYY or MM/DD/YYYY hh:mm:ss AM or

MM/DD/YYYY hh:mm:ss PM. Example:

04/29/2015 11:59:59 PM

First name sent on the original transaction. Valid only when searching based on card information and/or date range. Results will contain all transactions with first name ssl_first_name matching this value.

Last name sent on the original transaction. Valid only when searching based on card information and/or date range. Results will contain all transactions with last name ssl_last_name matching this value.

Description sent on the original transaction.

Valid only when searching based on card information and/or date range. Results will contain all transactions with description ssl_description matching this value.

Converge Developer Guide: Transaction Format CON-0002-N

Input Field Name

ssl_search_transaction_type ssl_search_min_amount ssl_search_max_amount ssl_search_card_type ssl_search_card_short_description N ssl_search_taxed

Req? Description

N Transaction type. Valid only when searching based on card information and/or date range.

Results will contain all transactions with transaction ssl_transaction_type matching this value. Examples of valid values are: VOID, SALE,

FORCE, AUTHONLY, AVSONLY, PURCHASE, SALE,

RETURN, FORCEPURCHASE, FORCERETURN,

INQUIRY, REDEMPTION, CREDIT, ACTIVATION

Transaction minimum amount. Decimal. Results will contain all transactions greater than or equal this value.

Transaction maximum amount. Decimal. Valid only when searching based on card information and/or date range. Results will contain all transactions less than or equal this value.

Transaction type, valid only when searching based on card information and/or date range.

Valid values are CREDITCARD, DEBITCARD,

GIFTCARD, LOYALTY, FOODSTAMP, CASH.

Card description, valid only when searching based on card information and/or date range.

Examples of valid values: VISA, MC, AMEX, CUP

Taxed transactions indicator, valid only when searching based on card information and/or date range. Valid values are true or false, results will have those transactions with sales tax value higher than 0.00 (ssl_salestax > 0.00) ssl_search_tipped ssl_include_signature

Tip indicator, valid only when searching based on card information and/or date range. Valid values are true or false, results will have those transactions with tip higher than 0.00

(ssl_tip_amount > 0.00)

Signature indicator, valid only when searching based on transaction ID. Valid values are true or false, results will have those transactions signature.

Converge Developer Guide: Transaction Format CON-0002-N

Response

Output Field Name

ssl_txn_count ssl_next_txn_time ssl_result_message ssl_txn_id ssl_user_id ssl_trans_status ssl_card_type ssl_transaction_type ssl_txn_time ssl_first_name ssl_last_name ssl_card_number ssl_entry_mode ssl_avs_response ssl_cvv2_response ssl_approval_code

Description

The number of transactions matching the search query up to 1000 transactions.

The timestamp of the transaction in the next set when the transaction number in the batches exceeds 1000. This time can be used for the next call to request the next available set of 1000.

Transaction result message. Example: APPROVAL, PARTIAL

an extensive list of possible returned messages.

Transaction identification number. This is a unique number used to identify the transaction. This value can be used to complete the

Auth Only transaction.

Converge User ID that processed the transaction.

Transaction status, example: STL (Settled).

The valid values are:

 PEN = Pended



OPN = Unpended, Released, Open

 REV = Review



STL = Settled



PST = Failed Due to Post-Auth Rule



FPR = Failed Due to Fraud Prevention Rules



PRE = Failed Due to Pre-Auth Rule

The card type. Available card types: LOYALTY, CASHBENEFIT, CASH,

DEBITCARD, FOODSTAMP, CREDITCARD, GIFTCARD,

ELECTRONICCHECK.

Transaction type, example: SALE.

Date and time when the transaction was processed. Format:

MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10

AM.

Cardholder’s first name.

Cardholder’s last name.

Masked card number.

The entry mode of the transaction, K for keyed or S for swiped.

The Address Verification Response Code (refer to the AVS

Response Codes section for a complete list of AVS response codes).

The Card Verification Response Code (refer to the CVV2/CVC2

Response Codes section for a complete list of CVV/CVC2 response

codes).

Transaction approval code.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_amount ssl_invoice_number ssl_city ssl_country

Description

Transaction authorized or approved amount. Returned based on merchant setup.

The invoice or ticket number sent originally on the request.

Returned based on merchant setup. ssl_card_short_description Card description. Returned when searching based on card information and/or date range. ssl_salestax Sales tax. ssl_description ssl_tip_amount

Description.

Tip amount. Returned when searching based on card information and/or date range. ssl_avs_address ssl_address2 ssl_address3

Returned when searching based on Transaction identifier only.

Returned when searching based on Transaction identifier only. ssl_company Returned when searching based on Transaction identifier only.

Returned when searching based on Transaction identifier only.

Returned when searching based on Transaction identifier only. ssl_state ssl_avs_zip ssl_cardholder_currency ssl_terminal_currency ssl_cardholder_amount ssl_tip_amount ssl_cardholder_tip_amount Returned when searching based on Transaction identifier only. ssl_is_voidable ssl_account_balance

Returned when searching based on Transaction identifier only.

Returned when searching based on Transaction identifier only. ssl_departure_Date ssl_completion_Date

Returned when searching based on Transaction identifier only.

Returned when searching based on Transaction identifier only. ssl_ship_to_address1 ssl_ship_to_address2 ssl_ship_to_address3

Returned when searching based on Transaction identifier only.

Returned when searching based on Transaction identifier only. ssl_ship_to_first_name

Returned when searching based on Transaction identifier only.

Returned when searching based on Transaction identifier only. ssl_ship_to_last_name ssl_ship_to_company ssl_ship_to_city

Returned when searching based on Transaction identifier only.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_ship_to_country ssl_ship_to_state ssl_ship_to_zip ssl_signature_image ssl_signature_type errorCode errorMessage errorName

Description

Returned when searching based on Transaction identifier only.

Signature image, returned only when the signature indicator has been provided in the request when searching based on transaction identifier.

Signature type, returned only when the signature indicator has been provided in the request when searching based on transaction identifier. Possible returned values are: GIF , TIF , JPG, PNG

numeric field. Refer to the Error Codes section for more

information.

Detailed explanation of the error returned only if an error occurred.

This field may be changed based on merchant configuration in the

user interface. Refer to the Error Codes section for more

information.

Error name or reason for the error returned only if an error

occurred. Refer to the Error Codes section for more information.

Converge Developer Guide: Transaction Format CON-0002-N

Examples

Query Based on Transaction ID Request xmldata=<txn><ssl_merchant_id>my_virtualmerchant_id</ssl_merchant_id>

<ssl_user_id>my_user</ssl_user_id><ssl_pin>my_pin</ssl_pin>

<ssl_test_mode>false</ssl_test_mode><ssl_transaction_type>txnquery</s sl_transaction_type><ssl_txn_id>AA48439-65E7D601-5E31-4809-882A-

2028CBC3A979</ssl_txn_id></txn>

Query Based on Date Range Request xmldata=<txn><ssl_merchant_id>my_virtualmerchant_id</ssl_merchant_id>

<ssl_user_id>my_user</ssl_user_id><ssl_pin>my_pin</ssl_pin>

<ssl_search_start_date>04/30/2015 09:34:36 AM</ssl_search_start_date>

<ssl_search_end_date></ssl_search_end_date></txn>

Query Based on Card Number Request xmldata=<txn><ssl_merchant_id>my_virtualmerchant_id</ssl_merchant_id>

<ssl_user_id>my_user</ssl_user_id><ssl_pin>my_pin</ssl_pin>

<ssl_test_mode>false</ssl_test_mode><ssl_transaction_type>txnquery</s sl_transaction_type><ssl_card_number>[Full Card number]</ssl_card_number></txn>

Query Based on Track data Request xmldata=<txn><ssl_merchant_id>my_virtualmerchant_id</ssl_merchant_id>

<ssl_user_id>my_user</ssl_user_id><ssl_pin>my_pin</ssl_pin>

<ssl_test_mode>false</ssl_test_mode><ssl_transaction_type> txnquery</ssl_transaction_type><ssl_track_data>[Track data]

</ssl_track_data></txn>

Converge Developer Guide: Transaction Format CON-0002-N

Query Based on Last 4 digit of a Card Number Request xmldata=<txn><ssl_merchant_id>my_virtualmerchant_id</ssl_merchant_id>

<ssl_user_id>my_user</ssl_user_id><ssl_pin>my_pin</ssl_pin>

<ssl_test_mode>false</ssl_test_mode><ssl_transaction_type>txnquery</s sl_transaction_type><ssl_card_suffix>3003</ssl_card_suffix></txn>

Query Response

This is an XML response of a query based on a transaction identifier:

<txn>

<ssl_txn_id>AA7757-2C7226AA-C2A2-45E4-BB5F-

1EC12309D9C3</ssl_txn_id>

<ssl_user_id>my_user</ssl_user_id>

<ssl_trans_status>STL</ssl_trans_status>

<ssl_card_type>CREDITCARD</ssl_card_type>

<ssl_transaction_type>SALE</ssl_transaction_type>

<ssl_txn_time>07/09/2013 02:29:13 PM</ssl_txn_time>

<ssl_first_name>John</ssl_first_name>

<ssl_last_name>Doe</ssl_last_name>

<ssl_card_number>00**********0000</ssl_card_number>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_entry_mode>K</ssl_entry_mode>

<ssl_avs_response />

<ssl_cvv2_response />

<ssl_amount>.37</ssl_amount>

<ssl_invoice_number />

<ssl_result_message>APPROVAL</ssl_result_message>

<ssl_approval_code>N29032</ssl_approval_code>

</txn>

Converge Developer Guide: Transaction Format

This is an ASCII response of a query based on a transaction identifier: ssl_txn_id=AA7757-2C7226AA-C2A2-45E4-BB5F-1EC12309D9C3 ssl_user_id=my_user ssl_trans_status=STL ssl_card_type=CREDITCARD ssl_transaction_type=SALE ssl_txn_time=07/09/2013 02:29:13 PM ssl_first_name=John ssl_last_name=Doe ssl_card_number=00**********0000 ssl_exp_date=1215 ssl_entry_mode=K ssl_avs_response= ssl_cvv2_response= ssl_amount=.37 ssl_invoice_number= ssl_result_message=APPROVAL ssl_approval_code=N29032

CON-0002-N

Converge Developer Guide: Transaction Format CON-0002-N

This is an XML response of a query based on a card number. In this example 2 transactions were returned:

<ssl_txn_count>2</ssl_txn_count>

<txn>

<ssl_txn_id>AA7757-EBB7E0B1-CA25-45FF-9728-

5D45BC222D9A</ssl_txn_id>

<ssl_user_id>my_user</ssl_user_id>

<ssl_trans_status>OPN</ssl_trans_status>

<ssl_card_type>CREDITCARD</ssl_card_type>

<ssl_transaction_type>AVSonly</ssl_transaction_type>

<ssl_txn_time>06/04/2013 10:12:49 AM</ssl_txn_time>

<ssl_first_name />

<ssl_last_name />

<ssl_card_number>00**********0000</ssl_card_number>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_entry_mode>K</ssl_entry_mode>

<ssl_avs_response>G</ssl_avs_response>

<ssl_cvv2_response />

<ssl_amount>0</ssl_amount>

<ssl_invoice_number />

<ssl_result_message>APPROVAL</ssl_result_message>

<ssl_approval_code>031719</ssl_approval_code>

</txn>

<txn>

<ssl_txn_id>AA7757-05E853A6-8DB6-4A0B-B907-

C5E96829CAC6</ssl_txn_id>

<ssl_user_id>my_user</ssl_user_id>

<ssl_trans_status>OPN</ssl_trans_status>

<ssl_card_type>CREDITCARD</ssl_card_type>

<ssl_transaction_type>AVSonly</ssl_transaction_type>

<ssl_txn_time>06/04/2013 10:12:28 AM</ssl_txn_time>

<ssl_first_name />

<ssl_last_name />

<ssl_card_number>00**********0000</ssl_card_number>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_entry_mode>K</ssl_entry_mode>

<ssl_avs_response>G</ssl_avs_response>

<ssl_cvv2_response />

<ssl_amount>0</ssl_amount>

<ssl_invoice_number />

<ssl_result_message>APPROVAL</ssl_result_message>

<ssl_approval_code>031719</ssl_approval_code>

</txn>

</txnlist>

Converge Developer Guide: Transaction Format CON-0002-N

This is an ASCII response of a query based on a card number. In this example two transactions were returned: ssl_txn_count=2 ssl_txn_id=AA7757-EBB7E0B1-CA25-45FF-9728-5D45BC222D9A ssl_user_id=my_user ssl_trans_status=OPN ssl_card_type=CREDITCARD ssl_transaction_type=AVSonly ssl_txn_time=06/04/2013 10:12:49 AM ssl_first_name= Jane ssl_last_name= Doe ssl_card_number=00**********0000 ssl_exp_date=1215 ssl_entry_mode=K ssl_avs_response=G ssl_cvv2_response= M ssl_amount=0.00 ssl_invoice_number= ssl_result_message=APPROVAL ssl_approval_code=031719 ssl_txn_id=AA7757-05E853A6-8DB6-4A0B-B907-C5E96829CAC6 ssl_user_id=my_user ssl_trans_status=OPN ssl_card_type=CREDITCARD ssl_transaction_type=AVSonly ssl_txn_time=06/04/2013 10:12:28 AM ssl_first_name=John ssl_last_name=Doe ssl_card_number=00**********0000 ssl_exp_date=1215 ssl_entry_mode=K ssl_avs_response=G ssl_cvv2_response= ssl_amount=0 ssl_invoice_number= ssl_result_message=APPROVAL ssl_approval_code=031719

Converge Developer Guide: Transaction Format CON-0002-N

Total/ Summary (total)

This request is used to obtain a summary of all transactions waiting to be settled. This will allow the merchant to review the batch prior to settlement.

Batch submissions are posted using process.do for key value pairs formatted request or processxml.do

for XML formatted request.

Notes:



Users must have the Batches-View Transactions user right in order to request a summary



The Empty batch response indicates that there is no transactions in the current batches waiting to be settled



The total request will not return those transactions that are pended or set to review or

Auth only transactions

Request

Input Field Name Req? Description

ssl_transaction_type Y

Total/Summary transaction (total). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin Y Converge PIN as configured within Converge, case sensitive.

Response

Output Field Name

ssl_result ssl_result_message

Description

Outcome of a transaction. A response that contains ssl_result of 0 represents a successful batch submission transaction. A response containing any other value for ssl_result represents a failure preventing it from being settled, example: Empty batch, settlement in progress.

Transaction result message. Example: SUCCESS, Empty batch ssl_txn_main_count ssl_txn_main_amount

Total Transaction count in Main batch

Total Transaction amount in Main batch ssl_txn_cash_count ssl_txn_cash_amount

Total cash count in the cash batch

Total cash amount in the cash batch ssl_txn_loyalty_count Total loyalty card count in the loyalty batch ssl_txn_loyalty_amount Total loyalty amount in the loyalty batch ssl_txn_ecg_count

Total gift card count in the gift batch

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

ssl_txn_ecg_amount errorCode errorName errorMessage

Description

Total gift card amount in the gift batch

Refer to the Error Codes section for more information.

Error name or reason for the error returned only if an error occurred.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user

interface. Refer to the Error Codes section for more information.

Examples

Example 1: process.do

The following XML code example demonstrates the initiation of a total transaction request:

Batch Settlement Request xmldata=<txn><ssl_merchant_id>my_virtualmerchant_id</ssl_merchant_id>

<ssl_user_id>my_user</ssl_user_id><ssl_pin>my_pin</ssl_pin>

<ssl_test_mode>false</ssl_test_mode><ssl_transaction_type>total

</ssl_transaction_type></txn>

Total Response

<txn>

<ssl_result>0</ssl_result>

<ssl_result_message>SUCCESS</ssl_result_message>

<ssl_txn_main_count>10</ssl_txn_main_count>

<ssl_txn_main_amount>220.00</ssl_txn_main_amount>

<ssl_txn_ecg_count>2</ssl_txn_ecg_count>

<ssl_txn_ecg_amount>50.00</ssl_txn_ecg_amount>

</txn>

Converge Developer Guide: Transaction Format CON-0002-N

Settle (settle)

This request is used to initiate a manual settlement on a single, multiple or batch of transactions.

Once the batch is successfully settled, the funds will be moved from the customer's account to the merchant account.

Open batches must be reviewed prior to settlement for accuracy; transactions set to pend or to review must be released prior to settlement. You may opt to set the terminal for auto-settlement or submit a manual settlement from the integrated application. Elavon highly recommends that batches be closed out on a daily basis.

Batch submissions are posted using process.do for key value pairs formatted request or processxml.do

for XML formatted request, the following options are supported:



To settle a single credit card transaction, the settlement request must include the transaction identification number in the ssl_txn_id field.



To settle multiple transactions, the XML request must contain all the transaction identification numbers in the <ssl_txn_id> fields nested within one single

element. The number of <ssl_txn_id> inside the group corresponds to the number of transactions you want to settle.



To settle all transactions in the batch, omit the transaction identifier values.

Notes:



When settling transactions, the ssl_show_form property does not apply.

 Card number or track data should not be sent

 Users must have the Batches-Settle Transactions user right in order to settle transactions

 The Scheduled for Settlement response indicates that the batch will be submitted for settlement. In order to check the status of a transaction, the integrated application may use the transaction query to obtain information on the status of a transaction



The settlement can be initiated on open transactions only. Transactions that are pended or set to review must be released or set to unpend in order to settle.



Settling a single gift or cash transaction is not supported, the gift or cash batch must be settled entirely.



Settings are available within the Admin portion of the Virtual Terminal that can block transactions from being added to a current open batch, if they do not meet certain qualifications. Elavon recommends that merchants review these settings prior to accepting transactions.



Manual settlement is not allowed for those terminals setup for Multi-Currency.

Converge Developer Guide: Transaction Format CON-0002-N

Request

Input Field Name Req? Description

ssl_transaction_type Y Settle transaction (settle). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin ssl_txn_id

Converge PIN as configured within Converge, case sensitive.

Unique identifier returned on the original transaction.

Response

Output Field Name

ssl_result ssl_result_message ssl_txn_time ssl_txn_id ssl_txn_main_count

Description

Transaction result message. Example: Scheduled for settlement, Empty batch, and settlement in progress.

Date and time when the batch was submitted, Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM.

Unique identifier returned on the original transaction, this is to settle an individual transaction sent in the request.

Total Transaction count in Main Batch to be settled. ssl_txn_main_amount Total Transaction amount in Main Batch to be settled. ssl_txn_loyalty_count

Total loyalty card count in the loyalty batch to be settled. ssl_txn_loyalty_amount Total loyalty amount in the loyalty batch to be settled. ssl_txn_cash_count ssl_txn_cash_amount ssl_txn_ecg_count ssl_txn_ecg_amount

Total cash count to be settled.

Total cash amount to be settled.

Total gift card count to be settled.

Total gift card amount to be settled. errorCode errorName errorMessage

Refer to the Error Codes section for more information.

Error name or reason for the error returned only if an error occurred.

Detailed explanation of the error returned only if an error occurred. This field may be changed based on merchant configuration in the user

interface. Refer to the Error Codes section for more information.

Converge Developer Guide: Transaction Format CON-0002-N

Examples

Example 1: process.do

The following XML code example demonstrates the initiation of a settlement transaction request and response for batch and single transaction settlement.

Batch Settlement Request xmldata=<txn><ssl_merchant_id>my_virtualmerchant_id</ssl_merchant_id>

<ssl_user_id>my_user</ssl_user_id><ssl_pin>my_pin</ssl_pin>

<ssl_test_mode>false</ssl_test_mode><ssl_transaction_type>settle

</ssl_transaction_type></txn>

Transaction Settlement Request xmldata=<txn><ssl_merchant_id>my_virtualmerchant_id</ssl_merchant_id>

<ssl_user_id>my_user</ssl_user_id><ssl_pin>my_pin</ssl_pin>

<ssl_test_mode>false</ssl_test_mode><ssl_transaction_type>settle

</ssl_transaction_type><ssl_txn_id>AA48439-65E7D601-5E31-4809-882A-

2028CBC3A979</ssl_txn_id></txn>

Batch Settlement Response

This is a successful attempt for settlement of a batch:

<txn>

<ssl_result>0</ssl_result>

<ssl_result_message>Scheduled for Settlement</ssl_result_message>

<ssl_txn_id/>

<ssl_txn_main_count>10</ssl_txn_main_count>

<ssl_txn_main_amount>220.00</ssl_txn_main_amount>

<ssl_txn_ecg_count>2</ssl_txn_ecg_count>

<ssl_txn_ecg_amount>50.00</ssl_txn_ecg_amount>

</txn>

Converge Developer Guide: Transaction Format CON-0002-N

This is a request of a settlement on a terminal that is not active (Not live):

<txn>

<ssl_result>0</ssl_result>

<ssl_result_message>Scheduled for Settlement</ssl_result_message>

<ssl_txn_id/>

<ssl_txn_main_count>999</ssl_txn_main_count>

<ssl_txn_main_amount>0.00</ssl_txn_main_amount>

<ssl_txn_ecg_count>999</ssl_txn_ecg_count>

<ssl_txn_ecg_amount>0.00</ssl_txn_ecg_amount>

</txn>

Transaction Settlement Response

This is a successful attempt for settlement of a single transaction:

<txn>

<ssl_result>0</ssl_result>

<ssl_result_message>Scheduled for Settlement</ssl_result_message>

<ssl_txn_id>AA48439-65E7D601-5E31-4809-882A-

2028CBC3A979</ssl_txn_id>

<ssl_txn_main_count>1</ssl_txn_main_count>

<ssl_txn_main_amount>16.00</ssl_txn_main_amount>

<ssl_txn_ecg_count>0</ssl_txn_ecg_count>

<ssl_txn_ecg_amount/>

</txn>

This is a successful attempt for settlement for a single transaction on a terminal that is not active

(Not live):

<txn>

<ssl_result>0</ssl_result>

<ssl_result_message>Scheduled for Settlement</ssl_result_message>

<ssl_txn_id>00000000-0000-0000-0000-00000000000</ssl_txn_id>

<ssl_txn_main_count>1</ssl_txn_main_count>

<ssl_txn_main_amount>0.00</ssl_txn_main_amount>

<ssl_txn_ecg_count>0</ssl_txn_ecg_count>

<ssl_txn_ecg_amount>0.00</ssl_txn_ecg_amount>

</txn>

Converge Developer Guide: Transaction Format CON-0002-N

Account Admin Transactions

This message format is for Admin transactions. Those types of transactions use XML and send the transaction to accountxml.do to retrieve the terminal account information.

Terminal Setup (terminalsetup)

This request is used to retrieve the terminal and merchant setup information located under

Terminal | Merchant | Main option and Terminal | Merchant | Terminal option in the user interface terminal menu. The response contains the <MerchantInformation> element which has the merchant information and the <TerminalInformation> element which has the terminal information.

Request

Input Field Name Req? Description

ssl_transaction_type Y Terminal Setup Information (terminalsetup). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin Y Converge PIN as configured within Converge, case sensitive.

Response

Output Field Name Description

MerchantInformation Contains the Merchant Information Elements as described in the table below.

TerminalInformation Contains the Terminal Information Elements as described table below.

Merchant Information Elements

Output Field Name Description

MerchantName

Address1

Merchant’s information as setup in Elavon

Merchant’s Street Address

Address2

City

Merchant’s Street Address Line 2

Merchant’s City

StateProvince

PostalCode

ContactName

ContactPhone1

ContactPhone2

Merchant’s State or Province

Merchant’s Zip Code

Merchant’s contact name

Merchant’s phone number

Merchant’s alternative phone number

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name Description

ContactEmail Merchant’s Email address

TerminalEmail Terminal Email address

SMSEmail

MerchantURL

Merchant’s Email

Merchant’s URL Address

Terminal Information Elements

Output Field Name

vm_friendly_name vm_region vm_time_zone vm_currency vm_market_segment vm_status vm_processing_type vm_payment_types vm_credit_option vm_recurring_option vm_debit_option

Description

Merchant’s information as setup in Elavon.

Merchant’s region of business, for example, USA or Canada.

Merchant ’s time zone, for example, EST.

Merchant’s currency, for example, USD.

Merchant’s market segment, for example, Retail.

The terminal Status. Example: ACTIVE, NOT LIVE, SUSPENDED

An active terminal can process transactions.

Terminal based only.

Contains the payment type elements and values as outlined in the payment type elements table below.

Contains the credit option elements and values as outlined in the credit option elements table below.

Contains the default recurring option elements and values as outlined below.

Output Field Name Description

Frequency Billing cycle, example: MONTHLY

Payments Payment number, example: 12

Contains the debit option elements and values as outlined below.

Output Field Name Description

Surcharge If surcharge is setup for this terminal,

Valid values: Y, N

SurchargeAmount Surcharge amount. Example: 1.00

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

vm_echeck_option

Description

Contains the check option elements and values as outlined below.

Output Field Name Description

CheckType Check type, valid values: ACHECHECK,

PAPERCHECK

TransactionType Check transaction option, example:

VERIFICATION

Image-upload option for Paper check. ImageUploadOption

Recurring If ACH recurring is setup for this terminal, valid values: Y, N vm_transaction_entry

Contains the API option elements and values as outlined below.

Output Field Name Description

EnableHTTPSTransaction If API is enabled. Y, N

EnableHTTPSBatch

EnableVMM

If batch import API is enabled. Y, N

If VM Mobile is enabled. Y, N vm_tokenization Tokenization flag to indicate if the terminal is setup for tokenization. Valid values are Y for Yes or N for No.

Payment type Elements

Output Field Name Description

AVS

Indicates if Address Verification is setup for this terminal. Valid values: Y or N

CVN Indicates if Card Verification is setup for this terminal. Valid values: Y or N

PurchaseCard

InvoiceNumber

DCC

MCC

Indicates if Purchase Card is setup for this terminal. Valid values: Y or N

Indicates if Invoice Number is setup for this terminal. Valid values: Y or N

Indicates if Dynamic Currency is setup for this terminal. Valid values: Y or N

Indicates if Multi-Currency is setup for this terminal. Valid values: Y or N

Recurring

Last4digits

Indicates if Recurring is setup for this terminal. Valid values: Y or N

Indicates if Last 4 Digits is setup for this terminal. Valid values: Y or N

TravelData Indicates if Travel Data is setup for this terminal. Valid values: Y or N

AccountUpdater Indicates if Account Updater is setup for this terminal. Valid values: Y or N

Converge Developer Guide: Transaction Format CON-0002-N

Credit Option Elements

Output Field Name Description

Credit Indicates if credit is setup for this terminal. Valid values: Y or N

Debit

Gift

ECheck

Indicates if debit is setup for this terminal. Valid values: Y or N

Indicates if gift is setup for this terminal. Valid values: Y or N

Indicates if ECheck is setup for this terminal. Valid values: Y or N

FoodStamp

CashBenefit

Cash

Loyalty

Indicates if Food Stamp is setup for this terminal. Valid values: Y or N

Indicates if Cash Benefit is setup for this terminal. Valid values: Y or N

Indicates if Cash is setup for this terminal. Valid values: Y or N

Indicates if Loyalty is setup for this terminal. Valid values: Y or N

Examples

The following XML code example demonstrates a request to retrieve the terminal setup using accountxml.do

Terminal Setup Information Request xmldata=<txn><ssl_merchant_id>my_virtualmerchant_id</ssl_merchant_id>

<ssl_user_id>my_user</ssl_user_id><ssl_pin>my_pin</ssl_pin>

<ssl_transaction_type>terminalsetup</ssl_transaction_type></txn>

Converge Developer Guide: Transaction Format

Terminal Setup Information Response

<txn>

<MerchantInformation>

<MerchantName>ABC COMPANY</MerchantName>

<Address1>123 MAIN STREET</Address1><Address2/>

<ContactEmail>[email protected]</ContactEmail>

<TerminalEmail>[email protected]</TerminalEmail>

</MerchantInformation>

<TerminalInformation>

<vm_friendly_name>MY STORE</vm_friendly_name>

<vm_region>USA</vm_region>

<vm_time_zone>EST</vm_time_zone>

<vm_currency>USD</vm_currency>

<vm_market_segment>Retail</vm_market_segment>

<vm_status>ACTIVE</vm_status>

<vm_processing_type>TerminalBased</vm_processing_type>

<vm_payment_types>

</vm_payment_types>

CON-0002-N

(continued)

Converge Developer Guide: Transaction Format CON-0002-N

(end)

<vm_credit_option>

</vm_credit_option>

<vm_level3>N</vm_level3>

<vm_recurring_option>

<Frequency>MONTHLY</Frequency><Payments>12</Payments>

</vm_recurring_option>

<vm_debit_option>

</vm_debit_option>

<vm_echeck_option>

<CheckType>ACHECHECK</CheckType>

<TransactionType>VERIFICATION</TransactionType>

</vm_echeck_option>

<vm_transaction_entry>

</vm_transaction_entry>

<vm_tokenization>Y</vm_tokenization>

</TerminalInformation>

</txn>

Converge Developer Guide: Transaction Format CON-0002-N

Payment Field (fieldsetup)

This request is used to retrieve the payment field information as setup under the Terminal |

Merchant | Payment Fields option in the user interface terminal menu. The response contains the root xml beginning and ending element <txn>; within that element, section information is presented. Data for each section will be nested and embedded between beginning element

, and ending element </Section>, there are several section elements.

Within each Section element, fields are presented. Data for each field resides between beginning

<Field>

and ending </Field>, there are several field elements.

Request

Input Field Name Req? Description

ssl_transaction_type Y

Terminal Setup Information (fieldsetup). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured on Converge, case sensitive. ssl_pin Y Converge PIN as configured within Converge, case sensitive.

Response

Output Field Name

Name

DisplayName

ShowinVT

Description

Section name as configured by Converge. Example: OrderSection

Section label name, as configured by the merchant. Example: Order Section

Indicates if the section will show in the Virtual Terminal under the payment menu. Valid values: Y, N

ShowOnPaymentForm Indicates if the section will show in the Payment page under the payment menu. Valid values: Y, N

ShowinReceipt Indicates if the section will show in the receipt. Valid values: Y, N

CustomerEmail

MerchantEmail

Indicates if the section will show in the customer email. Valid values: Y, N

Indicates if the section will show in the merchant email. Valid values: Y, N

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name

Field

Description

Contains the field data elements and values as outlined below.

Output Field Name Description

Name Field name

DisplayName

Section

FieldType

Min

Max

Required

Field display name

Which section the field is located in

Field type, for example: TEXT

Minimum allowed size

ShowinVT

ChangedOnPaymentForm

Maximum allowed size

Indicates if the field is set to required.

Valid values: Y, N

Indicates if the field is set to show in the

Virtual Terminal. Valid values: Y, N

Indicates if the field can be changed in the payment form in the Virtual

Terminal. Valid values: Y, N

ShowOnPaymentForm

ShowinReceipt

CustomerEmail

MerchantEmail

ForwardOnApproval

ForwardOnDecline

SystemField

Indicates if the field is set to show in the payment page. Valid values: Y, N

Indicates if the field is set to show in the receipt. Valid values: Y, N

Indicates if the field is set to show in the customer email. Valid values: Y, N

Indicates if the field is set to show in the merchant email. Valid values: Y, N

Indicates if the field is set to be forwarded on approval. Valid values: Y, N

Indicates if the field is set to be forwarded on decline. Valid values: Y, N

Indicates if the field is a system or custom field. Valid values: Y, N

Converge Developer Guide: Transaction Format CON-0002-N

Examples

The following XML code example demonstrates a request to retrieve the payment field setup for a terminal using accountxml.do.

Payment Field Setup Information Request xmldata=<txn><ssl_merchant_id>my_virtualmerchant_id</ssl_merchant_id>

<ssl_user_id>my_user</ssl_user_id><ssl_pin>my_pin</ssl_pin>

<ssl_transaction_type>fieldsetup</ssl_transaction_type></txn>

Payment Field Setup Response

<txn>

<Name>OrderSection</Name>

<DisplayName>Order Section</DisplayName>

<Field>

<Name>ssl_account_data</Name>

<DisplayName>Order Section</DisplayName>

<Section>OrderSection</Section>

</Field>

<Field>

……….

</Field>

(continued)

Converge Developer Guide: Transaction Format

(end)

……….

</Section>

<Name>CustomFields</Name>

<DisplayName>Custom Fields</DisplayName>

<Field>

<Name>MyCustom</Name>

<DisplayName>Custom Fields</DisplayName>

<Section>CustomFields</Section>

</Field>

</Section>

</txn>

CON-0002-N

Converge Developer Guide: Transaction Format CON-0002-N

Printer Setup (printersetup)

This request is used to retrieve the printer information as setup under the Terminal | Merchant |

Printer option in the user interface. When sending the request you must use XML and send the transaction to accountxml.do. Response contains the root xml beginning and ending element

<txn>

Request

Input Field Name

ssl_transaction_type Y ssl_merchant_id

Req? Description

Terminal Setup Information (printersetup).

Converge ID as provided by Elavon. ssl_user_id ssl_pin

Converge User ID as configured on Converge, case sensitive.

Converge PIN as configured within Converge, case sensitive.

Response

Output Field Name

PrinterOptions

ReceiptHeaderOptions

Description

Indicates the printer options as described in the table below:

Output Field Name Description

PrinterType Type of printer, example: Serial Printer.

PaperType Type of paper, example: Multi Ply.

Indicates the header of the receipt as described in the table below:

Output Field Name Description

Justification The location of the header in the receipt. For example: Center

HeaderLine1

HeaderLine2

First line of the header, for example:

Thank you for shopping.

Second line of the header, for example:

Store ABC

HeaderLine3

HeaderLine4

HeaderLine5

Third line of the header, for example:

123 Main Street

Fourth line of the header.

Fifth line of the header.

Converge Developer Guide: Transaction Format CON-0002-N

Output Field Name Description

ReceiptTrailerOptions Indicates the trailer/footer of the receipt as described in the table below:

Output Field Name Description

Justification The location of the trailer in the receipt.

For example: Center

TrailerLine1

TrailerLine2

First line of the trailer, for example: Come back and shop with us again.

Second line of the trailer, for example:

Store ABC

TrailerLine3

TrailerLine4

TrailerLine5

Third line of the trailer, for example: 123

Main Street

Fourth line of the trailer.

Fifth line of the trailer.

ReceiptCustomFields Indicates the custom fields setup to show in the receipt.

Output Field Name Description

CustomLabel1 First custom field label setup to show in the receipt. Example: My Custom Data

CustomField1

CustomLabel2

First custom field setup to show in the receipt. Example: MyField

Second custom field label setup to show in the receipt.

CustomField2

CustomLabel3

CustomField3

CustomLabel4

Second custom field setup to show in the receipt.

Third custom field label setup to show in the receipt.

Third custom field setup to show in the receipt.

Fourth custom field label setup to show in the receipt.

CustomField4

CustomLabel5

CustomField5

Fourth custom field setup to show in the receipt.

Fifth custom field label setup to show in the receipt.

Fifth custom field setup to show in the receipt.

Converge Developer Guide: Transaction Format CON-0002-N

Examples

The following XML code example demonstrates a request to retrieve the printer setup for a terminal using accountxml.do.

Printer Setup Information Request xmldata=<txn><ssl_merchant_id>my_virtualmerchant_id</ssl_merchant_id>

<ssl_user_id>my_user</ssl_user_id><ssl_pin>my_pin</ssl_pin>

<ssl_transaction_type>printersetup</ssl_transaction_type></txn>

Printer Setup Information Response

<txn>

<PrinterType>Serial Printe</PrinterType>

<PaperType>Multi Ply</PaperType>

</PrinterOptions>

<Justification>Center</Justification>

<HeaderLine1>RECEIPT LINE 1</HeaderLine1>

<HeaderLine2>RECEIPT LINE 2</HeaderLine2>

<HeaderLine3>RECEIPT LINE 3</HeaderLine3>

<HeaderLine4>RECEIPT LINE 4</HeaderLine4>

<HeaderLine5>RECEIPT LINE 5</HeaderLine5>

</ReceiptHeaderOptions>

<Justification>Center</Justification>

<TrailerLine1>RECEIPT LINE 6</TrailerLine1>

<TrailerLine2>RECEIPT LINE 7</TrailerLine2>

</ReceiptTrailerOptions>

<CustomLabel1>Custom Field</CustomLabel1>

<CustomField1>MyCustom</CustomField1>

</ReceiptCustomFields>

</txn>

Converge Developer Guide: Integration Reference CON-0002-N

Chapter 5: Integration Reference

The following chapter reviews integration reference guidelines and examples to process, format, and send transactions using process.do, processxml.do , processBatch.do and accountxml.do.

Topics include:



Supported transaction input fields



Fraud prevention matrix



ISO country codes



ISO currency codes

Supported Transaction Input Fields

Field Name

ssl_3dsecure_value ssl_account_type ssl_add_token ssl_address2 ssl_amount ssl_approval_code ssl_avs_address ssl_avs_zip

9 ssl_background_color 20

Length

Default

Set In

Terminal

Req Description

Sent on 3D Secure authenticated transactions only.

Cardholder Authentication Verification

Value.

Note: Called UCAF for MasterCard -

Universal Cardholder

Authentication Field. Base 64

Encoded (28 characters).

Account Type (0 = checking, 1 = saving).

N Add token to Card Manager

 Y = add,

 N = do not add

Customer’s address line 2.

Transaction total amount.

Return code generated by credit card processor. Must be passed on force.

Customer's address used to process AVS.

Customer's ZIP code used to process AVS.

Any HTML color value.

Converge Developer Guide: Integration Reference CON-0002-N

Field Name

ssl_billing_cycle ssl_bill_on_half ssl_bin_override ssl_card_number ssl_card_present ssl_card_suffix ssl_card_type ssl_cardholder_ip ssl_cardholder_tip

_amount ssl_cashback_amount 10 ssl_check_image ssl_city

Length Default

12 Y

Req Description

Billing cycle. Valid returned values, all caps and no hyphens:

 DAILY



WEEKLY

 BIWEEKLY



SEMIMONTHLY

 MONTHLY



BIMONTHLY



QUARTERLY



SEMESTER

 SEMIANNUALLY



ANNUALLY



SUSPENDED

Y Half of the month or Semimonthly indicator.

Valid values are 1 and 2:

 1 = 1st and the 15th of the month

 2 = 15th and the last day of the month

The indicator that allows a Customer Code and/or a Sales Tax value to be passed in the transaction request for non-corporate cards. The value is always 1.

Card Number. Maximum length 18 for electronic gift cards.

Card Present indicator. Valid values: Y or

N. Hand-keyed.

The last 4 digits of the card number.

The card type. Available card types:

LOYALTY, CASHBENEFIT, CASH,

DEBITCARD, FOODSTAMP, CREDITCARD,

GIFTCARD, ELECTRONICCHECK.

Cardholder IP address.

Cardholder tip amount.

The amount of cash back that the customer will receive.

Check image data base 64 TIFF image.

Customer’s city.

Converge Developer Guide: Integration Reference CON-0002-N

Field Name

ssl_company ssl_country ssl_customer_code ssl_customer_number ssl_cvv2cvc2 ssl_cvv2cvc2

_indicator ssl_description ssl_do_customer

_email ssl_do_merchant

_email ssl_drivers_license

_number ssl_drivers_license

_phone_number ssl_drivers_license

_state ssl_dukpt ssl_dynamic_dba ssl_eci_ind

Length Default

255

Set In

Terminal

Set In

Terminal

Req Description

N Customer’s company name.

N Customer’s country ISO code.

Customer code.

This value is used to submit the customer account number or payee account number for PINLess debit transactions.

CVV2/CVC2 value from the card

CVV2 Indicator.

Valid values are:



0 = Bypassed

 1 = Present



2 = Illegible

 9 = Not Present

Transaction description.

Valid values are:

 T = True



F = False

Valid values are:



T = True

 F = False

The driver’s license number as entered by the user. Alphanumeric.

Customer’s 10-digit phone number including the area code.

State code.

This is the value returned by the PIN Pad device, which was used to encrypt the cardholder’s personal identification number (PIN) using the Derived Unique

Key Per Transaction (DUKPT) method.

DBA Name provided by the merchant with each transaction

The maximum allowable Length of DBA

Name variable provided by Merchant can be 21, 17 or 12 based on the length setup for the DBA constant in the field setup.

Sent on 3D Secure authenticated transactions only.

Converge Developer Guide: Integration Reference CON-0002-N

Field Name

ssl_egc_tender_type ssl_email ssl_email_apprvl

_footer_html ssl_email_apprvl

_header_html ssl_email_decl

_footer_html ssl_email_decl

_header_html ssl_email_footer ssl_email_header ssl_end_of_month ssl_entry_mode ssl_error_url

Length Default

100

255

Set In

Terminal

Set In

Terminal

Set In

Terminal

Set In

Terminal

Set In

Terminal

Req Description

Y This field is used to pass the tender type used to pay for the gift card. Valid Values are as follows:

 0 = Cash



1 = Credit

 2 = Debit



3 = Check

Customer’s email address.

Customer order confirmation email footer for approvals.

Customer order confirmation email header for approvals.

Customer order confirmation email footer for declines.

Customer order confirmation email header for declines.

Customer order confirmation email footer.

If present, overrides values for ssl_email_apprvl_footer_html

and ssl_email_decl_footer_html

Customer order confirmation email header. If present, overrides values for ssl_email_apprvl_header_html and ssl_email_decl_header_html.

End of month indicator.

Valid values Y or N. Must be passed on add or update of a recurring/installment transaction to indicate if the transaction is to be processed on the last day of the month.

Recommended for swiped or contactless transactions. The transaction entry indicator to indicate how the track data was captured. Valid values are:



03 = Swiped



04 = Proximity / Contactless

If present, the error will be redirected to the URL specified including the errorCode, errorName, and errorMessage fields. Refer

to the Error Codes section for an extensive

list of possible codes.

Converge Developer Guide: Integration Reference CON-0002-N

Field Name

ssl_eWallet ssl_eWallet_shipping ssl_exp_date ssl_first_name ssl_footer_html ssl_get_token ssl_header_color ssl_header_html ssl_image_type ssl_import_file ssl_installment_id ssl_invoice_number ssl_key_pointer

Length Default

255

Set In

Terminal

Set In

Terminal

Set In

Terminal

Req Description

N Wallet identifier. Defaulted for process.do

(true), only needed for process.do

(false) and processxml.do

to indicate if Merchant wishes to offer MasterPass.

Valid values: MasterPass.

The merchant must be set up with

MasterPass.

Indicates if Merchant is wanting to use the shipping information provided with

MasterPass, valid values: Y or N.

Card expiry date.

Customer’s first name.

Payment form footer. Ignored when ssl_show_form

= False.

Generate Token indicator (Y = generate token, N = do not generate token)

Any HTML color value.

Payment form header, Ignored when ssl_show_form

= False.

Image format, required for signature transactions.

Possible values, must be capital:



GIF

 TIF



JPG

 PNG

Path/Location and Name of Batch Import

File being imported.

The ID number of the installment record that has been. Required on update.

Alphanumeric.

This value was returned when the original installment was added.

Invoice number.

The pointer that indicates to Elavon which encryption key was used for US debit transactions and which key to use for the next transaction. Value always T.

Converge Developer Guide: Integration Reference CON-0002-N

Field Name

ssl_last_name ssl_link_color ssl_merchant_email ssl_merchant_id ssl_micr_data ssl_next_payment

_date ssl_number_trans ssl_original_date ssl_original_time ssl_partial_auth

_indicator ssl_payment_count ssl_payment_number ssl_phone ssl_pin ssl_pin_block ssl_pos_mode ssl_product_string

Length Default

20 Set In

Terminal

100

200

Req Description

N Customer’s last name.

N Any HTML Color Value.

Merchant’s email address.

Converge ID as provided by Elavon.

MICR number as read through the check reader.

Next payment date in MM/DD/YYYY format.

Number of Transactions imported in the import file.

Date of original transaction in MMDDYY format.

Time of original transaction in HHMMSS format.

Partial Auth indicator required to indicate the support of partial approval, defaulted to 0 if not sent.

Valid values:



0 – Partial Auth not supported

 1 – Partial Auth supported

Installment Count (Total Number of

Payments).

Installment Sequence Number (Payment

Number).

Customer’s phone number.

Converge PIN as configured within

Converge, case sensitive.

The encrypted personal identification number entered by debit/EBT cardholder as identification for transaction.

The payment application capability.

Defaulted to 02 when track data is sent.

Valid values are:



02 for Swiped device

 03 Proximity/ Contactless capable device

Product string for MasterPass transactions.

Converge Developer Guide: Integration Reference CON-0002-N

Field Name

ssl_receipt_apprvl

_footer_html ssl_receipt_apprvl

_get_url ssl_receipt_apprvl

_header_html ssl_receipt_apprvl

_method ssl_receipt_apprvl

_post_url ssl_receipt_apprvl

_text ssl_receipt_decl

_footer_html

Length Default

255 Set In

Terminal

255

Set In

Terminal

Set In

Terminal

Set In

Terminal

Set In

Terminal

Set In

Terminal

Set In

Terminal

Req Description

N Receipt form footer for approved transaction. Ignored when ssl_result_format

= ASCII.

Target of the link generated at the bottom of the receipt for an approval using the

GET method, or the target of the redirect for an approval using the REDG method.

Ignored when ssl_result_format =

ASCII and ssl_receipt_link_method

= LINK or POST.

Receipt form header for approved transaction. Ignored when ssl_result_format

= ASCII.

N REDG = No receipt displayed. Data redirected to ssl_receipt_link_url.

LINK = Receipt displayed. Link provided to return to ssl_receipt_link_url.

GET = Receipt displayed. Button provided to send GET data to ssl_receipt_link_url

POST = Receipt displayed. Button provided to send POST data to ssl_receipt_link_url

LINK, GET, POST ignored when ssl_result_format

= ASCII.

If present, overwrites ssl_receipt_decl_method and ssl_receipt_link_method.

Target of the link generated at the bottom of the receipt for an approval using the

POST method. Ignored when ssl_result_format

= ASCII.

Text that appears on the receipts of approved transactions.

Receipt form footer for declined transaction. Ignored when ssl_result_format

= ASCII.

Converge Developer Guide: Integration Reference CON-0002-N

Field Name

ssl_receipt_decl

_get_url ssl_receipt_decl

_header_html ssl_receipt_decl

_method ssl_receipt_decl

_post_url ssl_receipt_decl

_text ssl_receipt_footer

_html ssl_receipt_header

_html

Length Default

255 Set In

Terminal

255

Set In

Terminal

Set In

Terminal

Set In

Terminal

Set In

Terminal

Set In

Terminal

Set In

Terminal

Req Description

N Target of the link generated at the bottom of the receipt for a declined transaction using the GET method, or the target of the redirect for a declined transaction using the REDG method. Ignored when ssl_result_format

= ASCII and ssl_receipt_link_method

= LINK or

POST.

N Receipt form header for declined transaction. Ignored when ssl_result_format

= ASCII.

N REDG = No receipt displayed. Data redirected to ssl_receipt_link_url.

LINK = Receipt displayed. Link provided to return to ssl_receipt_link_url.

GET = Receipt displayed. Button provided to send GET data to ssl_receipt_link_url

POST = Receipt displayed. Button provided to send POST data to ssl_receipt_link_url

LINK, GET, POST ignored when ssl_result_format

= ASCII.

If present, overwrites ssl_receipt_decl_method and ssl_receipt_link_method.

Target of the link generated at the bottom of the receipt for a declined transaction using the POST method. Ignored when ssl_result_format

= ASCII.

Text that appears on the receipts of declined transactions.

Receipt form footer. Ignored when ssl_result_format

= ASCII.

Receipt form header. Ignored when ssl_result_format

= ASCII.

Converge Developer Guide: Integration Reference CON-0002-N

Field Name

ssl_receipt_link

_method ssl_receipt_link

_text ssl_receipt_link_url ssl_recurring_batch

_count

Length Default

4 Set In

Terminal

255

Set In

Terminal

Set In

Terminal

Req Description

N REDG = No receipt displayed. Data redirected to ssl_receipt_link_url.

LINK = Receipt displayed. Link provided to return to ssl_receipt_link_url.

GET = Receipt displayed. Button provided to send GET data to ssl_receipt_link_url

POST = Receipt displayed. Button provided to send POST data to ssl_receipt_link_url

LINK, GET, POST ignored when ssl_result_format

= ASCII.

If present, overwrites ssl_receipt_apprvl_method and ssl_receipt_decl_method.

Text in the link/on the submit button generated at the bottom of the receipt page. Ignored when ssl_result_format

= ASCII. If present, overwrites ssl_receipt_apprvl_text

and ssl_receipt_decl_text

Target of the Redirect or the link generated at the bottom of the Converge drawn receipt. Ignored when ssl_result_format

= ASCII and ssl_receipt_link_method

= GET,

POST, or REDG.

If present, overwrites ssl_receipt_apprvl_post_url, ssl_receipt_decl_post_url, ssl_receipt_apprvl_get_url, and ssl_receipt_decl_get_url.

Current number of transactions sitting in the recurring batch after the installment transaction has been added.

Converge Developer Guide: Integration Reference CON-0002-N

Field Name

ssl_recurring_flag ssl_recurring_id ssl_reference_number ssl_response_file ssl_result ssl_result_format ssl_result_message

Length Default

Req Description

N The recurring flag must be sent to indicate if a credit card sale transaction is a recurring or an installment payment. This option should only be used if maintaining your own recurring and installment database.

Valid values:

 1 = Recurring



2 = Installment

Note: When the flag is indicated as

Installment, the payment number and payment count must be passed.

The ID number of the recurring record to be updated. Required on update.

Alphanumeric.

This value was returned when the original credit card record was added, to be used for update or delete or Auth. It is a unique tracking number that the application assigns internally to each recurring record in the database. This number is returned in the authorization response message originally when a user adds a recurring or installment credit card.

Transaction reference number is returned in the authorization response.

The batch import response file friendly name, should not contain any of the following characters (\ / : * ? " < > | ).

Result code for the transaction. A result of

0 indicates an approval. Any other result means that the transaction was not approved.

When set to ASCII, Converge will generate a plain text key-value document.

Result message for the transaction. A result of APPROVAL indicates that a transaction was approved. Any other result means that the transaction was not approved.

Converge Developer Guide: Integration Reference CON-0002-N

Field Name

ssl_salestax ssl_search_start_ date ssl_search_end_date ssl_server ssl_shift ssl_ship_to_address1 30 ssl_ship_to_address2 30 ssl_ship_to_city ssl_ship_to_company ssl_ship_to_country

20 ssl_ship_to_first

_name ssl_ship_to_last

_name ssl_ship_to_phone ssl_ship_to_state

2 ssl_ship_to_zip ssl_show_form

5 ssl_signature_image ssl_skip_payment ssl_start_payment

_date

Length Default

10 End date minus 31

Start date plus 31

Req Description

N Sales tax.

C Start date of the search window. Format

MM/DD/YYYY. If you submit a start date without an end date, the end date will be set to start date plus 31 days (not the current date).

End date of the search window. Format

MM/DD/YYYY. If you submit an end date without a start date, the start date will be set to end date minus 31 days.

Server ID, this is the clerk, cashier, waiter or waitress identification number,.

Alphanumeric.

Shift, can refer to or used to identify time period, course or type of service.

Alphanumeric.

Ship To Address Line 1.

Ship To Address Line 2.

Ship To City.

Ship To Company Name.

Ship To Country ISO code.

Ship To First Name.

TRUE

Ship To Last Name.

Ship To Phone Number.

Ship To State.

Ship To ZIP.

When set to false, Converge will not present the payment form but process the transaction directly.

BASE 64 Encoded version of an IMAGE required for signature transactions and has size limit.

Skip payment field.

Start payment date with format

MM/DD/YYYY. Date when the first payment started. If recently added, start date is same as next payment.

Converge Developer Guide: Integration Reference CON-0002-N

Field Name

ssl_state

Length Default

2 ssl_surcharge_amount 5 Set In

Terminal ssl_table_color ssl_test_mode

Set In

Terminal

FALSE

Req Description

N Customer's state.

Surcharge amount to apply to this transaction. Configurable.

Any HTML color value.

N ssl_text_color ssl_tip_amount ssl_token ssl_total

_installments ssl_track_data

Optional when set to true. Transactions will not be forwarded to the credit card processor, but instead will always return an APPROVED result.

Any HTML color value.

Tip or gratuity amount to be added or updated, must be decimal, can be 0.00.

Credit Card Token generated from the card number. A token can be stored and used as a substitute for a card number.

Number of payments. Numeric. Max 999. ssl_trans_status

Track 1 or 2 data as read from a magnetic stripe reader (MSR).

Transaction status, example: STL (Settled).



PEN = Pended



OPN = Unpended, Released,

Open



REV = Review



STL = Settled

 PST = Failed Due to Post-Auth

Rule



FPR = Failed Due to Fraud

Prevention Rules

 PRE = Failed Due to Pre-Auth

Rule

Converge Developer Guide: Integration Reference CON-0002-N

Field Name

ssl_transaction

_currency ssl_transaction_type

Length Default

3 USD or

CAD

Req Description

N Transaction currency must be sent in the

3-digit Alpha ISO 4217 code. For a

complete list refer to the ISO Currency

Codes section.

Note: For those terminals setup for Multi-

Currency, you must send a transaction currency to specify the currency used to process the transaction. If a currency is not specified then it will default to the merchant currency. Do not send a transaction currency if your terminal is not setup for Multi-

Currency

Credit Transactions



Sale (ccsale)



Auth Only (ccauthonly)

 Return/ Credit (cccredit)

 Force (ccforce)



AVS Only (ccavsonly)



Verification (ccverify)



Balance Inquiry (ccbalinquiry)



Generate Token (ccgettoken)



Enhanced Return/ Credit

(ccreturn)

 Void (ccvoid)

 Completion (cccomplete)

 Delete (ccdelete)

 Signature (ccsignature)



Update Tip (ccupdatetip)

Credit Recurring Transactions

 Add (ccaddrecurring)

 Update (ccupdaterecurring)



Delete (ccdeleterecurring)



Submit (ccrecurringsale)

Credit Installment Transactions



Add (ccaddinstall)



Update (ccupdateinstall)



Delete (ccdeleteinstall)



Submit (ccinstallsale)

Converge Developer Guide: Integration Reference

Field Name

CON-0002-N

Length Default Req Description

Batch Import Transactions



Credit Batch Import (ccimport)



Recurring batch Import

(ccrecimport)

Debit Transactions



Purchase (dbpurchase)



Return (dbreturn)



Inquiry (dbbainquiry)

EMV Credit/ Debit Card Transactions



EMV Chip Sale (emvchipsale)



EMV Chip Auth Only

(emvchipauthonly)



EMV Swipe Sale

(emvswipesale)



EMV Swipe Auth Only

(emvswipeauthonly)



EMV Card Update

(emvchipupdatetxn)

 EMV Reversal (emvreverse)



EMV Key Exchange

(emvkeyexchange)

EBT Transactions



Food Stamp Purchase

(fspurchase)

 Food Stamp Return (fsreturn)

 Food Stamp Inquiry

(fsbainquiry)

 Food Stamp Force Purchase

(fsforcepurchase)

 Food Stamp Force Return

(fsforcereturn)

 Cash Benefit Purchase

(cbpurchase)

 Cash Benefit Inquiry

(cbbainquiry)

Converge Developer Guide: Integration Reference

Field Name

CON-0002-N

Length Default Req Description

Gift Card Transactions



Activation (egcactivation)



Sale / Redemption (egcsale)



Card Refund (egccardrefund)



Replenishment / Reload

(egcreload)



Balance Inquiry

(egcbalinquiry)

 Credit (egccredit)

Loyalty Card Transactions

 Enrollment (ltenrollment)

 Redemption (ltredeem)

 Return (ltreturn)



Add Points (ltaddpoints)



Balance Inquiry (ltinquiry)



Lead Inquiry (ltleadinquiry)



Member Inquiry

(ltmemberinquiry)



Void (ltvoid)

 Delete (ltdelete)

Check Transactions (ECS)



Electronic Check Purchase

(ecspurchase)



Void (ecsvoid)

Check Recurring



Add (ecsaddrecurring)



Delete

(ecsdeleterecurring)



Submit (ecsrecurringsale)

 Update (ecsupdaterecurring)

Check Installment



Add (ecsaddinstall)



Delete (ecsdeleteinstall)



Submit (ecsinstallsale)



Update (ecsupdateinstall)

PINLess Debit Transactions

 PINLess Debit Purchase

(pldpurchase)

Converge Developer Guide: Integration Reference CON-0002-N

Field Name

ssl_txn_count ssl_txn_ecg_count ssl_txn_ecg_amount ssl_txn_id ssl_txn_main_count ssl_txn_main_amount ssl_user_id ssl_voucher_number ssl_xid

Length Default

Req Description

Cash Transactions



Cash Sale (cashsale)



Cash Credit (cashcredit)

Card Manager Transactions



Token Query (ccquerytoken)

 Token Update

(ccupdatetoken)



Token Delete (ccdeletetoken)

End of Day Transactions



Total/ Summary (total)



Transaction Query (txnquery)



Transaction Email (txnemail)



Settle (settle)

Account Admin Transactions



Terminal Setup

(terminalsetup)

 Field Setup (fieldsetup)



Printer Setup (printersetup)

The number of transactions matching the search query.

Total gift card count to be settled.

Total gift card amount to be settled.

Transaction identification number. This is a unique number used to identify the transaction. Required for void and delete transactions.

Total Transaction count in Main Batch to be settled.

Total Transaction amount in Main Batch to be settled.

Converge User ID as configured on

Converge, case sensitive.

The voucher number from an EBT sales slip. Used for Voucher Clear Food Stamp transactions.

Sent on 3D Secure authenticated transactions Only.

Unique transaction identifier assigned by eMPI.

Converge Developer Guide: Integration Reference CON-0002-N

Fraud Prevention Matrix

The following table provides the list of fraud prevention rules and applicable transaction types.

The fraud prevention rules are set up through the user interface and triggered through requests initiated through process.do, processxml.do, or processBatch.do. Merchant will receive a result message (ssl_result_message) of Declined when a fraud rule is triggered. The reason for the decline will display under the error batch as Declined – [Rule Name].

Notes:

 The cardholder IP address (ssl_cardholder_ip) is required for the IP address filter and the IP Address velocity filter.



The billing country ISO code (ssl_country) is required for billing country filter.



The shipping country ISO code (ssl_ship_to_country) is required for shipping country filter.

 The cardholder IP address (ssl_cardholder_ip) and the billing country ISO code

(ssl_country) are required for the IP address and billing country mismatch filter.



The cardholder IP address (ssl_cardholder_ip) and the shipping country ISO code

(ssl_ship_to_country) are required for the IP address and shipping country mismatch filter



The email (ssl_email) is required for Email Address filter.



The cardholder IP address (ssl_cardholder_ip) value should reflect the IP address from which the transaction originates. For example: Consumer IP for a website clerk workstation IP address.

Transaction Type

ccaddinstall ccaddrecurring ccauthonly X ccavsonly ccbalinquiry cccredit ccforce

X ccimport

Converge Developer Guide: Integration Reference CON-0002-N

Transaction Type

ccrecimport ccreturn ccsale ccverify pldpurchase

ISO Country Codes

The following is a complete ISO 3 encoding list of the countries which are assigned official codes.

It is listed in alphabetical order by the English short country name.

Country

Afghanistan

Åland Islands

Albania

Algeria

American Samoa

Andorra

Angola

Anguilla

Antarctica

Antigua and Barbuda

Argentina

Armenia

Aruba

Australia

Austria

Azerbaijan

Bahamas

Code Country

AFG Liberia

ALA

ALB

DZA

Libya

Liechtenstein

Lithuania

ASM Luxembourg

AND Macao

AGO Macedonia, the former Yugoslav Republic of

AIA

ATA

ATG

Madagascar

Malawi

Malaysia

ARG Maldives

ARM Mali

ABW Malta

AUS Marshall Islands

AUT

AZE

BHS

Martinique

Mauritania

Mauritius

Code

LBR

LBY

LIE

LTU

LUX

MAC

MKD

MDG

MWI

MYS

MDV

MLI

MLT

MHL

MTQ

MRT

MUS

Converge Developer Guide: Integration Reference

Country

Bahrain

Bangladesh

Barbados

Belarus

Belgium

Belize

Benin

Bermuda

Bhutan

Bolivia, Plurinational State of

Bonaire, Sint Eustatius and Saba

Bosnia and Herzegovina

Botswana

Bouvet Island

Brazil

British Indian Ocean Territory

Brunei Darussalam

Bulgaria

Burkina Faso

Burundi

Cambodia

Cameroon

Canada

Cape Verde

Cayman Islands

Central African Republic

Chad

Chile

China

Christmas Island

Cocos (Keeling) Islands

Colombia

Comoros

Code Country

BHR Mayotte

BGD Mexico

BRB

BLR

BEL

BLZ

Micronesia, Federated States of

Moldova, Republic of

Monaco

Mongolia

BEN Montenegro

BMU Montserrat

BTN

BOL

Morocco

Mozambique

BES

BIH

Myanmar

Namibia

BWA Nauru

BVT

BRA

IOT

Nepal

Netherlands

New Caledonia

BRN

BGR

BFA

BDI

New Zealand

Nicaragua

Niger

Nigeria

KHM Niue

CMR Norfolk Island

CAN

CPV

Northern Mariana Islands

Norway

CYM Oman

CAF Pakistan

TCD Palau

CHL Palestinian Territory, Occupied

CHN Panama

CXR Papua New Guinea

CCK

COL

Paraguay

Peru

COM Philippines

CON-0002-N

PSE

PAN

PNG

PRY

PER

PHL

MNP

NOR

OMN

PAK

PLW

NPL

NLD

NCL

NZL

NIC

NER

NGA

NIU

NFK

Code

MYT

MEX

FSM

MDA

MCO

MNG

MNE

MSR

MAR

MOZ

MMR

NAM

NRU

337

Converge Developer Guide: Integration Reference CON-0002-N

Country

Congo

Code

COG

Country

Pitcairn

Congo, the Democratic Republic of the COD Poland

Cook Islands

Costa Rica

Côte d'Ivoire

Croatia

Cuba

Curaçao

COK

CRI

CIV

HRV

Portugal

Puerto Rico

Qatar

Réunion

CUB Romania

CUW Russian Federation

Cyprus

Czech Republic

Denmark

Djibouti

Dominica

Dominican Republic

Ecuador

Egypt

CYP

CZE

DNK

Rwanda

Saint Barthélemy

Saint Helena, Ascension and Tristan da

Cunha

DJI Saint Kitts and Nevis

DMA Saint Lucia

DOM Saint Martin (French part)

ECU Saint Pierre and Miquelon

EGY Saint Vincent and the Grenadines

El Salvador

Equatorial Guinea

Eritrea

Estonia

Ethiopia

Falkland Islands (Malvinas)

Faroe Islands

Fiji

Finland

France

French Guiana

French Polynesia

French Southern Territories

Gabon

Gambia

SLV Samoa

GNQ San Marino

ERI

EST

ETH

FLK

FRO

FJI

FIN

FRA

GUF

PYF

ATF

Sao Tome and Principe

Saudi Arabia

Senegal

Serbia

Seychelles

Sierra Leone

Singapore

Sint Maarten (Dutch part)

Slovakia

Slovenia

Solomon Islands

GAB Somalia

GMB South Africa

WSM

SMR

STP

SEN

SRB

SYC

KNA

LCA

MAF

SPM

VCT

SLE

SGP

SXM

SVK

SVN

SLB

SOM

ZAF

Code

PCN

POL

PRT

PRI

QAT

REU

ROU

RUS

RWA

BLM

SHN

Converge Developer Guide: Integration Reference CON-0002-N

Country

Georgia

Germany

Ghana

Gibraltar

Greece

Greenland

Grenada

Guadeloupe

Guam

Guatemala

Guernsey

Guinea

Guinea-Bissau

Guyana

Haiti

Heard Island and McDonald Islands

Holy See (Vatican City State)

Honduras

Hong Kong

Hungary

Iceland

India

Indonesia

Iran, Islamic Republic of

Iraq

Ireland

Isle of Man

Israel

Italy

Jamaica

Japan

Jersey

Code Country

GEO South Georgia and the South Sandwich

Islands

DEU South Sudan

GHA

GIB

GRC

GRL

Spain

Sri Lanka

Sudan

Suriname

GRD

GLP

Svalbard and Jan Mayen

Swaziland

GUM Sweden

GTM Switzerland

GGY Syrian Arab Republic

GIN

GNB

Taiwan, Province of China

Tajikistan

GUY

HTI

Tanzania, United Republic of

Thailand

HMD Timor-Leste

ISR

ITA

JAM

JPN

JEY

IRN

IRQ

IRL

IMN

VAT Togo

HND Tokelau

HKG Tonga

HUN Trinidad and Tobago

ISL

IND

IDN

Tunisia

Turkey

Turkmenistan

Turks and Caicos Islands

Tuvalu

Uganda

Ukraine

United Arab Emirates

United Kingdom

United States

United States Minor Outlying Islands

Uruguay

Code

SGS

ARE

GBR

USA

UMI

URY

TCA

TUV

UGA

UKR

TGO

TKL

TON

TTO

TUN

TUR

TKM

SJM

SWZ

SWE

CHE

SYR

TWN

TJK

TZA

THA

TLS

SSD

ESP

LKA

SDN

SUR

Converge Developer Guide: Integration Reference CON-0002-N

Country

Jordan

Kazakhstan

Code Country

JOR Uzbekistan

KAZ Vanuatu

Kenya

Kiribati

KEN

KIR

Korea, Democratic People's Republic of PRK

Korea, Republic of KOR

Kuwait

Kyrgyzstan

KWT

KGZ

Venezuela, Bolivarian Republic of

Viet Nam

Virgin Islands, British

Virgin Islands, U.S.

Wallis and Futuna

Western Sahara

Lao People's Democratic Republic

Latvia

Lebanon

Lesotho

LAO

LVA

LBN

LSO

Yemen

Zambia

Zimbabwe

ISO Currency Codes

The following is a complete ISO 4217 encoding list of the currencies which are assigned official codes. It is listed in alphabetical order by the English short currency name.

Currency

United Arab Emirates Dirham

Netherlands Antillean Guilder

Argentine Peso

Austrailian Dollar

Aruban Florin

Azerbaijani Manat

Barbados Dollar

Bangladeshi Taka

Bulgarian Lev

Bahraini Dinar

Bermudian Dollar

Brazilian Real

Bahamian Dollar

Botswana Pula

Canadian Dollar

Code Currency

AED Kazakhstan Tenge

ANG Lebanese Pound

ARS Sri Lanka Rupee

AUS Lithuanian Litas

AWG Latvian Lats

AZN Libyan Dinar

BBD

BDT

BGN

BHD

Moroccan Dirham

Macedonian Denar

Mauritian Rupee

Malawian Kwacha

BMD Mexican Peso

BRL Malaysian Ringgit

BSD Namibian Dollar

BWP Nigerian Naira

CAD Norwegian Krone

Code

KZT

LBP

LKR

LTL

LVL

LYD

MAD

MKD

MUR

MWK

MXN

MYR

NAD

NGN

NOK

Code

UZB

VUT

VEN

VNM

VGB

VIR

WLF

ESH

YEM

ZMB

ZWE

Currency

Congolese Franc

Swiss Franc

Chilean Peso

China Yuan Renminbi

Colombian Peso

Costa Rican Colon

Czech Koruna

Danish Krone

Dominican Peso

Algerian Dinar

Estonian Kroon

Egyptian Pound

Ethiopian Birr

Euro

Fiji Dollar

Pound Sterling

Guatemalan Quetzal

Hong Kong Dollar

Croatian Kuna

Haitian Gourde

Hungarian Forint

Indonesian Rupiah

Israeli Shekel

Indian Rupee

Iranian Rial

Icelandic Krona

Jamaican Dollar

Jordanian Dinar

Japanese Yen

Kenyan Shilling

South Korean Won

Kuwaiti Dinar

Converge Developer Guide: Integration Reference

DOP

DZD

EEK

EGP

ETB

Code Currency

CDF Nepalese Rupee

CHF New Zealand Dollar

CLP

CNY

COP

CRC

CZK

DKK

Omani Rial

Peruvian Nuevo Sol

Philippine Peso

Pakistani Rupee

Polish Zloty

Qatari Rial

Romanian New Leu

Serbian Dinar

Russian Ruble

Saudi Riyal

Swedish Krona

EUR

FJD

GBP

GTQ

HKD

HRK

HTG

HUF

IDR

Singapore Dollar

Syrian Pound

Thai Baht

Tunisian Dinar

Turkish Lira

Trinidad and Tobago Dollar

New Taiwan Dollar

Ukrainian Hryvnia

US Dollar

ILS

INR

IRR

ISK

JMD

Venezuelan Bolivar Fuerte

Vietnamese Kong

Gabon Franc

East Caribbean Dollar

Ivory Coast Franc

JOD

JPY

KES

Fr. Polynesia Franc

South African Rand

Zambian Kwacha

KRW Zimbabwe Dollar

KWD

CON-0002-N

XPF

ZAR

ZMK

ZWL

VEF

VND

XAF

XCD

XOF

SGD

SYP

THB

TND

TRY

TTD

TWD

UAH

USD

Code

NPR

NZD

OMR

PEN

PHP

PKR

PLN

QAR

RON

RSD

RUB

SAR

SEK

341

Converge Developer Guide: Additional Processing Options CON-0002-N

Chapter 6: Additional Processing

Options

The following sections review the transaction processes and provide implementation guidelines and examples to format, process, and send payments with specific needs using process.do, processxml.do

and processBatch.do.

Topics include:

 3D Secure

 MasterPass

 Dynamic Currency Conversion (DCC)

 Multi-Currency Conversion (MCC)

 Tokenization

 Encryption



Loyalty



Electronic Check ACH ECheck

3D Secure

Converge uses the Elavon eMPI engine to allow processing of 3D secure transactions. The following transactions types are supported when processing 3D secure transactions:

Transaction Types Description

ccsale Credit Card Sale ccauthonly

Credit Card Auth Only

Notes:



The terminal must be setup for e-Commerce.



The terminal must be setup for 3D Secure.



3D Secure processing is supported with MasterCard and Visa transactions only. Other card types will process as normal and will not trigger 3D secure processing.

Converge Developer Guide: Additional Processing Options CON-0002-N

The process of authentication is to retrieve and pass the following Issuer Authentication variables:

Field Name

ssl_eci_ind ssl_3dsecure_value

Req? Description

e-Commerce indicator or ECI Values

(fully authenticated) - There is a liability shift and the merchant is protected from chargeback

(VbV has been attempted) - There is a liability shift and the merchant is protected from chargeback

(Non-VbV transaction) – The merchant is no longer protected from chargeback

Cardholder Authentication Verification Value or CAVV ssl_xid C Unique transaction identifier assigned by eMPI

Transaction Flow

Using process.do

If you are using process.do to integrate to Converge, there is no additional work required to utilize the eMPI, as the authentication piece is built in and the authentication variables are passed for you. The following steps outline the process of sending a 3D Secure transaction with process.do

1. The website processes Auth only or Sale transactions and collects the payment

information using process.do. Refer to Credit Card Sale (ccsale)

and Credit Card Auth

Only (ccauthonly) sections for more information.

2. Consumer enters Visa or MasterCard card number at the check-out.

3. The website is redirected automatically to the issuer website.

4. Cardholder completes the authentication process by either enrolling in the program for the first time and successfully authenticating, or authenticating using an existing account with the issuer or simply by opting out if allowed by the issuer.

5. The issuer passes the Issuer Authentication variables to Converge and redirects the cardholder browser back to Converge.

6. Converge processes the transaction with the authentication variables and returns a response to the website displaying the results and the ECI response code in the response.

Using processxml.do

If you are using processxml.do to integrate to Converge, you have to pass the Issuer

Authentication variables ssl_eci_ind, ssl_3dsecure_value and ssl_xid in the Credit Card Sale or the

Credit Card Auth Only requests. Those values are obtained by integrating your system to any eMPI capable engine of your choice. Converge has a built-in integration to the Elavon eMPI service that can be utilized free of charge.

Converge Developer Guide: Additional Processing Options CON-0002-N

The following steps outline the process of sending a 3D secure transaction with processxml.do using Elavon built-in eMPI engine:

1. Cardholder enters a Visa or a MasterCard card number at the checkout.

2. The website collects the payment information using processxml.do and sends an enrollment request to Converge.

3. Converge will determine if the card is eligible for 3D Secure processing and responds to the website with a URL, a merchant data value and an encoded payer request value.

Note: This completes the first stage in the authentication process.

Shown below is an example of a card enrollment request using processxml.do:

Step 1: Send a card enrollment request xmldata=<txn>

<ssl_merchant_id>my_virtualmerchant_id</ssl_merchant_id>

<ssl_user_id>my_user_id</ssl_user_id>

<ssl_pin>my_pin</ssl_pin>

<ssl_transaction_type>paenrolled</ssl_transaction_type>

<ssl_card_number>0000000000000000</ssl_card_number>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_amount>1.00</ssl_amount>

</txn>

Converge Developer Guide: Additional Processing Options CON-0002-N

Receive a card enrollment response along with the issuer URL:

<txn>

<acs_url>https://secure.issuerwebsite.com/Visaormastercard.jsp

</acs_url>

<pareq>eJxVUu9PwjAQ/VeWfYe2uOEktxoEiSYWBaeJn0zTHTJlHXRFYH+9LQ5/fGn uXa/v3r0rXO7LVfCJpi4qnYasS8MAtaryQr+l4VM26SRhUFupc7mqNKbhAevwkkO2N

IjjR1RbgxwE1rV8w6DI03AtDW5ekySO8hgXnYjl7ogX553kgkUddY6SLlS/r2Qv5PA wnOOGQ9ufu/bdHpATdLxGLaW2HKTaXN1O+d39aHj3KkZA2gSUaG7HXIwoZUC+AWhZI rdY28DljgBUtdXWHHgSUSAnAFuz4ktr1wNCdrtdt9AWjUZbH8fqqqoE4kuA/Ap52Pq odpT7IufiQ5xNG9VMs/lEPEZsRieTeTazz+PrFIivgFxa5D3KIhr3koD1B1E0oDGQY x5k6bW4eyerjWHtWwz/XPxNgJNm3IZOo5wQ4H7tFuSfAPmJgfzqHd14G5V1Dk2z61g

0H40YD3fi/eVMNC/sfpam3tZjgWcrnEMs9ra2AIinIO3OSLt0F/37DF+VksSF</par eq>

<md>rO0ABXNyACZjb20ubm92YWluZm8uYWRhcHRlci5lbXBpLk1lcmNoYW50RGF0YQ

AAAAAAAAABAgAETAACaWR0ABJMamF2YS9sYW5nL1N0cmluZztMAApwYXJhbWV0ZXJz dAATTGphdmEvdXRpbC9IYXNoTWFwO0wAFnRocmVlRFNlY3VyZU1lcmNoYW50SWRxAH

4AAUwAA3hpZHEAfgABeHB0ACFOdnpiV3VNbGQ4TnA3ZkE3RjU2X1FGdTEwMTY0MTMy

NTlzcgARamF2YS51dGlsLkhhc2hNYXAFB9rBwxZg0QMAAkYACmxvYWRGYWN0b3JJAA l0aHJlc2hvbGR4cD9AAAAAAAAMdwgAAAAQAAAAAnQACXNlc3Npb25JZHEAfgAEdAAM

ZGNjUmVxdWVzdGVkdAABTnh0AApFTVBJLTAwMDAxdAAUMkM3NzczNTRFMS41Q0FFRT

QtVDE=</md>

</txn>

4. If Converge indicates that the card is enrolled, the website will need to redirect the cardholder to the URL returned in the acs_url field and posts the results received from

Converge. The post must include the merchant URL so the issuer can redirect the cardholder back to the merchant once the authentication has been completed. The website will receive a new merchant data value and an encoded payer response value from the issuer.

5. The website sends a second request to Converge with the merchant data value and an encoded payer request value.PaRes value obtained from the issuer in step 1.

Notes:



This completes the second stage in the authentication process.



There is a 15-minute window given to allow the website to responds back to Converge.

Shown below is an example of a payer authentication:

Converge Developer Guide: Additional Processing Options CON-0002-N

Step 2: Send a Payer Authentication Request

The Merchant will redirect the Customers Browser to the Issuer website and post the authentication request (paReq). Inline authentication Windows with or Without Frames are recommended. Popup windows are not allowed.

Note: Do not use the GET method

<Form action="https://secure.issuerwebsite.com/Visaormastercard.jsp" method=POST> <input type="hidden" id="PaReq" name="PaReq" value="eJxVUu9PwjAQ/VeWfYe2uOEktxoEiSYWBaeJn0zTHTJlHXRFYH+9LQ5/fGn uXa/v3r0rXO7LVfCJpi4qnYasS8MAtaryQr+l4VM26SRhUFupc7mqNKbhAevwkkO2N

0H40YD3fi/eVMNC/sfpam3tZjgWcrnEMs9ra2AIinIO3OSLt0F/37DF+VksSF">

<input type="hidden" id="TermUrl" name="TermUrl" value="https://www.merchantwebsite.com/3DSReturn.jsp"> <input type="hidden" id="MD" name="MD" value="rO0ABXNyACZjb20ubm92YWluZm8uYWRhcHRlci5lbXBpLk1lcmNoYW50RGF

0YQAAAAAAAAABAgAETAACaWR0ABJMamF2YS9sYW5nL1N0cmluZztMAApwYXJhbWV0Z

XJzdAATTGphdmEvdXRpbC9IYXNoTWFwO0wAFnRocmVlRFNlY3VyZU1lcmNoYW50SWR xAH4AAUwAA3hpZHEAfgABeHB0ACFOdnpiV3VNbGQ4TnA3ZkE3RjU2X1FGdTEwMTY0M

TMyNTlzcgARamF2YS51dGlsLkhhc2hNYXAFB9rBwxZg0QMAAkYACmxvYWRGYWN0b3J

JAAl0aHJlc2hvbGR4cD9AAAAAAAAMdwgAAAAQAAAAAnQACXNlc3Npb25JZHEAfgAEd

AAMZGNjUmVxdWVzdGVkdAABTnh0AApFTVBJLTAwMDAxdAAUMkM3NzczNTRFMS41Q0F

FRTQtVDE="> <input type="submit" name="Proceed to Issuer Website">

</form>

Converge Developer Guide: Additional Processing Options CON-0002-N

Receive the Payer Authentication response:

PaRes = eJzFWMmSo8qS3ddXlNVbyrKYEVxTpVkwCIEUSCAmsbnGJECMYhDD1zfKrKzKV32 trV9vWht5eES4H3ePODhsjKSJIuEcBX0TvW5g1LZeHH1Nwx/faq

J7n9HHhUEBM2 sASBvpA0hb8wjHd9wQIcw5k1g1Ek9u11cwJ61P7a1v4dYER49ejgJaJY9oUMmfC

F8cPwBV0H1wilInLNRMu2R9S0aVW Yt/R7/gG

RguOJog8crudeMFd05WXw9HHhz tuQN8lOxKaJGFl4tGUWxDfI

2JReEb12Udt9XXRvg01Q9WXXTK8MiW6Qj8Gmb/LXpOvqvxBkGIbvadlFTRl17Vs avgdVsUGeSzbIbyCn/im1i8kxDV9hZqLQgJR

U3k9pURV2PKqkXWWIP7YIM8Vm9DrolccxUiUwamvGPkXuv4LZzfIm37jFU8sy/w

C66e8qZ8uwKeJz4rNAq2JyuAjlI/RJhrrqoyeWzbIL3mD/MZbe Ur umHLb/F9qLdGM7rpkuLP3CyfxHLgjf9pu28rm9fLxvkp7QJvMfjFRryrAomrs4x

BQVxgrOGqbeAPBpgif9tySYK0leUWkAt/2

7QB5XTdolxRPqvys2yBMK8naMXjfnNC4XZ030dSzysv3x7VOtBuJ71cTIkh8UQV lkWRC2afyvb 7olAur9V/tI33yqpMAy9PZ69bTh

MuqQKv/7C9k9mDP1pCUN0kX9ZTL0EGFm PDUogVHfkE8R/G s/Qmqab2XNvGwpyE9ukbPQkdfTV3 8e1f/9H1EtJ4uQz/Fwgf7t8tWF7eR6 t7EQmcjhmhdGS1Y63O6rv2eSGMMNS888rN8gv2Iv8uy6f8vK

8MgnD8m/zFHL7ixZJmNWQCZvq9qlR3IeSZ/97LYyrxoj8rF/dE3hAtNjdGfpiEw

9dNWxcgWv5hCG82B8KZ1c7c5YpnEFmumCpNc2IXCVJu7unsR6pVfHV9NvS5jtwM

XDmxxvpxOXAbFQR53SS1cSc1q8YpKA6l YAFfbNUZNDHpXuK066S13PTVwp pkM5lg32UEKvMefEwJNM

7PYaLIX2ED79SOJkRZ1lx6NZJLeB1X/rAlCPixl9Q8igHV9Hr9dNIYI7onMeYs3 u9ss7MqmGvHpk/gCMw59W zUigY/4tqPQpZjQBP6xWYsPevlzn0aZUqzuY02N2

ZS3vMzZ3Vf3NSYAD/Z0RmWE9uPHe I/JXuzj6b3KizCT5V

Br8HsAr7fLnibW/50mVe16pEHLWgWgcH2j0B2bUjn8zxmjtCzzaK brzRR pHgCvsvKC7ZO4n6L8BuqjSis2oV8cDHw5dPKFd0taOHC6qnjBMZX4gETGncQmWi

65dKAjJzZOS/HAFPI21df5jY6Q87xyD/qa6WkMVe9NJHT1Pf0iGToTT3RnWOA0G

SXcdUakOFe3G3gDczRXYFJNuvY1TGgdx2tEWV

1W8/e5Fzd45aukHQ0CzFewlpFviTybmimqx01D7c3LWaJhgxDU6vB7aATdE6gDF pqbHYyAgTLyEq8Y8keln1b5aWXDwUpCoiQVU1fIMKXU1p3kb7f10q5pUJrO8iov artNiOu2E3AIHGXGGl4VuUjyxvxg6yBBrgNIv7m7n rCvJbdCiUFbzOe5f4qOnS68Jcy/MEyrJQCDwPKj4Gg8yBWNaBYuIPAqEOYszVCg

44JzoX0mUQtIuyr1w5eQQq0MQtp4EhEMQDBJkEMFPkEshrqDiKAjhysWotxgwOZ ftQ2k6ezYyiAU7v sDgRTbxCLf2pTGHejBstYtgadpeHCjFL/U8KKg83Kr5hbAm1xBNyMlvPvgRHnRp i17OnODaFBoU5igY4PBuFxqcZKmmmA27JFChAYajIC7P28twNETSfurmP3Q3joV aO/Dv/iVxUATNEDUIyHd/HNwZOIVeHKX2Z1GHgHmPdYSygW bsMhbXzLH7QysdwyVIWT5ErM1

YWFmrh1Cx1liVEbxPjNx0EcOtF13NyX2MG3rT4URA9y8ZtdMELdNTHtfOY4DYOx bmOYv8TrE/IQx2IKASrx57t0ln1C0EQOaCYApMwJA3jO70G11FDjJ8pq3dupz1A

/oLjp1g2POmNAkrvUI3W8TCTH2j36KhO2 mOVMoKXnsObeZf4tULbkM9Iosr9cJtcTdCjSawU1wq2WxHN64GWL8p8Q8TAx7e8

6Zb1uGMQnN8H2mO6xLay6

1TvWYPJyrrdo9p3Tgafu/II17cZVfdTcLhjqkmQJRjMESYSuYhWxBAOVkhl50mB bgrOpt29c73SqbsWP64xmFqoo1rieWtXsOj4AVTRqzE

Mo/FNale7agdGcIWyPBMJ3PeNjtrnfnasznUMA1Vp0R20jjc2OL1RTRU2qHd4f3

3EHM9pT/sMXO0LjBKre1YETo6ZDrjpPp17kxEiNjyZc1T5gw9iyAEg3WQBRBAMz

3qF4iByyKDxEIBBeNZXR09A2yFLEQQQ2/Gf9eJ

1mupkX03t3bIMcrg7UakOWdlxQzuecYuRL70REZ7pFey7Tlr17mkBP7QptpLVhL jT7d05lp1nKkDjgpHTY31gz7ZQTqToRrvj3KVmSmzonjysCK2ebsv7Lagdc6BN9 oLJOzS

(continued)

Converge Developer Guide: Additional Processing Options CON-0002-N

YgFisAXpEAGeBnWK3I7cQZCtU8fgu44SwtsNqNDFTxUjddo5x70h52qMWteK3Vi ssRLOxmpIekwb8KtWYCdZJiK5yGdNvukJJOi6MPupHXvYs

POSf1BXp7yqz58WOZcYL3tuw

GLjWKaTHpFJxa9cXMiBnzrAcDNpZqQVbUZiQ1OfhUcRC31IYtG9E/SIHeFUT/Co wL/tjOseKBoe8QQdbm6dsBNcN8ifD/SPlxU/KK9IPytMkpBsa6NjaqsebZnc7VK w2L0ng4uyeZOlyUdHnVdsCgRv P ji4uiJLKr5Qo1POlQhaD/oQnyjCwNE2wEdoQBIaGgDFExSFUJv0U1/6uAOjPwMl

Hf/FwNkKgf1n8dX02RxCE

LnyQo8gfUxUEY3vQ7cUhOF7vDPXtsFwwO5Mz3mBN4PC9U7DpK7zq64doq9qTlrQ

DO7z5ag0f1JJTEWMMXutst8WnowL/bFcRBzw2LU5a6cPJ/y7m4BWB5h9MY8Jzn4

/0ii4BkKm57uO6aNleg1NSEvVqVd3puVHYGVSk/HLJCfFnv

ZLNHgF2vxM6FgeZ2g9Nr1vZgfEMK8odcyq1x8wiYctLe55uHqVKYYWL2sOjZ6e6

OdioDIQZq yxokHMO2iiCPq5JERXZ1Li5CcPHCuJjjk4iBZq8fVmNOs1S/Cid11t9dJ aJUTlNK5qobz/tagEQ9DI4iUw02wrL4oZ2kX7ViJjsG9P5ME268SFFjTWIejrTt hcee1CuCodL65u6SYDddSZM5A1JUbW4fBVqQrR2hAnC9FQ

KMc4eRtlLOHXIzpzqXqBQ7ojPwaFG5nQ5kN

/bY3m/WwqSOnxC7Vs19luerWDfuOlDW4ht6Siq8TJ81G6nL5R3XbpoAUhPWgOxy

P0PlEa0TJykHZcIdMJHR3UdwnFJNJmNibHe9zp9JsneY jbvkTO1C5UUYi7pS/ZfHy1jSHLdhY3a3x62ZNmS yxNNuvOMNu4aVu

61jUgEpuTtUMo9WEAnqqqd44yYvQM7bsn

Ep4khRpZTee2UoKca7pCu16zQIYPjbRQIZqUISJrIJwEaTUI9m

4rPjtGzxP780nwDFs5N mRLJxBPqeZCCdrWDptnbxMsOtGYmXNHCOVow6DrLEhdehBo9l1d1Iq/HSpcWLtZ

A89PSAuagp1YI8EWl7y7tF4km8QEIz0Rd52e mK7O

XhxmcEmR1GJ0GW056qV8Z1NBjZN5btXetstNo8CbSJJL2D5SG/G7okF/N e

2/e37w9sHmef78ecPNf8FfxDQ0w==

MD = rO0ABXNyACZjb20ubm92YWluZm8uYWRhcHRlci5lbXBpLk1lcmNoYW50RGF0YQA

AAAAAAAABAgAETAACaWR0ABJMamF2YS9sYW5nL1N0cmluZztMAApwYXJhbWV0ZX

JzdAATTGphdmEvdXRpbC9IYXNoTWFwO0wAFnRocmVlRFNlY3VyZU1lcmNoYW50S

WRxAH4AAUwAA3hpZHEAfgABeHB0ACFZTkE2cWFpU28yZDBzb0FBZGtGTDdaZDEw

MTY0MTMyNThzcgARamF2YS51dGlsLkhhc2hNYXAFB9rBwxZg0QMAAkYACmxvYWR

GYWN0b3JJAAl0aHJlc2hvbGR4cD9AAAAAAAAMdwgAAAAQAAAABXQADXZlbmRvck

FwcE5hbWV0AAB0AAlzZXNzaW9uSWRxAH4ABHQADGRjY1JlcXVlc3RlZHQAAU50A

Ah2ZW5kb3JJZHB0ABB2ZW5kb3JBcHBWZXJzaW9ucQB

AAh4dAAKRU1QSS0wMDAwMXQAFDJFNDEzOUYzQkYuRDQxQjU5LVQx

(end)

6. Converge will validate the PaRes value sent and responds with the Issuer Authentication variables needed to complete the ccsale or ccauthonly transaction.

Note: This completes the third and final stage in the authentication process.

Converge Developer Guide: Additional Processing Options CON-0002-N

Shown below is an example of a PaRes verification request using processxml.do:

Step 3: Send a PaRes Verification request, include the PaRes and MD values received from

the issuer in step 2: xmldata=

<txn>

<ssl_merchant_id>my_virtualmerchant_id</ssl_merchant_id>

<ssl_user_id>my_user_id</ssl_user_id>

<ssl_pin>my_pin</ssl_pin>

<ssl_transaction_type>parequest</ssl_transaction_type>

<md>rO0ABXNyACZjb20ubm92YWluZm8uYWRhcHRlci5lbXBpLk1lcmNoYW50RGF

0YQAAAAAAAAABAgAETAACaWR0ABJMamF2YS9sYW5nL1N0cmluZztMAApwYXJhbW

V0ZXJzdAATTGphdmEvdXRpbC9IYXNoTWFwO0wAFnRocmVlRFNlY3VyZU1lcmNoY

W50SWRxAH4AAUwAA3hpZHEAfgABeHB0ACFZTkE2cWFpU28yZDBzb0FBZGtGTDda

ZDEwMTY0MTMyNThzcgARamF2YS51dGlsLkhhc2hNYXAFB9rBwxZg0QMAAkYACmx vYWRGYWN0b3JJAAl0aHJlc2hvbGR4cD9AAAAAAAAMdwgAAAAQAAAABXQADXZlbm

RvckFwcE5hbWV0AAB0AAlzZXNzaW9uSWRxAH4ABHQADGRjY1JlcXVlc3RlZHQAA

U50AAh2ZW5kb3JJZHB0ABB2ZW5kb3JBcHBWZXJzaW9ucQB

AAh4dAAKRU1QSS0wMDAwMXQAFDJFNDEzOUYzQkYuRDQxQjU5LVQx</md>

<pares> eJzFWMmSo8qS3ddXlNVbyrKYEVxTpVkwCIEUSCAmsbnGJECMYhDD1zfKrKzKV3

2trV9vWht5eES4H3ePODhsjKSJIuEcBX0TvW5g1LZeHH1Nwx/faq

J7n9HHhUEBM2 sASBvpA0hb8wjHd9wQIcw5k1g1Ek9u11cwJ61P7a1v4dYER49ejgJaJY9oUMmf

CF8cPwBV0H1wilInLNRMu2R9S0aVW Yt/R7/gG

RguOJog8crudeMFd05WXw9HHhz tuQN8lOxKaJGFl4tGUWxDfI

2JReEb12Udt9XXRvg01Q9WXXTK8MiW6Qj8Gmb/LXpOvqvxBkGIbvadlFTRl17V savgdVsUGeSzbIbyCn/im1i8kxDV9hZqLQgJR

U3k9pURV2PKqkXWWIP7YIM8Vm9DrolccxUiUwamvGPkXuv4LZzfIm37jFU8sy/ wC66e8qZ8uwKeJz4rNAq2JyuAjlI/RJhrrqoyeWzbIL3mD/MZbe Ur umHLb/F9qLdGM7rpkuLP3CyfxHLgjf9pu28rm9fLxvkp7QJvMfjFRryrAomrs4 xBQVxgrOGqbeAPBpgif9tySYK0leUWkAt/2

7QB5XTdolxRPqvys2yBMK8naMXjfnNC4XZ030dSzysv3x7VOtBuJ71cTIkh8UQ

VlkWRC2afyvb 7olAur9V/tI33yqpMAy9PZ69bTh

MuqQKv/7C9k9mDP1pCUN0kX9ZTL0EGFm PDUogVHfkE8R/G s/Qmqab2XNvGwpyE9ukbPQkdfTV3 8e1f/9H1EtJ4uQz/Fwgf7t8tWF7eR6 t7EQmcjhmhdGS1Y63O6rv2eSGMMNS888rN8gv2Iv8uy6f8vK

8MgnD8m/zFHL7ixZJmNWQCZvq9qlR3IeSZ/97LYyrxoj8rF/dE3hAtNjdGfpiE w9dNWxcgWv5hCG82B8KZ1c7c5YpnEFmumCpNc2IXCVJu7unsR6pVfHV9NvS5jt wMXDmxxvpxOXAbFQR53SS1cSc1q8YpKA6l YAFfbNUZNDHpXuK066S13PTVwp pkM5lg32UEKvMefEwJNM

7PYaLIX2ED79SOJkRZ1lx6NZJLeB1X/rAlCPixl9Q8igHV9Hr9dNIYI7onMeYs

3u9ss7MqmGvHpk/gCMw59W zUigY/4tqPQpZjQBP6xWYsPevlzn0aZUqzuY02N2

ZS3vMzZ3Vf3NSYAD/Z0RmWE9uPHe I/JXuzj6b3KizCT5V

Br8HsAr7fLnibW/50mVe16pEHLWgWgcH2j0B2bUjn8zxmjtCzzaK brzRR pHgCvsvKC7ZO4n6L8BuqjSis2oV8cDHw5dPKFd0taOHC6qnjBMZX4gETGncQmW i65dKAjJzZOS/HAFPI21df5jY6Q87xyD/qa6WkMVe9NJHT1Pf0iGToTT3RnWOA

0GSXcdUakOFe3G3gDczRXYFJNuvY1TGgdx2tEWV

(continued)

Converge Developer Guide: Additional Processing Options CON-0002-N

(end)

1W8/e5Fzd45aukHQ0CzFewlpFviTybmimqx01D7c3LWaJhgxDU6vB7aATdE6gD

FpqbHYyAgTLyEq8Y8keln1b5aWXDwUpCoiQVU1fIMKXU1p3kb7f10q5pUJrO8i ovartNiOu2E3AIHGXGGl4VuUjyxvxg6yBBrgNIv7m7n rCvJbdCiUFbzOe5f4qOnS68Jcy/MEyrJQCDwPKj4Gg8yBWNaBYuIPAqEOYszVC g44JzoX0mUQtIuyr1w5eQQq0MQtp4EhEMQDBJkEMFPkEshrqDiKAjhysWotxgw

OZftQ2k6ezYyiAU7v sDgRTbxCLf2pTGHejBstYtgadpeHCjFL/U8KKg83Kr5hbAm1xBNyMlvPvgRHnR pi17OnODaFBoU5igY4PBuFxqcZKmmmA27JFChAYajIC7P28twNETSfurmP3Q3j oVaO/Dv/iVxUATNEDUIyHd/HNwZOIVeHKX2Z1GHgHmPdYSygW bsMhbXzLH7QysdwyVIWT5ErM1

YWFmrh1Cx1liVEbxPjNx0EcOtF13NyX2MG3rT4URA9y8ZtdMELdNTHtfOY4DYO xbmOYv8TrE/IQx2IKASrx57t0ln1C0EQOaCYApMwJA3jO70G11FDjJ8pq3dupz

1A/oLjp1g2POmNAkrvUI3W8TCTH2j36KhO2 mOVMoKXnsObeZf4tULbkM9Iosr9cJtcTdCjSawU1wq2WxHN64GWL8p8Q8TAx7e

86Zb1uGMQnN8H2mO6xLay6

1TvWYPJyrrdo9p3Tgafu/II17cZVfdTcLhjqkmQJRjMESYSuYhWxBAOVkhl50m

BbgrOpt29c73SqbsWP64xmFqoo1rieWtXsOj4AVTRqzE

Mo/FNale7agdGcIWyPBMJ3PeNjtrnfnasznUMA1Vp0R20jjc2OL1RTRU2qHd4f

3EHM9pT/sMXO0LjBKre1YETo6ZDrjpPp17kxEiNjyZc1T5gw9iyAEg3WQBRBAM z3qF4iByyKDxEIBBeNZXR09A2yFLEQQQ2/Gf9eJ

1mupkX03t3bIMcrg7UakOWdlxQzuecYuRL70REZ7pFey7Tlr17mkBP7QptpLVh

LjT7d05lp1nKkDjgpHTY31gz7ZQTqToRrvj3KVmSmzonjysCK2ebsv7Lagdc6B

N9oLJOzSYgFisAXpEAGeBnWK3I7cQZCtU8fgu44SwtsNqNDFTxUjddo5x70h52 qMWteK3VissRLOxmpIekwb8KtWYCdZJiK5yGdNvukJJOi6MPupHXvYs

POSf1BXp7yqz58WOZcYL3tuw

GLjWKaTHpFJxa9cXMiBnzrAcDNpZqQVbUZiQ1OfhUcRC31IYtG9E/SIHeFUT/C owL/tjOseKBoe8QQdbm6dsBNcN8ifD/SPlxU/KK9IPytMkpBsa6NjaqsebZnc7

VKw2L0ng4uyeZOlyUdHnVdsCgRv P ji4uiJLKr5Qo1POlQhaD/oQnyjCwNE2wEdoQBIaGgDFExSFUJv0U1/6uAOjPwM lHf/FwNkKgf1n8dX02RxCE

LnyQo8gfUxUEY3vQ7cUhOF7vDPXtsFwwO5Mz3mBN4PC9U7DpK7zq64doq9qTlr

QDO7z5ag0f1JJTEWMMXutst8WnowL/bFcRBzw2LU5a6cPJ/y7m4BWB5h9MY8Jz n4/0ii4BkKm57uO6aNleg1NSEvVqVd3puVHYGVSk/HLJCfFnv

ZLNHgF2vxM6FgeZ2g9Nr1vZgfEMK8odcyq1x8wiYctLe55uHqVKYYWL2sOjZ6e

6OdioDIQZq yxokHMO2iiCPq5JERXZ1Li5CcPHCuJjjk4iBZq8fVmNOs1S/Cid11t9dJ aJUTlNK5qobz/tagEQ9DI4iUw02wrL4oZ2kX7ViJjsG9P5ME268SFFjTWIejrT thcee1CuCodL65u6SYDddSZM5A1JUbW4fBVqQrR2hAnC9FQ

KMc4eRtlLOHXIzpzqXqBQ7ojPwaFG5nQ5kN

/bY3m/WwqSOnxC7Vs19luerWDfuOlDW4ht6Siq8TJ81G6nL5R3XbpoAUhPWgOx yP0PlEa0TJykHZcIdMJHR3UdwnFJNJmNibHe9zp9JsneY jbvkTO1C5UUYi7pS/ZfHy1jSHLdhY3a3x62ZNmS yxNNuvOMNu4aVu

61jUgEpuTtUMo9WEAnqqqd44yYvQM7bsn

Ep4khRpZTee2UoKca7pCu16zQIYPjbRQIZqUISJrIJwEaTUI9m

4rPjtGzxP780nwDFs5N mRLJxBPqeZCCdrWDptnbxMsOtGYmXNHCOVow6DrLEhdehBo9l1d1Iq/HSpcWLt

ZA89PSAuagp1YI8EWl7y7tF4km8QEIz0Rd52e mK7O

XhxmcEmR1GJ0GW056qV8Z1NBjZN5btXetstNo8CbSJJL2D5SG/G7okF/N e

2/e37w9sHmef78ecPNf8FfxDQ0w== </pares>

</txn>

Converge Developer Guide: Additional Processing Options CON-0002-N

Receive a PaRes Verification response along with the 3D Secure authentication variables:

<txn>

<cavv>MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=</cavv>

</txn>

7. The merchant now has to include the ssl_eci_ind, ssl_3dsecure_value, and ssl_xid

values in the transaction request ccsale and ccauthonly sent to the converge gateway.

Note: There is a leading (0) in the ECI value returned from Converge in the second step. It must be removed prior to sending it to Converge.

8. The website processes Sale or Auth Only collecting the payment information along with

the 3D Secure variables obtained, using processxml.do. Refer to the Credit Card Sale

(ccsale)

and Credit Card Auth Only (ccauthonly) sections for more information.

Below is an example of a ccsale request with ssl_eci_ind, ssl_3dsecure_value, and ssl_xid

values obtained from the previous steps. xmldata=<txn>

<ssl_merchant_id>my_virtualmerchant_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>ccsale</ssl_transaction_type>

<ssl_card_number>0000000000000000</ssl_card_number>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_amount>1.00</ssl_amount>

<ssl_first_name>john</ssl_first_name>

<ssl_last_name>Doe</ssl_last_name>

<ssl_cvv2cvc2_indicator>1</ssl_cvv2cvc2_indicator>

<ssl_cvv2cvc2>789</ssl_cvv2cvc2>

<ssl_company>01</ssl_company>

<ssl_description>VBV Transaction</ssl_description>

<ssl_eci_ind>2</ssl_eci_ind>

<ssl_3dsecure_value>

MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=</ssl_3dsecure_value>

<ssl_xid>2C77797CAF.7392B4-T1</ssl_xid>

</txn>

Converge Developer Guide: Additional Processing Options CON-0002-N

9. Converge processes the transaction and returns a response to the website displaying the results. A 3D secure transaction will show in the batch with correct ECI indicator.

Transaction Format

The tables below define the transaction request and response data field elements when using processxml.do

for:

 Card Enrollment



Payer Authentication



Verify PaRes

Note: If you are using process.do to integrate to Converge, the authentication piece is built in and the authentication variables are passed for you. This section applies to processxml.do

only.

Step 1: Verify Card Enrollment Request

Input Field Name Req? Description

ssl_transaction_type Y Credit Card 3D Secure enrollment (paenrolled). ssl_merchant_id ssl_user_id

Converge ID as provided by Elavon.

Converge User ID as configured within Converge, case sensitive. ssl_pin ssl_card_number

Converge PIN as configured within Converge, case sensitive.

Credit Card Number as it appears on the credit card. Must be

Visa or MasterCard to be eligible. ssl_exp_date ssl_amount

Credit Card Expiry Date as it appears on credit card formatted as

MMYY.

Transaction Sale Amount. Number with 2 decimal places. This amount includes the Net amount and Sales Tax.

Converge Developer Guide: Additional Processing Options CON-0002-N

Verify Card Enrollment Response

Output Field Name Data Type

acs_Url 1-2048 ANS

Description

Cardholder issuer URL. The website must redirect the cardholder to this website in order to authenticate with 3D Secure. paReq enrolled

ANS

1 A

Encoded Payer Authentication Request.

Indicates whether the card can be authenticated, valid values are:

 N: The Issuer is not participating. Proceed to authorize the transaction with an with ECI set to 07 (Visa or JCB) or 01 (MC)



U: Unable to Authenticate: “U” is used whether the

Issuer’s inability to authenticate the account is due to technical difficulties or business reasons. Proceed to authorize the transaction with an ECI of 07 (Visa or JCB) or 01 (MC) or cancel the transaction.



Y: The card is enrolled and authentication is available.

Redirect the cardholder to the Issuer site for authentication. After the authentication Process, send request to eMPI to obtain the decrypted ECI/CAVV. md 0-1024 ANS Merchant Data. This is a unique reference to identify the 3D

Secure request is genuine and can be then matched up with

Elavon.

Step 2: The Payer Authentication Request

Input Field Name Req? Data Type

PaReq Y ANS

TermUrl md

Description

Encoded Payer Authentication Request.

1-2048 ANS The merchant URL to which the final reply must be posted. Fully qualified https URL.

0-1024 ANS Merchant Data. Recommend using request id.

The Payer Authentication Response

Output Field Name Data Type

PaRes ANS md

Description

Encoded Payer Authentication Response. The PARes message is sent by the ACS in response to the PAReq, regardless of whether authentication is successful. PaRes is a Signed XML

String which is Compressed and Base 64 Encoded returned by the Issuer.

0-1024 ANS Merchant Data.

Converge Developer Guide: Additional Processing Options CON-0002-N

Step 3: Verify PaRes Request

Input Field Name

ssl_transaction_type Y ssl_merchant_id

Y ssl_user_id Y

Req? Description

Credit Card 3D PaRes verification (parequest).

Converge ID as provided by Elavon.

Converge User ID as configured within Converge, case sensitive. ssl_pin

PaRes md

Converge PIN as configured within Converge, case sensitive.

Encoded Payer Authentication key

Verify PaRes Response

Input Field Name Data Type Description

result xID 28 ANS

Transaction verification result.

A response containing a value other than 0 for <result> represents non-authenticated transaction. Transaction should be cancelled; the merchant may proceed with ECI of 07 (Visa or JCB) though strongly discouraged.

Base 64 Encoded transaction ID.

CAVV 28 ANS eci 0-2 N

Cardholder Authentication Verification Value.

Note: Called UCAF for MasterCard. Universal Cardholder

Authentication Field



Base 64 Encoded (28 characters)

e-Commerce indicator. For a list of possible values, see the ECI

Codes section below

Converge Developer Guide: Additional Processing Options CON-0002-N

ECI Codes

The tables below define the ECI code field elements for:



Returned ECI Codes



ECI Codes to Send to Converge



Protection Status

Returned ECI Codes

ECI

Visa

N/A

MasterCard

MCSC has been attempted: Merchant is no longer protected from Chargeback.

Fully authenticated: There is a liability shift and the merchant is protected from chargebacks.

N/A 05

<blank>

Fully authenticated: There is a liability shift and the merchant is protected from chargebacks.

VbV has been attempted: There is a liability shift and the Merchant is protected from chargebacks.

Non-VbV transaction: Merchant is no longer protected from Chargebacks.

N/A

Non-MCSC transaction: Merchant is no longer protected from Chargebacks.

ECI Codes to Send to Converge

ECI (returned by Converge)

<blank>

ssl_eci_ind ssl_3DSecure_Value ssl_xid

CAVV Optional

Must contain CAVV

CAVV Optional

No CAVV

Must contain XID

XID optional

Converge Developer Guide: Additional Processing Options CON-0002-N

Transaction Examples

Example 1: process.do

Shown below are the key value pairs for a Sale transaction with 3D Secure enabled – No additional work is needed – authentication is automatic ssl_merchant_id=xxxxxx ssl_user_id=xxxxxxx ssl_pin=xxxxxx ssl_show_form=false ssl_card_number=0000000000000000 ssl_exp_date=1215 ssl_amount=1.00 ssl_error_url=http://www.url.com/cgi-bin/testtran.cgi ssl_result_format=HTML ssl_transaction_type=ccsale ssl_receipt_decl_method=REDG ssl_receipt_decl_get_url=http://www.url.com/cgi-bin/testtran.cgi ssl_receipt_apprvl_method=REDG ssl_receipt_apprvl_get_url=http://www.url.com/cgi-bin/testtran.cgi

Response below contains the ECI indicator of Fully Authenticated after consumer has been directed to the issuer website for verification – this is transparent to the merchant website:

<input type="hidden" name="ssl_txn_id" value="99C7884A-EDB6-4256-

BE69-4547B8859D5B">

<input type="hidden" name="ssl_eci_ind" value="Fully

Authenticated">

<br>

</form>

Converge Developer Guide: Additional Processing Options CON-0002-N

Example 2: processxml.do

Shown below is an example of a ccsale request with ssl_eci_ind, ssl_3dsecure_value, and ssl_xid values obtained from an integrated eMPI solution to indicate this 3D Secure qualified transaction: xmldata=<txn>

<ssl_merchant_id>my_virtualmerchant_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>ccsale</ssl_transaction_type>

<ssl_card_number>0000000000000000</ssl_card_number>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_amount>12000.00</ssl_amount>

<ssl_first_name>john</ssl_first_name>

<ssl_last_name>Doe</ssl_last_name>

<ssl_cvv2cvc2_indicator>1</ssl_cvv2cvc2_indicator>

<ssl_cvv2cvc2>789</ssl_cvv2cvc2>

<ssl_company>01</ssl_company>

<ssl_description>VBV Transaction</ssl_description>

<ssl_eci_ind>5</ssl_eci_ind>

<ssl_3dsecure_value>

MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=</ssl_3dsecure_value>

<ssl_xid>14FC923865.3B54A8-T1</ssl_xid>

</txn>

Converge Developer Guide: Additional Processing Options CON-0002-N

Receive a ccsale response (transaction will show in batch with correct ECI indicator)

<txn>

<ssl_card_number>00********0000</ssl_card_number>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_amount>1.00</ssl_amount>

<ssl_company>01</ssl_company>

<ssl_first_name>john</ssl_first_name>

<ssl_last_name>Doe</ssl_last_name>

<ssl_result>0</ssl_result>

<ssl_result_message>APPROVAL</ssl_result_message>

<ssl_txn_id>AA48439-14AE8D51-2A60-DFA5-15A2-

BD02D2FB08A5</ssl_txn_id>

<ssl_approval_code>CVI127</ssl_approval_code>

<ssl_cvv2_response>M</ssl_cvv2_response>

<ssl_avs_response/>

<ssl_account_balance>1.00</ssl_account_balance>

<ssl_txn_time>10/04/2011 10:09:11 AM</ssl_txn_time>

</txn>

MasterPass

Converge offers MasterPass as a service that enables consumers to check out on a merchant website using any MasterPass connected wallet. Cardholders store and manage their payment and shipment information at the MasterPass website, when they are ready to purchase goods, their information will be securely shared with the merchant website, speeding up the checkout process. Converge uses the Elavon eMPI engine to allow processing of MasterPass wallet transactions.

The following transactions types are supported when processing MasterPass transactions:

Transaction Types Description

ccsale Credit Card Sale ccauthonly Credit Card Auth Only

Notes:



The terminal must be setup under region Canada and market segment e-Commerce.



The terminal must be setup for MasterPass.



All card types are supported under the MasterPass wallet.

Converge Developer Guide: Additional Processing Options CON-0002-N

The following information is supported for MasterPass transactions:

Field Name

ssl_eWallet

Req? Description

C The wallet identifier , valid values: MasterPass

Note: Required for process.do(false) and processxml.do to indicate that the Cardholder has opted to pay using

MasterPass. For process.do(true) this value is sent automatically by the payment form when the Cardholder selects to pay using MasterPass. ssl_eWallet_shipping

N Wallet shipping option to indicate if the shipping address information used is retrieved from the MasterPass website or the merchant’s website. Default is N.

Valid values:



Y = Use the Shipping address stored in MasterPass



N = Use the Shipping address from the merchant website or payment form ssl_product_string N Product string. This is the list of products purchased at the merchant website. All products will be displayed as line item on

MasterPass site along with the total amount.

The product string have to be formatted as following: (Unit

Price:: Quantity: Description: Image URL|) of the product, several products can be provided, each separated by “|”. Converge will send a generic product string if not provided.

Example:

10.00::1::shirt::https://merchantwebsite/shirtpic.gif|22.00::1::pants:: https://merchantwebsite/pantspic.gif|15.00::1::hat::https://mercha ntwebsite/hatpic.gif|5.00::1::socks::https://merchantwebsite/socks pic.gif

Transaction Flow

Using process.do(true)

If you are using process.do with the payment form to integrate to Converge, there is no additional work required to use MasterPass, as the authentication piece is built in. The following steps outline the process of sending a MasterPass transaction with the payment form:

1. Cardholder purchases goods/services from the merchant website and clicks on the checkout page.

2. The integrated application/website sends a request using HTTPS POST for a Sale or Auth

Only request using the payment page.

Converge Developer Guide: Additional Processing Options CON-0002-N

Shown below are the key value pairs from the header by themselves for a credit card

Auth Only transaction indicating that the shipping address as stored in the ewallet is supported. ssl_merchant_id=xxxxxx ssl_user_id=xxxxxxx ssl_pin=xxxxxx ssl_show_form=true ssl_transaction_type=ccauthonly ssl_amount=100.00 ssl_eWallet_shipping=Y

Notes:



Do not send ssl_eWallet_shipping if shipping information is to be collected at the merchant website or the payment page

 ssl_eWallet_shipping

value is ignored if the Cardholder opted to pay with credit card

3. The Merchant website redirects the Cardholder to the Converge payment page.

4. Cardholder is presented with a choice to enter a credit card number or select the

MasterPass wallet by clicking on the MasterPass logo located in the payment page above the card number. The Cardholder selects to pay with the MasterPass wallet.

5. Cardholder is redirected automatically to the MasterPass website. Cardholder completes the authentication process by logging to their MasterPass wallet and selecting payment information.

6. Cardholder is redirected back to the payment page.

7. Payment page displays the card information with billing and shipping information.

Cardholder confirms payment.

8. Converge processes the transaction and returns a response to the website displaying the results.

Converge Developer Guide: Additional Processing Options CON-0002-N

Using process.do(false)

If you are using process.do without the payment form to integrate to Converge, you must send the card information or indicate that the Cardholder is opting to pay using the MasterPass wallet.

The MasterPass wallet logo must display in your website.

1. Cardholder purchases goods/services from the merchant website and clicks on the checkout page

2. The integrated application/website sends a Sale or Auth Only request using HTTPS POST

indicating that the Cardholder is using a MasterPass wallet. Refer to Credit Card Sale

(ccsale)

or Credit Card Auth Only (ccauthonly) sections for the list of recommended

fields.

Shown below are the key value pairs from the header by themselves for a credit card sale transaction indicating that the Cardholder has opted to pay using the MasterPass wallet and the shipping address will be retrieved from the ewallet profile (optional): ssl_merchant_id=xxxxxx ssl_user_id=xxxxxxx ssl_pin=xxxxxx ssl_show_form=false ssl_transaction_type=ccsale ssl_amount=100.00 ssl_eWallet_shipping=Y ssl_eWallet= MasterPass

3. Cardholder is redirected automatically to the MasterPass website. Cardholder completes the authentication process by logging to their MasterPass wallet and selecting payment information.

4. Converge processes the transaction and returns a response to the website displaying the results.

Using processxml.do

If you are using processxml.do to integrate to Converge, you must provide the choice to the cardholder to pay using a credit card or a MasterPass wallet, the MasterPass logo must be displayed in the website. The following steps outline the process of sending a MasterPass transaction with processxml.do:

1. Cardholder purchases goods/services from the merchant website and chooses to pay using MasterPass wallet on the checkout page.

2. The integrated application/website sends an XML formatted Sale or Auth Only request using processxml.do using HTTPS POST indicating that the Cardholder is using a

MasterPass wallet and providing a call back URL. Refer to Credit Card Sale (ccsale) or

Credit Card Auth Only (ccauthonly) sections for recommended fields.

Converge Developer Guide: Additional Processing Options CON-0002-N

Shown below is an example of the XML request for a credit card Sale transaction indicating that the Cardholder has opted to pay using the MasterPass wallet and the shipping address will be selected from the ewallet profile (optional): xmldata=<txn>

<ssl_merchant_id>my_virtualmerchant_id</ssl_merchant_id>

<ssl_user_id>my_user</ssl_user_id>

<ssl_pin>my_pin</ssl_pin>

<ssl_transaction_type>ccsale</ssl_transaction_type>

<ssl_amount>10.00</ssl_amount>

<ssl_eWallet>MasterPass</ssl_eWallet>

<ssl_product_string>1.00::1::T-Shirt::Image

URL</ssl_product_string>

<ssl_eWallet_shipping>Y</ssl_eWallet_shipping>

<ssl_callback_url>https://www.merchantwebsite.com/payments/r esponse.do</ssl_callback_url>

</txn>

3. Converge will send a request to MasterPass.

4. MasterPass responds with a token and a URL.

Shown below is an example of the XML request:

<txn>

<id>rsz9cfRaLPGYU1azyT5mp8Z1016413257</id>

<oauth_token>40f3dab23aeb9c4f484192acb294d2cd</oauth_token>

<redirectURL>https://sandbox.masterpass.com/Checkout/Authoriz e?oauth_token=40f3dab23aeb9c4f484192acb294d2cd&acceptable_car ds=master&checkout_identifier=a4a6x1yrgh71dhgw5g9d31hh3uali82 xcm&version=v3&suppress_shipping_address=true</redirectURL>

</txn>

Note: There is a 15-minute window given for the merchant to use the token and redirect the Cardholder to MasterPass.

5. Merchant redirects the Cardholder Browser to the Authorize URL and uses the Request

Token.

6. Cardholder completes the authentication process by logging to their MasterPass wallet and selecting card, billing, and shipping information.

7. MasterPass redirects the Cardholder Back to the Merchant Call back URL with an access token and a session id.

Converge Developer Guide: Additional Processing Options CON-0002-N

Shown below is an example of the data posted back to the merchant: osessionId=rsz9cfRaLPGYU1azyT5mp8Z1016413257 showform=false merchantId=EMPI-00012 xid=2C102E7F0D.C234D7-T1 oauth_token=40f3dab23aeb9c4f484192acb294d2cd oauth_verifier=8cc86efa1f6c3483a23c32a02b7beb33 checkout_resource_url=https://sandbox.api.mastercard.com/online/ v3/checkout/2036737

8. Merchant uses the session id and sends the access token back to Converge.

Shown below is an example of the XML request:

<txn>

<osessionId>rsz9cfRaLPGYU1azyT5mp8Z1016413257</osessionId>

<oauth_token>40f3dab23aeb9c4f484192acb294d2cd </oauth_token>

<oauth_verifier>8cc86efa1f6c3483a23c32a02b7beb33</oauth_veri fier>

<checkout_resource_url> https://sandbox.api.mastercard.com/online/v3/checkout/203673

7</checkout_resource_url>

</txn>

9. Converge sends the access token to MasterPass through and obtains the credit card number, expiration date, billing and shipping information.

10. Converge processes the transaction and returns a response to the merchant website displaying the results.

Converge Developer Guide: Additional Processing Options CON-0002-N

Transaction Examples

Example 1: process.do

Shown below is an example of a ccsale request with wallet indicator, shipping will be provided by the MasterPass wallet along with the card information: ssl_amount" value=5.00 ssl_merchant_id" value=my_virtualmerchant_id ssl_user_id" value=my_user_id ssl_pin" value=my_pin ssl_transaction_type=ccsale ssl_show_form" value=false ssl_eWallet_shipping=Y ssl_eWallet= MasterPass ssl_invoice_number=123-ABC ssl_result_format" value="HTML ssl_receipt_decl_method=REDG ssl_receipt_decl_get_url=http://www.website.com/decline.asp ssl_receipt_apprvl_method=REDG ssl_receipt_apprvl_get_url=http://www.website.com/approval.asp

Converge Developer Guide: Additional Processing Options CON-0002-N

Example 2: process.do

Send a ccauthonly request with wallet indicator, shipping will be provided by the merchant: ssl_amount" value=5.00 ssl_merchant_id" value=my_virtualmerchant_id ssl_user_id" value=my_user_id ssl_pin" value=my_pin ssl_transaction_type=ccauthonly ssl_show_form" value=false ssl_invoice_number=123-ABC ssl_eWallet_shipping=N ssl_eWallet= MasterPass ssl_ship_to_address1=999 Main ssl_ship_to_last_name=Doe ssl_ship_to_first_name=Jane ssl_ship_to_city=Any City ssl_ship_to_zip=99999 ssl_ship_to_state=GA ssl_result_format" value="HTML ssl_receipt_decl_method=REDG ssl_receipt_decl_get_url=http://www.website.com/decline.asp ssl_receipt_apprvl_method=REDG ssl_receipt_apprvl_get_url=http://www.website.com/approval.asp

Example 3: process.do

Send a Sale transaction with the payment page, billing and shipping will be provided by the

MasterPass wallet along with the card information – No additional work is needed ssl_amount" value=5.00 ssl_merchant_id" value=my_virtualmerchant_id ssl_user_id" value=my_user_id ssl_pin" value=my_pin ssl_transaction_type=ccsale ssl_show_form" value=true ssl_eWallet_shipping=Y ssl_invoice_number=123-ABC ssl_result_format" value="HTML ssl_receipt_decl_method=REDG ssl_receipt_decl_get_url=http://www.website.com/decline.asp ssl_receipt_apprvl_method=REDG ssl_receipt_apprvl_get_url=http://www.website.com/approval.asp

Converge Developer Guide: Additional Processing Options CON-0002-N

Dynamic Currency Conversion (DCC)

Converge uses Elavon conversion tools to process Dynamic Currency Conversion (DCC) for merchants. The merchant is pricing in USD or CAD, but when the card is entered and is determined to be DCC eligible, Cardholder is then given a choice to pay with their currency

(foreign); this agreed currency becomes the transaction currency, regardless of the merchant’s pricing currency. Cardholder accepts to pay with their local currency and the conversion rates associated with it:



Merchant price, sell, authorize, settle and is funded in one single currency (The merchant currency USD or CAD)

 Cardholders are prompted for a choice to pay in their local currency (foreign)

The following transactions types are supported when processing DCC transactions:

Transaction Types Description

ccsale

Credit Card Sale ccauthonly Credit Card Auth Only ccforce cccredit

Credit Card Force

Credit Card Credit/Refund

Notes:



The terminal must be setup for DCC.



DCC is supported with MasterCard and Visa transactions only. Other card types will process as normal and will not trigger DCC processing.



The conversion is triggered when the card is swiped or entered, and rates will be presented for any of the following currencies: US Dollar, Canadian Dollar, Pound Sterling,

Australian Dollar, Euro and Japanese.

The process of dynamic currency is to retrieve the rates and pass the following DCC Transaction variables:

Field Name Req? Description

ssl_txn_currency_code Y The cardholder’s Billing Currency. ssl_markup Y The Mark-up applied to the Reference Exchange Rate when calculating the Exchange Rate used to convert from the merchant’s Pricing Currency to the cardholder’s Billing

Currency. ssl_conversion_rate

Y ssl_cardholder_amount Y

Exchange rates applied to the conversion of the transaction amount.

The transaction amount in the cardholder’s Billing Currency

Converge Developer Guide: Additional Processing Options CON-0002-N

Transaction Flow

Using process.do

If you are using process.do to integrate to Converge, there is no additional work required to process DCC, as the conversion piece is built and Cardholders are presented with the choice to pay in their currency, the DCC variables are then passed for you. The following steps outline the process of sending a DCC transaction with process.do:

1. The website or Point of Sale (POS) application processes Sale, Auth Only, or Force transactions and collects the payment information using process.do. Refer to the

Credit Card Sale (ccsale) ,

(ccforce) sections for more information.

, or Credit Card Force

2. Cardholder enters or swipes a Visa or MasterCard card at the checkout.

3. Converge will determine if the card is a foreign card. If the card is determined to be foreign the website or POS is redirected automatically to the DCC choice page

4. The DCC choice page displays the rate, the markup percentage, the merchant amount, and the card holder amount.

5. Cardholder decides in what currency the transaction is processed in.

6. Converge processes the transaction and returns a response to the website displaying the results with conversion rates and amounts agreed on.

Notes:



There is a 15-minute window given to the Cardholder to opt for an option



If you are using process.do and ssl_result_format field is set to ASCII, the flow of the transaction will be similar to processxml.do outlined below.

Using processxml.do

If you are using processxml.do to integrate to Converge, you must provide the choice to the cardholder to accept or decline the DCC service and display all relevant information to make an informed decision. The following steps outline the process of sending a DCC transaction with processxml.do

1. The website or POS application processes Sale, Auth Only, or Force transactions and

collects the payment information using process.do. Refer to the Credit Card Sale

(ccsale) ,

, or Credit Card Force (ccforce) sections

for more information.

2. Cardholder enters or swipes a Visa or MasterCard card at the checkout.

3. Converge will determine if the card is a foreign card

Converge Developer Guide: Additional Processing Options CON-0002-N

4. Converge will return a decision response providing a transaction ID, rates, markup, and currency information.

5. The website or POS application displays the option to the cardholder with the information returned by Converge

6. The Cardholder makes a choice at the website or POS application : a) If the Cardholder opted to process in home currency, the website or POS application sends the Transaction ID for that transaction with DCC option value of Y. b) If the Cardholder opted to process in merchant currency, the website or POS application sends the Transaction ID for that transaction with DCC option value of N.

7. Converge processes the transaction and returns a response to the website displaying the results with conversion rates and amounts agreed on.

Note: There is a 15-minute window given to allow the website or POS application to send the option.

Transaction Examples

Example 1: process.do

Send a ccsale request ssl_amount" value=5.00 ssl_merchant_id" value=my_virtualmerchant_id ssl_user_id" value=my_user_id ssl_pin" value=my_pin ssl_transaction_type=ccsale ssl_show_form" value=false ssl_invoice_number=123-ABC ssl_card_number=0000000000000000 ssl_exp_date=1215 ssl_result_format" value="HTML ssl_receipt_decl_method=REDG ssl_receipt_decl_get_url=http://www.website.com/decline.asp ssl_receipt_apprvl_method=REDG ssl_receipt_apprvl_get_url=http://www.website.com/approval.asp

Converge Developer Guide: Additional Processing Options

Receive a DCC decision Page

The customer must select one of the buttons to continue to process the transaction.

CON-0002-N

Example 2: processxml.do

Send a ccsale request xmldata=<txn>

<ssl_merchant_id>my_virtualmerchant_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>ccsale</ssl_transaction_type>

<ssl_card_number>0000000000000000</ssl_card_number>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_amount>1.00</ssl_amount>

</txn>

Converge Developer Guide: Additional Processing Options CON-0002-N

Receive a DCC decision response xmldata=<txn>

<id>ekU9j0L0iFO9m9FELAqK8E6</id>

<ssl_txn_currency_code>EUR</ssl_txn_currency_code>

<ssl_markup>3.25</ssl_markup>

<ssl_conversion_rate>.76373</ssl_conversion_rate>

<ssl_amount>1.00</ssl_amount>

<ssl_cardholder_amount>0.76</ssl_cardholder_amount> <dccoption>

</dccoption>

</txn>

Cardholder accepts DCC and second request sent requesting card to be charged in foreign

currency xmldata=<txn>

<ID>ekU9j0L0iFO9m9FELAqK8E6</ID>

</txn>

Receive a final response and print receipt xmldata=<txn>

<ssl_card_number>00********0000</ssl_card_number>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_amount>1.00</ssl_amount>

<ssl_cardholder_amount>0.76</ssl_cardholder_amount>

<ssl_cardholder_currency>EUR</ssl_cardholder_currency>

<ssl_conversion_rate>.76373</ssl_conversion_rate>

<ssl_markup>3.25</ssl_markup>

<ssl_invoice_number />

<ssl_result>0</ssl_result>

<ssl_result_message>APPROVAL</ssl_result_message>

<ssl_txn_id>101641221295DB876-F2A9-7B6A-B173-

2737983B7693</ssl_txn_id>

<ssl_approval_code>N05465</ssl_approval_code>

<ssl_txn_time>01/20/2011 01:05:44 PM</ssl_txn_time>

</txn>

Converge Developer Guide: Additional Processing Options CON-0002-N

Cardholder declines DCC and second request sent requesting card to be charged in

Developer currency xmldata=<txn>

<ID>iQ4AezhcjmJznh3BYLZ0-W9</ID>

</txn>

Receive a final response xmldata=<txn>

<ssl_card_number>00********0000</ssl_card_number>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_amount>1.00</ssl_amount>

<ssl_result>0</ssl_result>

<ssl_result_message>APPROVAL</ssl_result_message>

<ssl_txn_id>101641221593ACBA6-BAFD-76B7-4948-

B3DE68CFD0CC</ssl_txn_id>

<ssl_approval_code>CMC142</ssl_approval_code>

<ssl_account_balance>1.00</ssl_account_balance>

<ssl_txn_time>01/20/2011 01:07:23 PM</ssl_txn_time>

</txn>

Send a ccsale with tip request xmldata=<txn>

<ssl_merchant_id>my_virtualmerchant_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>CCSALE</ssl_transaction_type>

<ssl_amount>10.00</ssl_amount>

<ssl_tip_amount>2.00</ssl_tip_amount>

<ssl_track_data>%B00**********0000^ELAVONTEST/TESTCARD^151290154321

3961456789123456789001?;00**********0000=151290154321396?</ssl_trac k_data>

</txn>

Converge Developer Guide: Additional Processing Options CON-0002-N

Receive a response showing Cardholder base, Tip and Total amounts after customer opted

to pay in DCC

<txn>

<ssl_approval_code>CVI045</ssl_approval_code>

<ssl_cvv2_response/>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_server/>

<ssl_cardholder_amount>9.52</ssl_cardholder_amount>

<ssl_result_message>APPROVAL</ssl_result_message>

<ssl_markup>3.25</ssl_markup>

<ssl_tip_amount>2.00</ssl_tip_amount>

<ssl_base_amount>10.00</ssl_base_amount>

<ssl_amount>12.00</ssl_amount>

<ssl_txn_id>AA4843B-893BE162-0F1A-4DF5-9076-

D93CB9421914</ssl_txn_id>

<ssl_result>0</ssl_result>

<ssl_card_number>00**********0000</ssl_card_number>

<ssl_cardholder_tip_amount>1.59</ssl_cardholder_tip_amount>

<ssl_cardholder_base_amount>7.94</ssl_cardholder_base_amount>

<ssl_cardholder_currency>EUR</ssl_cardholder_currency>

<ssl_txn_time>10/08/201211:57:25PM</ssl_txn_time>

<ssl_conversion_rate>.79362</ssl_conversion_rate>

</txn>

Update tip in Cardholder amount (Cardholder leaves a tip on a DCC transaction) xmldata=<txn>

<ssl_merchant_id>my_virtualmerchant_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>CCUPDATETIP</ssl_transaction_type>

<ssl_cardholder_tip_amount>3.00</ssl_cardholder_tip_amount>

<ssl_txn_id>AA4843B-893BE162-0F1A-4DF5-9076-

D93CB9421914</ssl_txn_id>

</txn>

Converge Developer Guide: Additional Processing Options CON-0002-N

Receive a final response

<txn>

<ssl_result_message>SUCCESS</ssl_result_message>

<ssl_tip_amount>3.78</ssl_tip_amount>

<ssl_base_amount>10.00</ssl_base_amount>

<ssl_amount>13.78</ssl_amount>

<ssl_cardholder_tip_amount>3.00</ssl_cardholder_tip_amount>

<ssl_cardholder_base_amount>7.94</ssl_cardholder_base_amount>

<ssl_cardholder_amount>10.94</ssl_cardholder_amount>

<ssl_cardholder_currency>EUR</ssl_cardholder_currency>

<ssl_conversion_rate>.79362</ssl_conversion_rate>

<ssl_txn_id>AA4843B-893BE162-0F1A-4DF5-9076-

D93CB9421914</ssl_txn_id>

<ssl_txn_time>10/08/201211:57:25PM</ssl_txn_time>

</txn>

Receipt Requirements

Receipt Requirements for VISA

All Environments (Face-to-Face, MOTO, e-Commerce)

 The price of the goods or services in the merchant’s home currency, accompanied by the currency symbol or code next to the amount.



The total price in the transaction currency accompanied by the words Transaction

Currency and the currency symbol or code next to the amount.



The exchange rate used to convert the total price from the merchant’s home currency to the transaction currency.



Any mark-up or commission included in the exchange rate as an amount or a percentage.

This information may be shown as a separate line item or in the disclosure verbiage on the transaction receipt.



An I accept check box that indicates the cardholder’s acceptance of the currency conversion.



A statement in an area easily seen by the cardholder that states that DCC is offered by the merchant.

Converge Developer Guide: Additional Processing Options CON-0002-N

Receipt Requirements for MasterCard

All Environments (Face-to-Face, MOTO, e-Commerce)



Pre-conversion currency and amount.



Conversion rate or method.



Post-conversion currency and amount.



A prescribed statement, “I have chosen not to use the MasterCard currency conversion method and I will have no recourse against MasterCard concerning currency conversion or its disclosure.”

Special Requirements for Internet, Cardholder Activated Terminals and ATMs

 Screen messages at unattended point of sale terminals must not require the cardholder to select Yes or No when choosing currency conversion. Indirect means, such as the colors red and green, must not be used to influence the cardholder’s choice.

 At attended point of sale terminals that require the cardholder to choose between Yes and No, the merchant must verbally explain the offer to the cardholder before presenting it on the point of sale terminal.

Converge Developer Guide: Additional Processing Options CON-0002-N

Receipt Example

Merchant Copy

Header1

FRIENDLY TERMINAL

XXXXXXXXXXXXXXXXXXXXX

Date: 11/04/2010 11:07:30 AM

CREDIT CARD SALE

CARD DATA: **********0002 S

TRANSACTION CURRENCY: JPY

CONVERSION RATE: 85.05321

CONVERSION MARKUP: 3.25%

MERCHANT AMOUNT: $2.00 USD

TRANSACTION AMOUNT: ¥170.00 JPY

APPROVAL CD: N19586

CLERK ID: my_merchant_id

RECORD #: 001

I HAVE BEEN OFFERED THE CHOICE OF CURRENCIES FOR

PAYMENT INCLUDING THE MERCHANT'S LOCAL CURRENCY. MY

DECISION TO ACCEPT CURRENCY CONVERSION ON THIS

TRANSACTION IS FINAL. I ACCEPT THE RATE OF

CONVERSION,(INCLUSIVE OF CONVERSION FEE 3.25%), FINAL

AMOUNT, AND THAT THE FINAL SETTLED TRANSACTION

CURRENCY IS {JPY}.

I UNDERSTAND THAT VISA HAS A CURRENCY CONVERSION

PROCESS, AND THAT I HAVE CHOSEN NOT TO USE THE VISA

CURRENCY CONVERSION PROCESS. CURRENCY CONVERSION IS

CONDUCTED BY THE MERCHANT AND IS NOT ASSOCIATED

WITH OR ENDORSED BY VISA.

I AGREE TO THE TRANSACTION RECEIPT INFORMATION BY

MARKING THE ACCEPT BOX BELOW.

[ ] I ACCEPT

X____________________________________

JPY STANDARD VI

Trailer1

Merchant Copy

Customer Copy

Header1

FRIENDLY TERMINAL

XXXXXXXXXXXXXXXXXXXXX

Date: 11/04/2010 11:07:30 AM

CREDIT CARD SALE

CARD DATA: **********0002 S

TRANSACTION CURRENCY: JPY

CONVERSION RATE: 85.05321

CONVERSION MARKUP: 3.25%

MERCHANT AMOUNT: $2.00 USD

TRANSACTION AMOUNT: ¥170.00 JPY

APPROVAL CD: N19586

CLERK ID: my_merchant_id

RECORD #: 001

I HAVE BEEN OFFERED THE CHOICE OF CURRENCIES FOR

PAYMENT INCLUDING THE MERCHANT'S LOCAL CURRENCY.

MY DECISION TO ACCEPT CURRENCY CONVERSION ON THIS

TRANSACTION IS FINAL. I ACCEPT THE RATE OF

CONVERSION,(INCLUSIVE OF CONVERSION FEE 3.25%), FINAL

AMOUNT, AND THAT THE FINAL SETTLED TRANSACTION

CURRENCY IS {JPY}.

I UNDERSTAND THAT VISA HAS A CURRENCY CONVERSION

PROCESS, AND THAT I HAVE CHOSEN NOT TO USE THE VISA

CURRENCY CONVERSION PROCESS. CURRENCY CONVERSION

IS CONDUCTED BY THE MERCHANT AND IS NOT ASSOCIATED

WITH OR ENDORSED BY VISA.

Trailer1

Customer Copy

Converge Developer Guide: Additional Processing Options CON-0002-N

Multi-Currency Conversion (MCC)

Multi-Currency processing allows the merchant to sell their products and services in a variety of currencies but receive their funding from Elavon in just one currency. Multi-Currency payment solutions help merchants offer enhanced customer service, and attract more international customers.

This feature is beneficial to those merchants who have websites targeted to a particular audience or demographic in a country other than their own. Examples:



A US merchant has a website targeted to Europe, which displays prices and processes payments in Euros (EUR), payments are then cleared in a US bank account in USD.



A Canadian merchant has a website targeted to customers from Australia; it processes transactions in Australian Dollars (AUD) and deposits the payments to a Canadian domiciled bank account in CAD.

Elavon supports almost a hundred different transaction currencies (refer to the ISO Currency

Codes section) for both MasterCard and Visa payments. Transaction amounts are converted from

the submission currency to the funding currency on your merchant account, utilizing the exchange rates provided by Elavon’s designated currency exchange desk provider.

The following transactions types are supported when processing Multi-Currency transactions:

Transaction Types Description

ccsale Credit Card Sale ccauthonly Credit Card Auth Only ccforce cccredit ccimport

Credit Card Force

Credit Card Return/Credit

A Batch file of credit card transactions

Notes:

 The terminal must be setup for Multi-Currency.

 Once a terminal is setup for Multi-Currency, the terminal can process by default the following currencies: US Dollar (USD), Canadian Dollar (CAD), Pound Sterling (GBP),

Australian Dollar (AUD), Euro (EUR) and Japanese (YEN). You can add or remove currencies in the Converge user interface.



Multi-Currency is supported with MasterCard and Visa transactions only. Other card types cannot be sent with a transaction other than merchant currency: USD or CAD.



Manual settlement is not allowed for those terminals setup for Multi-Currency.

Converge Developer Guide: Additional Processing Options CON-0002-N

Transaction Flow

To process a transaction as Multi-Currency, simply pass the 3 character ISO currency code in the ssl_transaction_currency

field along with the ssl_amount, if the transaction currency is not specified, it is assumed to be the same as the merchant domestic currency (USD or CAD).

The following steps outline the process of sending a Multi-Currency transaction:

1. The website/POS application quotes the customer a price in the variety of currencies the merchant accepts.



Currency Conversion is done by the Merchant on the Merchant Website



Merchant price, sell, authorize, and settle in variety of currencies

2. Cardholder keys or swipes a Visa or MasterCard card at the checkout.

3. The integrated application/website processes Sale, Auth Only, Refund, or Force transactions and collects the payment information using process.do or processxml.do

or a batch import using processBatch.do. Refer to Credit Card Sale

(ccsale) ,

, or Credit Card Force (ccforce) ,

Credit

Card Return Credit (cccredit) , or

Credit Card Batch Import (ccimport) sections for more information.

4. The integrated application/website sends the transaction with the amount and the transaction currency along with the transaction data using HTTPS, either by the HTTPS

POST. Shown below are the key value pairs from the header by themselves for a credit card sale transaction processed in EUR: ssl_merchant_id=xxxxxx ssl_user_id=xxxxxxx ssl_pin=xxxxxx ssl_show_form=false ssl_transaction_type=ccsale ssl_card_number=0000000000000000 ssl_exp_date=1214 ssl_amount=100.00 ssl_transaction_currency=EUR

Converge Developer Guide: Additional Processing Options CON-0002-N

5. Converge processes the transaction and returns a response to the website displaying the results with the transaction currency.

Notes:

 Merchant is funded in one single currency (The merchant currency USD or CAD).

 Do not send transaction currency if adjustment to the original transaction is needed; cccomplete, ccvoid, ccupdatetip or ccreturn will carry the original transaction currency.



When specifying amounts, be sure to submit the correct number of decimal places for the transaction currency. All currencies support two exponents

(decimals,) other than the following:

BHD

JOD

KWD

LYD

OMR

TND

Currency Code Currency Name

JPY Japanese Yen

KRW

XAF

XOF

XPF

South Korean Won

Gabon Franc

Ivory Coast Franc

French Polynesian Franc 0

Exponents

Bahraini Dinar

Jordanian Dinar

Kuwaiti Dinar

Libyan Dinar

Omani Rial

Tunisian Dinar



For Japanese Yen, there are no currency exponents after the decimal place. Any numbers included after the decimal place will be ignored.



For the Bahraini Dinar, there are 3 possible digits after the decimal place. Your website may wish to take advantage of the precision this audience of customers will expect. However, currently the Converge will accommodate only 2 decimals.

If you submit three, it will automatically round your transaction to two decimals.

(for example: 1.235 will round to 1.23 and 1.236 will round to 1.24).

Converge Developer Guide: Additional Processing Options CON-0002-N

Transaction Examples

Example 1: process.do

Send a ccsale request ssl_merchant_id" value=my_virtualmerchant_id ssl_user_id" value=my_user_id ssl_pin" value=my_pin ssl_transaction_type=ccsale ssl_amount" value=200 ssl_transaction_currency=JPY ssl_show_form =false ssl_invoice_number=123-ABC ssl_card_number=0000000000000000 ssl_exp_date=1215 ssl_result_format" value="HTML ssl_receipt_decl_method=REDG ssl_receipt_decl_get_url=http://www.website.com/decline.asp ssl_receipt_apprvl_method=REDG

The following XML code example demonstrates the initiation of a Sale transaction with currency: xmldata=<txn>

<ssl_merchant_id>my_virtualmerchant_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>ccsale</ssl_transaction_type>

<ssl_card_number>0000000000000000</ssl_card_number>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_amount>200</ssl_amount>

<ssl_transaction_currency>JPY</ssl_transaction_currency>

</txn>

Converge Developer Guide: Additional Processing Options CON-0002-N

Receive a final response and print receipt xmldata=<txn>

<ssl_card_number>00********0000</ssl_card_number>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_amount>200</ssl_amount>

<ssl_transaction_currency>JPY</ssl_transaction_currency>

<ssl_result>0</ssl_result>

<ssl_result_message>APPROVAL</ssl_result_message>

<ssl_txn_id>AA47AE-BD32FF54-BE12-4046-98E9-

F78E9D75212D</ssl_txn_id>

<ssl_approval_code>N05465</ssl_approval_code>

<ssl_txn_time>11/19/2013 12:02:29 AM</ssl_txn_time>

</txn>

Tokenization

The following section provides the guidelines on how to obtain tokens and use them to process transactions with your integrated application.

Tokenization is a powerful security feature that allows a merchant to support all of their existing business processes that require card data without the risk of holding card data and without any security implications therefore protecting the customers' confidential information; because tokens are useless to criminals, they can be saved by the merchant as they do not represent any threat, the liability and costs associated with PCI compliance is substantially reduced and the risk of storing sensitive data is eliminated. Tokenization applies to credit card and gift card.

Merchants set up for the tokenization service receive responses that include a token. The token generated is not linked to a specific transaction but to a specific card number and the token generated for that transaction will be identical for every use of that card number and merchant.

Furthermore, you can generate a token and save the token with associated information in the

Card Manager.

Card manager enables merchants to tokenize and store their customers' sensitive payment information on our secure servers, simplifying their PCI DSS compliance as well as the payments process for returning customers. The Card Manager will allow you access to all tokens that have been previously generated from your integrated application or directly added to your integrated application. The Card Manager can be only accessed directly from the user interface and will give you the ability to search for a token previously added, add a card number, and process transactions.

Converge Developer Guide: Additional Processing Options CON-0002-N

Use Cases may include the following scenarios:

1. Generate tokens using credit or gift card numbers:



Requesting token only.



Requesting token after validating the card.



Processing a transaction and requesting a token.

2. Generate tokens using existing recurring transactions:



Requesting token only.



Processing a recurring/installment transaction and requesting a token.

3. Store tokens from credit cards in the Card Manager after token generation.

4. Process transactions using tokens:

 Providing the token, expiration date and billing information.

 Providing the token only and Converge will use the stored information in the Card

Manager to send the expiration date and billing information for you. Applicable to credit cards only at this time.

Notes:



Tokens replace credit or gift card numbers.



The terminal must be enabled to accept tokenization.



Tokens are unique for each merchant, for example: the same card will produce a different token for each merchant.



Tokens match the format of the initiating PAN and do not overlap major brand (Visa, MC,

AMEX, and Discover) BIN ranges (first digit is 0-2 or 7-9) and share last four digits with corresponding PAN.



Merchants with multiple terminals sharing tokenization domains will receive the same token for a unique card and the token can be used across their stores if they wish to do so.



Merchants may supply the token in place of card information in any subsequent transaction.



Card Manager can be accessed from the user interface.



Tokenization is supported for both credit cards and gift cards. Adding a token to the Card

Manager using integration is supported only when sending a Credit Card Number.

Converge Developer Guide: Additional Processing Options CON-0002-N

Generating Tokens

There are two ways to generate a token:

1. Performing an authorization (process.do, processxml.do, or processBatch.do) either:



An authorization with the Generate Token indicator of Y by itself will authorize the transaction and generate a token. You must pass either a card number for a handkeyed transaction, a track data for a swiped transaction, tlv chip data for EMV transaction or recurring ID for recurring/ installment transactions.



An authorization with the Add to Card Manager Indicator of Y by itself will authorize the transaction, generate a token, and add the token to the Card Manager. Adding to the Card Manager is applicable to credit cards only. To add a gift card you must use the user interface.

The following transactions are supported when requesting a token at the authorization time:

Transaction Types

ccsale ccauthonly ccforce cccredit ccbalinquiry emvchipsale

Description

Credit Card Sale

Credit Card Auth Only

Credit Card Force

Credit Card Return/Credit

Credit Card Balance Inquiry

EMV Chip Sale emvswipesale ccimport

EMV Chip Sale

A Batch file of credit card transactions ccrecurringsale Submit Recurring Payment ccinstallsale Submit Installment Payment egcactivation egcsale

Gift Card Activation

Gift Card Sale egcbalinquiry Gift Card Balance Inquiry egcreload egccredit

Gift Card Reload

Gift Card Credit

Converge Developer Guide: Additional Processing Options CON-0002-N

All transactions requests sent to Converge must pass the following basic information:

Field Name

[Card Data] ssl_amount ssl_get_token ssl_add_token ssl_first_name ssl_last_name ssl_avs_zip ssl_avs_address

Req? Description

Y Refer to Card Data Elements table for list of card data required to generate a token.

Transaction Amount.

Generate Token indicator must be sent in order to generate tokens only. Valid values: Y (generate a token), N (do not generate token). Defaulted to N.

Add to Card Manager indicator, must be sent in order to indicate that the token needs to generated and added to the

Card Manager. Valid values: Y (add token) , N (do not add token). Defaulted to N.

Add token to card manager is not supported with ccimport, it is also not supported with Gift Card transactions.

Required with Add to Card Manager indicator.

Cardholder first name.

Required with Add to Card Manager indicator.

Cardholder last name.

Required with Add to Card Manager indicator.

Customer ZIP Code.

Required with Add to Card Manager indicator.

Customer Billing Address.

Card Data Elements:

Field Name

ssl_card_number ssl_exp_date

Req? Description

C Required when generating token from handkeyed transactions.

Credit Card Number or Gift Card Number as it appears on the card.

C Required when generating token from handkeyed transactions.

Expiration date.

Converge Developer Guide: Additional Processing Options CON-0002-N

Field Name

ssl_track_data ssl_tlv_enc ssl_enc_track_data ssl_encrypted_track1_data ssl_encrypted_track2_data ssl_recurring_id

Req? Description

C Required when generating token from swiped or contactless transactions.

The raw track I and/or II data from the magnetic strip on the credit or gift card. The track data captured from the swipe device cannot be manipulated and must be passed at the time of the transaction. This includes the beginning and ending sentinels that are included in the drack data. Raw track data cannot be stored under any circumstance.

Expiration date is included with track data. First and last name of the Cardholder is also included with the Track I data

Required when generating token from Chip transactions

Encrypted Tag Length Value data defining this

EMV record.

C Required for generating token using swiped or contactless (MSD) card from an Ingenico encrypting device.

This is the entire encrypted Track data combined into a single cipher text that was extracted from the Ingenico encrypting device.

Required for generating token using swiped or contactless (MSD) card from a Magtek encrypting reader.

This is the encrypted Track 1 data extracted from the Magtek device.

Required for generating token using swiped or contactless (MSD) card from a Magtek encrypting reader.

This is the encrypted Track 2 data extracted from the Magtek device.

Required when generating token from recurring or installment transactions.

The ID number of the recurring record or installment record to be submitted for payment. This value was returned in the recurring ID when the original recurring record was added for recurring or installment ID when the original installment was added for installment. Alphanumeric.

Converge Developer Guide: Additional Processing Options CON-0002-N

2. Performing a token generation request (process.do, processxml.do, or processBatch.do

The following transactions are supported when requesting a token without authorization:

Transaction Types Description

ccgettoken cctokenimport

Credit Card Generate Token

A Batch file of Credit Card information egcgettoken Gift Card Generate Token

Token generation can request account verification along with the token to be added to the Card Manager.



A Token generation request by itself will generate a token from a credit or gift card number or recurring ID.



A Token generation request with card verification flag will validate if the credit card is valid along with CVV and AVS then generate the token.



A token generation request with the Add to Card Manager indicator will generate a token from a card number or recurring ID and add it the token to the card manager, this functionality is not available with gift card transactions using the integration. To add a gift card to the card manager you must use the user interface.



A token generation request with Account Verification indicator will perform a check on the card along with CVV and AVS, if supplied, prior to generating a token.



A token generation request with Card Verification Flag and Add to Card Manager will validate if the Credit Card Number is valid along with CVV and AVS , generate the token, then add it to the card manager.

All transactions with token generation requests sent to Converge must pass the following basic information:

Field Name

ssl_card_number ssl_exp_date

Req? Description

Required for hand-keyed transactions.

Credit Card Number or Gift Card Number as it appears on the card.

Required for hand-keyed transactions.

Expiration date.

Converge Developer Guide: Additional Processing Options CON-0002-N

Field Name

ssl_recurring_id ssl_enc_track_data

Req? Description

Required for recurring or installment transactions.

The ID number of the recurring record or installment record to be submitted for payment.

This value was returned in the recurring ID when the original recurring record was added for recurring or installment ID when the original installment was added for installment.

Alphanumeric.

Required for generating token using swiped or contactless (MSD) card from an Ingenico encrypting device.

This is the entire encrypted Track data combined into a single cipher text that was extracted from the

Ingenico encrypting device. ssl_encrypted_track1_data C

Required for generating token using swiped or contactless (MSD) card from a Magtek encrypting reader.

This is the encrypted Track 1 data extracted from the Magtek device. ssl_encrypted_track2_data C ssl_ksn C

Required for generating token using swiped or contactless (MSD) card from a Magtek encrypting reader.

This is the encrypted Track 2 data extracted from the Magtek device.

Required when sending track data from an encrypting device for payment cards.

The Key Serial Number generated from the swiped payment card, this is the value returned by the encrypting device. This value is used to encrypt the

PAN data, using the Derived Unique Key Per

Transaction (DUKPT) method. It is a 10 byte composite field that is transmitted as 20 alphanumeric character fixed length. ssl_verify N

Verification indicator must be sent in order to verify the card for CVV and AVS checks.

Applicable to credit cards only. ssl_add_token

N Add to Card Manager indicator, must be sent in order to indicate that the token needs to be added to the Card Manager.

Applicable to credit cards only.

Converge Developer Guide: Additional Processing Options CON-0002-N

Field Name

ssl_first_name ssl_last_name ssl_avs_zip ssl_avs_address ssl_cvv2cvc2

Req? Description

C Required with Add to Card Manager indicator.

Cardholder first name.

Applicable to credit cards only.

Required with Add to Card Manager indicator.

Cardholder last name.

Applicable to credit cards only.

Required with Add to Card Manager indicator, optional for verification.

Customer ZIP Code.

Applicable to credit cards only.

Required with Add to Card Manager indicator, optional for verification.

Customer Billing Address.

Applicable to credit cards only.

CVV2/CVC/CID in the field. Optional for verification.

Applicable to credit cards only.

All token generation requests with or without authorization will return the following fields:

Field Name

ssl_token

Description

The token value generated from the card number. This value can be stored and used as a substitute for a card number. ssl_token_response Outcome of the token generation. This value will be a SUCCESS if a token has been generated. Other possible returned values are FAILURE, Action Not Permitted, Invalid Token, Not

Permitted, Acct Verification Failed. ssl_add_token_response Outcome of the Add to Card Manager request, examples: Card

Added, Card Updated, Not Permitted, FAILURE - First Name - is required. ssl_result Outcome of the transaction if the token generation was requested with verification or with an authorization. A response that contains ssl_result of 0 represents an Approved transaction. A response containing any other value for ssl_result

represents a Declined transaction preventing it

from being authorized. Refer to the Authorization Response

Codes section for an extensive list of possible returned

messages.

Converge Developer Guide: Additional Processing Options CON-0002-N

Field Name

ssl_result_message ssl_avs_response ssl_cvv2_response

Description

The transaction result message. Example: APPROVAL. Refer to

the Authorization Response Codes section for an extensive list

of possible returned messages.

The Address Verification Response Code if an AVS was passed

(refer to the AVS Response Codes section for a complete list of

AVS response codes).

The Card Verification Response Code if a CVV was passed (refer

to the CVV2/CVC2 Response Codes section for a complete list

of CVV/CVC2 response codes)

Processing Transactions Using Tokens

The following transactions are supported when processing transactions using tokens for a Credit

or Gift Card Number:

Transaction Types

ccsale ccauthonly ccforce cccredit ccbalinquiry ccimport ccaddrecurring ccaddinstall egcactivation egcsale egcbalinquiry egcreload egccredit

Description

Credit Card Sale

Credit Card Auth Only

Credit Card Force

Credit Card Return/Credit

Credit Card Balance Inquiry

A Batch file of credit card transactions

Add Credit Card Recurring

Add Credit Card Installment

Gift Card Activation

Gift Card Sale

Gift Card Inquiry

Gift Card Reload

Gift Card Credit

Converge Developer Guide: Additional Processing Options CON-0002-N

All credit and gift card transactions sent with tokens to Converge must pass the following basic cardholder information:

Field Name

ssl_token Y ssl_exp_date

Req? Description

Credit or Gift Card Token previously generated from a card number. ssl_amount Y

Expiration date. Required if the token is not in the Card Manager. If the token has been previously stored in the Card Manager, expiration date should not be sent.

Transaction Amount. Number with 2 decimal places. The authorized amount passed on request should not contain the tip amount, tips must be passed separately. The total authorized amount will be calculated during the authorization if tip is provided. For example: 1.00.

Notes:



The Card Manager feature is not available with gift card transactions using the integration. To add a gift card to the Card Manager you must use the user interface.



When tokens are stored in the Card Manager, the token number can be sent alone ,

Converge will grab the Billing information and the Cardholder first and last name and send them with the transaction.



The more cardholder information passed during authorization, the better. Tokens are substitute to card numbers and adhere to the same rules as a hand keyed transactions.

Refer to Credit Card Sale (ccsale) ,

Credit Card Return Credit (cccredit) ,

, or Credit Card

Force (ccforce) ,

Credit Card Batch Import

(ccimport)

, Gift Card Activation (egcativation) ,

Gift Card Sale/Redemption

(egcsale) ,

Gift Card Balance Inquiry (egcbalinquiry) ,

Gift Card Replenishment/Reload

(egcreload)

, or Gift Card Credit (egccredit) sections for more information.

 Tokens are substitute to card numbers and adhere to the same rules as a hand keyed transactions

Converge Developer Guide: Additional Processing Options CON-0002-N

Managing Stored Tokens

Once stored, tokens from a Credit Card can be located, modified or deleted. The following transactions are used to manage stored tokens in the card manager:

Transaction Types Description

ccquerytoken Credit Card Token Query ccupdatetoken ccdeletetoken

Credit Card Token Update

Credit Card Token Delete

Note: Only those tokens that belong to a credit card number can be managed using the integration. Tokenized gift cards cannot be added, modified, or deleted using integration.

Transaction Flow

1. Submit a transaction request to generate a token or a standard authorization with the

Generate Token indicator by using HTTPS POST with the values shown in the API

Reference Chapter in this guide in order to generate a token in the response. If you wish to store the token with billing information in the card manager, you must set the ssl_add_token

to Y. The request can be submitted on a single transaction or a batch file of transactions.

Shown below are the key value pairs from the header by themselves for a Generate Token request only: ssl_merchant_id=xxxxxx ssl_user_id=xxxxxxx ssl_pin=xxxxxx ssl_show_form=false ssl_transaction_type=ccgettoken ssl_card_number=0000000000000000 ssl_exp_date=1215 ssl_result_format=HTML ssl_receipt_decl_method=REDG ssl_error_url=http://www.url.com/cgi-bin/testtran.cgi ssl_receipt_decl_get_url=http://www.url.com/cgibin/testtran.cgi ssl_receipt_apprvl_method=REDG ssl_receipt_apprvl_get_url=http://www.url.com/cgibin/testtran.cgi

Converge Developer Guide: Additional Processing Options CON-0002-N

Shown below are the key value pairs from the header by themselves for a Generate Token request with card verification: ssl_merchant_id=xxxxxx ssl_user_id=xxxxxxx ssl_pin=xxxxxx ssl_show_form=false ssl_transaction_type=ccgettoken ssl_card_number=0000000000000000 ssl_exp_date=1215 ssl_verify=Y ssl_cvv2cvc2=123 ssl_avs_address=123 Main St ssl_avs_zip=01234 ssl_result_format=HTML ssl_receipt_decl_method=REDG ssl_error_url=http://www.url.com/cgi-bin/testtran.cgi ssl_receipt_decl_get_url=http://www.url.com/cgibin/testtran.cgi ssl_receipt_apprvl_method=REDG ssl_receipt_apprvl_get_url=http://www.url.com/cgibin/testtran.cgi

Converge Developer Guide: Additional Processing Options CON-0002-N

Shown below are the key value pairs from the header by themselves for a Generate Token request with card verification and Add to Card Manager Indicator: ssl_merchant_id=xxxxxx ssl_user_id=xxxxxxx ssl_pin=xxxxxx ssl_show_form=false ssl_transaction_type=ccgettoken ssl_card_number=0000000000000000 ssl_exp_date=1215 ssl_verify=Y ssl_cvv2cvc2=123 ssl_avs_address=123 Main St ssl_avs_zip=01234 ssl_add_token=Y ssl_first_name=John ssl_last_name=Doe ssl_result_format=HTML ssl_receipt_decl_method=REDG ssl_error_url=http://www.url.com/cgi-bin/testtran.cgi ssl_receipt_decl_get_url=http://www.url.com/cgibin/testtran.cgi ssl_receipt_apprvl_method=REDG ssl_receipt_apprvl_get_url=http://www.url.com/cgibin/testtran.cgi

Converge Developer Guide: Additional Processing Options CON-0002-N

Shown below are the key value pairs from the header by themselves for a sale transaction requesting a token: ssl_merchant_id=xxxxxx ssl_user_id=xxxxxxx ssl_pin=xxxxxx ssl_show_form=false ssl_transaction_type=ccsale ssl_card_number=0000000000000000 ssl_exp_date=1214 ssl_cvv2cvc2=123 ssl_avs_address=123 Main St ssl_avs_zip=01234 ssl_get_token=Y ssl_amount=1.00 ssl_error_url=http://www.url.com/cgi-bin/testtran.cgi ssl_result_format=HTML ssl_receipt_decl_method=REDG ssl_receipt_decl_get_url=http://www.url.com/cgibin/testtran.cgi ssl_receipt_apprvl_method=REDG ssl_receipt_apprvl_get_url=http://www.url.com/cgibin/testtran.cgi

Converge Developer Guide: Additional Processing Options CON-0002-N

Shown below are the key value pairs from the header by themselves for a sale transaction requesting a token and Add to Card Manager Indicator: ssl_merchant_id=xxxxxx ssl_user_id=xxxxxxx ssl_pin=xxxxxx ssl_show_form=false ssl_transaction_type=ccsale ssl_card_number=0000000000000000 ssl_exp_date=1214 ssl_cvv2cvc2=123 ssl_avs_address=123 Main St ssl_avs_zip=01234 ssl_get_token=Y ssl_add_token=Y ssl_first_name=John ssl_last_name=Doe ssl_amount=1.00 ssl_error_url=http://www.url.com/cgi-bin/testtran.cgi ssl_result_format=HTML ssl_receipt_decl_method=REDG ssl_receipt_decl_get_url=http://www.url.com/cgibin/testtran.cgi ssl_receipt_apprvl_method=REDG ssl_receipt_apprvl_get_url=http://www.url.com/cgibin/testtran.cgi

2. When Converge receives this post, it starts to parse the data to look for a few key fields first. It validates the ssl_merchant_id, ssl_user_id, and ssl_pin to authenticate the user.

Note: User ID (ssl_user_id) and PIN (ssl_pin) are case sensitive.

3. If the supplied information is invalid, an error is returned that states that the information is invalid. If the data is valid, Converge continues to validate the other supplied information such as the card number, expiration date, amount of the transaction, type of transaction, address information, and other custom data fields that are passed. Other fields that are passed with transactions states how the transactions should be handled from a communications standpoint.

Converge Developer Guide: Additional Processing Options CON-0002-N

4. These fields are: ssl_error_url=http://www.url.com/cgi-bin/testtran.cgi ssl_result_format=HTML ssl_receipt_decl_method=REDG ssl_receipt_decl_get_url=http://www.url.com/cgi-bin/testtran.cgi ssl_receipt_apprvl_method=REDG ssl_receipt_apprvl_get_url=http://www.url.com/cgibin/testtran.cgi ssl_show_form=false

Note: You can indicate in the error URL field where you would like Converge to send all the errors that are encountered. Any response that is not approved or declined will be sent to the URL specified.

5. By specifying the http://www.url.com/cgi-bin/testtran.cgi url in the ssl_error_url field for the redirect for the transaction above, for example, the following error is returned if one of the credentials in the request is invalid: errorCode=4025 errorName=Invalid Credentials errorMessage=The credentials supplied in the authorization request are invalid

6. By specifying the http://www.url.com/cgi-bin/testtran.cgi url in the ssl_apprvl_get_url field for the redirect for the transaction above, the following values are returned for the approved transaction:

Shown below are the key value pairs from a successful generate token transaction: ssl_result=0 ssl_token=8848842356063003 ssl_token_response=SUCCESS ssl_card_number=00**********0000

Converge Developer Guide: Additional Processing Options CON-0002-N

Shown below are the key value pairs from a successful token generation with card verification transaction: ssl_result=0 ssl_token=8848842356063003 ssl_token_response=SUCCESS ssl_card_number=00**********0000 ssl_result_message=APPROVAL ssl_txn_id=AA47AE-4B3FEED3-055E-4D4B-A67B-2AFBC235B925 ssl_approval_code=CVI368 ssl_cvv2_response=A ssl_avs_response=M ssl_txn_time=01/14/2014 11:13:51 AM

Shown below are the key value pairs from a successful generate token with card verification transaction and Add to Card Manager: ssl_result=0 ssl_add_token_response=Card Added ssl_token=8848842356063003 ssl_token_response=SUCCESS ssl_card_number=00**********0000 ssl_result_message=APPROVAL ssl_txn_id= AA47AE-B183DD7B-209D-4A8E-8CB6-749E1B750944 ssl_approval_code=N46032 ssl_cvv2_response=A ssl_avs_response=M ssl_txn_time=02/15/2014 13:12:35 AM ssl_avs_address=123 Main St ssl_avs_zip=01234 ssl_first_name=John ssl_last_name=Doe

Converge Developer Guide: Additional Processing Options CON-0002-N

Shown below are the key value pairs from an approved sale transaction: ssl_card_number=00**********0000 ssl_exp_date=0515 ssl_amount=1.00 ssl_get_token=Y ssl_token=8138827982163003 ssl_token_response=SUCCESS ssl_result=0 ssl_result_message=APPROVAL ssl_txn_id=AA776F-1981E7F3-907D-44F1-93BC-48D52F8CC2DF ssl_approval_code=N44032 ssl_cvv2_response=A ssl_avs_response=M ssl_account_balance=0.00 ssl_txn_time=02/17/2014 08:44:43 AM

7. By specifying the http://www.url.com/cgi-bin/testtran.cgi url in the ssl_receipt_decl_get_url field for the redirect for the transaction above, the following values are returned for when token has failed to be returned: ssl_result=1 ssl_token= ssl_token_response=FAILURE

8. Store the value of ssl_token obtained from successful transaction to use for any consecutive requests.

Converge Developer Guide: Additional Processing Options CON-0002-N

Shown below are the key value pairs from the header by themselves for a credit card sale transaction using a token: ssl_merchant_id=xxxxxx ssl_user_id=xxxxxxx ssl_pin=xxxxxx ssl_show_form=false ssl_transaction_type=ccsale ssl_token=8128827982163003 ssl_exp_date=1215 ssl_avs_zip=70004 ssl_avs_address=123 Main St ssl_first_name=John ssl_last_name=Doe ssl_amount=1.00 ssl_result_format=HTML

Shown below are the key value pairs from the header by themselves for a credit card sale transaction using a token previously stored in the Card Manager. ssl_merchant_id=xxxxxx ssl_user_id=xxxxxxx ssl_pin=xxxxxx ssl_show_form=false ssl_transaction_type=ccsale ssl_token=8128827982163003 ssl_amount=1.00 ssl_result_format=HTML

Converge Developer Guide: Additional Processing Options CON-0002-N

Transaction Examples

Example 1: process.do

In this example, the HTML code demonstrates the initiation of a token generation request with minimal information, the Cardholder will have to enter the card number and expiration date in the payment form and request the card to be added on file for later use: ssl_merchant_id" value=my_virtualmerchant_id ssl_user_id" value=my_user_id ssl_pin" value=my_pin ssl_transaction_type=ccgettoken ssl_show_form=true ssl_invoice_number=123-ABC ssl_result_format" value="HTML ssl_receipt_decl_method=REDG ssl_receipt_decl_get_url=http://www.website.com/decline.asp ssl_receipt_apprvl_method=REDG ssl_receipt_apprvl_get_url=http://www.website.com/approval.asp

Converge Developer Guide: Additional Processing Options CON-0002-N

Example 2: process.do

The following HTML code show an example of a request to generate a token after performing

CVV and AVS check on card. Once the verification is preformed successfully a token will be generated: ssl_merchant_id" value=my_virtualmerchant_id ssl_user_id" value=my_user_id ssl_pin" value=my_pin ssl_transaction_type=ccgettoken ssl_verify=Y ssl_card_number=0000000000000000 ssl_exp_date=1215 ssl_cvv2cvc2=123 ssl_avs_address=123 Main St ssl_avs_zip=01234 ssl_show_form=false ssl_invoice_number=123-ABC ssl_result_format" value="HTML ssl_receipt_decl_method=REDG ssl_receipt_decl_get_url=http://www.website.com/decline.asp ssl_receipt_apprvl_method=REDG ssl_receipt_apprvl_get_url=http://www.website.com/approval.asp

Converge Developer Guide: Additional Processing Options CON-0002-N

Approved Receipt

This generates a receipt that includes the following code for a successful token generation with verification:

This is your Receipt<br><br>

…

…

<input type="hidden" name="ssl_txn_id" value="99C7884A-EDB6-

4256-BE69-4547B8859D5B">

</form> ssl_receipt_decl_get_url=http://www.website.com/decline.asp ssl_receipt_apprvl_method=REDG ssl_receipt_apprvl_get_url=http://www.website.com/approval.asp

Converge Developer Guide: Additional Processing Options CON-0002-N

Decline Receipt

The result could be a form that includes the following code for a declined transaction due to verification failure; a token will not be generated:

<b>An Error Occurred</b><br><br>

Number: 1<br>

Message: This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.<br>

<input type="hidden" name="ssl_txn_id" value="B6637C93-CA38-

41C5-951A-C995BFFBD708">

<br>

</form>

Converge Developer Guide: Additional Processing Options CON-0002-N

Approved Receipt

This generates a receipt that includes the following key value pairs for an approved transaction: ssl_card_number=00**********0000 ssl_exp_date=0515 ssl_amount=3.33 ssl_get_token=Y ssl_customer_code= ssl_salestax=1.00 ssl_token=8138827982163003 ssl_token_response=SUCCESS ssl_result=0 ssl_result_message=APPROVAL ssl_txn_id=AA776F-1981E7F3-907D-44F1-93BC-48D52F8CC2DF ssl_approval_code=N44032 ssl_cvv2_response= ssl_avs_response= ssl_account_balance=0.00 ssl_txn_time=03/22/2013 05:44:43 AM

Example 2: processxml.do

The following XML code example demonstrates the initiation of a basic token generation request and response.

Initial 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>ccgettoken</ssl_transaction_type>

<ssl_card_number>0000000000000000</ssl_card_number>

<ssl_exp_date>1222</ssl_exp_date>

<ssl_avs_address>7300</ssl_avs_address>

<ssl_avs_zip>12345</ssl_avs_zip>

<ssl_verify>N</ssl_verify>

</txn>

Converge Developer Guide: Additional Processing Options CON-0002-N

Response Receipt

<txn>

<ssl_result>0</ssl_result>

<ssl_token_response>SUCCESS</ssl_token_response>

<ssl_token>7876275006683003</ssl_token>

</txn>

Example 3: processxml.do

The following XML code example demonstrates the initiation of a token generation with card verification request and response.

Initial 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>ccgettoken</ssl_transaction_type>

<ssl_card_number>0000000000000000</ssl_card_number>

<ssl_exp_date>1222</ssl_exp_date>

<ssl_avs_address>7300</ssl_avs_address>

<ssl_avs_zip>12345</ssl_avs_zip>

<ssl_verify>Y</ssl_verify>

</txn>

Response Receipt

<txn>

<ssl_transaction_type>ccgettoken</ssl_transaction_type>

<ssl_result>0</ssl_result>

<ssl_token_response>SUCCESS</ssl_token_response>

<ssl_token>7876275006683003</ssl_token>

<ssl_result_message>SUCCESS</ssl_result_message>

<ssl_avs_response>A<ssl_avs_response>

<ssl_cvv2_response>M</ssl_cvv2_response>

</txn>

Converge Developer Guide: Additional Processing Options CON-0002-N

Example 4: processxml.do

The following XML code example demonstrates the initiation of a sale transaction with a token 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>ccsale</ssl_transaction_type>

<ssl_card_number>0000000000000000</ssl_card_number>

<ssl_exp_date>1222</ssl_exp_date>

<ssl_cvv2cvc2_indicator>1</ssl_cvv2cvc2_indicator>

<ssl_cvv2cvc2>321</ssl_cvv2cvc2>

<ssl_amount>12.00</ssl_amount>

<ssl_avs_address>7300</ssl_avs_address>

<ssl_avs_zip>12345</ssl_avs_zip>

<ssl_get_token>Y</ssl_get_token>

</txn>

Response Receipt

<txn>

<ssl_approval_code>CVI194</ssl_approval_code>

<ssl_dynamic_dba/>

<ssl_exp_date>1222</ssl_exp_date>

<ssl_server />

<ssl_account_balance>12.00</ssl_account_balance>

<ssl_token>7876275006683003</ssl_token>

<ssl_get_token>Y</ssl_get_token>

<ssl_result_message>APPROVAL</ssl_result_message>

<ssl_token_response>SUCCESS</ssl_token_response>

<ssl_base_amount>12.00</ssl_base_amount>

<ssl_amount>12.00</ssl_amount>

<ssl_txn_id>AA4843B-0E98A88D-6923-4A77-B546-

38CFDDCE4DA4</ssl_txn_id>

<ssl_result>0</ssl_result>

<ssl_card_number>00**********0000</ssl_card_number>

<ssl_txn_time>03/26/2013 02:50:56 PM</ssl_txn_time>

<ssl_avs_response>S</ssl_avs_response>

<ssl_cvv2_response>M</ssl_cvv2_response>

</txn>

Converge Developer Guide: Additional Processing Options CON-0002-N

Example 5: processxml.do

The following XML code example demonstrates how to initiate a sale transaction, request a token and have it stored in the Card Manager: 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>ccsale</ssl_transaction_type>

<ssl_amount>10.00</ssl_amount>

<ssl_card_number>0000000000000000</ssl_card_number>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_invoice_number>1234</ssl_invoice_number>

<ssl_first_name>John</ssl_first_name>

<ssl_last_name>Doe</ssl_last_name>

<ssl_avs_address>123 Main</ssl_avs_address>

<ssl_city>Atlanta</ssl_city>

<ssl_state>GA</ssl_state>

<ssl_avs_zip>30123</ssl_avs_zip>

<ssl_country>USA</ssl_country>

<ssl_cvv2cvc2_indicator>1</ssl_cvv2cvc2_indicator>

<ssl_cvv2cvc2>123</ssl_cvv2cvc2>

<ssl_get_token>Y</ssl_get_token>

<ssl_add_token>Y</ssl_add_token>

</txn>

Converge Developer Guide: Additional Processing Options

Response Receipt

<txn>

<ssl_approval_code>CVI371</ssl_approval_code>

<ssl_cvv2_response>M</ssl_cvv2_response>

<ssl_add_token_response>Card Added</ssl_add_token_response>

<ssl_account_balance>10.00</ssl_account_balance>

<ssl_token>7098165265161885</ssl_token>

<ssl_token_response>SUCCESS</ssl_token_response>

<ssl_result_message>APPROVAL</ssl_result_message>

<ssl_invoice_number>1234</ssl_invoice_number>

<ssl_amount>10.00</ssl_amount>

<ssl_txn_id>AA4843B-0E213944-FEBA-4841-ADEA-

8804C127AB3</ssl_txn_id>

<ssl_result>0</ssl_result>

<ssl_card_number>00**********0000</ssl_card_number>

<ssl_txn_time>02/18/2014 04:06:41 PM</ssl_txn_time>

<ssl_avs_response>D</ssl_avs_response>

<ssl_invoice_number>1234</ssl_invoice_number>

<ssl_first_name>John</ssl_first_name>

<ssl_last_name>Doe</ssl_last_name>

<ssl_avs_address>123 Main</ssl_avs_address>

<ssl_city>Atlanta</ssl_city>

<ssl_state>GA</ssl_state>

<ssl_avs_zip>30123</ssl_avs_zip>

<ssl_country>USA</ssl_country>

</txn>

CON-0002-N

Converge Developer Guide: Additional Processing Options CON-0002-N

Since the token is now stored in the card manager, any consecutive Sale request can be easily done by sending tokens: 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>ccsale</ssl_transaction_type>

<ssl_amount>10.00</ssl_amount>

<ssl_token>7098165265161885</ssl_token>

</txn>

If the token is not stored in the card manager, you must send expiration data and billing information with the Sale 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>ccsale</ssl_transaction_type>

<ssl_amount>10.00</ssl_amount>

<ssl_token>7098165265161885</ssl_token>

<ssl_exp_date>1215</ssl_exp_date>

<ssl_first_name>John</ssl_first_name>

<ssl_last_name>Doe</ssl_last_name>

<ssl_avs_address>123 Main</ssl_avs_address>

<ssl_city>Atlanta</ssl_city>

<ssl_state>GA</ssl_state>

<ssl_avs_zip>30123</ssl_avs_zip>

<ssl_country>USA</ssl_country>

</txn>

Converge Developer Guide: Additional Processing Options CON-0002-N

Encryption

Developers can use process.do or processxml.do to process encrypted swiped, contactless or chip credit card, swiped gift card, or swiped loyalty card transactions using an encrypting device. The transaction sent to processxml.do is formatted in XML syntax and includes all supported transaction elements nested between one beginning and ending element <txn>, the transaction sent to process.do is formatted in key value pairs. EMV is only supported using processxml.do

Swiped transactions should be submitted with encrypted track data using a supported MagTek

(MagneSafe TM ) or an Ingenico device (with the Generic TDES DUKPT Encryption scheme) to maximize data protection instead of the standard track data. The encryption is delivered inside the read head closest to the magnetic stripe. This adds an additional layer of protection to the

HTTPS POST request. The following device types are supported for encrypting swipe data:



MagTek readers using MagneSafe encryption delivering track 1 and track 2 (separately), example: BulleT, iDynamo, uDynamo, aDynamo, Dynamag. These devices support swipe only.



Ingenico devices using Generic TDES DUKPT Encryption scheme, combining both track(s) into a single cipher text block, example: iSC250, iCMP (iCM122) Mobile PIN Pad or ROAM devices. These devices support swipe, chip read and contactless.

Notes:



You must download the appropriate SDK for each device type to enable the card reader to communicate with your software.



The SDKs for MagTek can be found at http://www.magtek.com

by selecting the

Programming Tools link under the Support section.

 The SDKs for Ingenico can be found at http://develper.ingenico.us/ , you must register in order to access resources.

 Only encrypted swipe data is supported at this time, hand-key transactions must provide non-encrypted card and expiration date.

Converge Developer Guide: Additional Processing Options CON-0002-N

The following transaction types are supported when submitting encrypted swiped transactions:

Transaction Types

ccsale ccauthonly emvchipsale emvchipauthonly emvswipesale EMV Swipe Sale emvswipeauthonly EMV Swipe Auth Only ccforce cccredit

Credit Card Force

Credit Card Credit/Refund ccbalinquiry ccgettoken

Credit Card Inquiry

Credit Card Generate Token egcsale egcactivation egccardrefund egcreload

Gift Card Sale

Gift Card Activation

Gift Card Refund

Gift Card Reload egcbalinquiry

Description

Credit Card Sale

Credit Card Auth Only

EMV Chip Sale

EMV Chip Auth Only egccredit egcgettoken ltenrollment ltredeem ltreturn ltaddpoints ltinquiry

Gift Card Inquiry

Gift Card Credit

Gift Card Generate Token

Loyalty Card Enrollment

Loyalty Card Redemption

Loyalty Card Return

Loyalty Card Add Points

Loyalty Card Balance Inquiry ltleadinquiry ltmemberinquiry

Loyalty Card Lead Inquiry

Loyalty Card Member Inquiry

Converge Developer Guide: Additional Processing Options CON-0002-N

All authorizations sent from an encrypting device must pass the following required information.

For a complete listing of all recommended fields please refer to the Credit Card Transactions ,

Gift

Card Transactions

, or Loyalty Card Transactions sections:

Field Name

ssl_merchant_id ssl_user_id ssl_pin ssl_transaction_type

Req? Description

Converge ID as provided by Elavon.

Converge user ID as configured on Converge (case sensitive).

Must be passed, the Merchant Admin (MA) user ID cannot be used.

Converge PIN as generated within Converge (case sensitive). It is strongly recommended that your user PIN is 32 or 64 characters long.

For example, the transaction type of (ccsale) to process a credit card sale or transaction type of (ccauthonly) to process a credit card sale. ssl_vm_mobile_source Y ssl_ksn

[Card Data] ssl_pos_mode ssl_entry_mode

Required for all encrypting devices.

The mobile source of the transaction, supported values are:



BBERRY: For all BlackBerry mobile devices

 ADROID: For all Android mobile devices



ITUNES: For all Apple mobile devices (iPhone/iPod/iPad)



WIN8: for all windows WIN8 based devices.



NOMOB: for non-mobile devices (PC or MAC)

Required for all encrypting devices for payment cards.

The Key Serial Number generated from the swiped payment card, this is the value returned by the encrypting device. This value is used to encrypt the PAN data, using the Derived Unique

Key Per Transaction (DUKPT) method. It is a 10 byte composite field that is transmitted as 20 alphanumeric character fixed length.

Refer to Card Data Elements table for each device and encryption type.

Recommended for swiped or contactless transactions.

The payment application capability. Valid values are:

 02 for Swiped device – Default value when track Data is sent alone



03 Proximity / Contactless capable device

Recommended for swiped or contactless transactions. The transaction entry indicator to indicate how the track data was captured. Valid values are:



03 = Swiped – Default value when track Data is sent alone

 04 = Proximity / Contactless

Converge Developer Guide: Additional Processing Options CON-0002-N

Field Name

ssl_amount ssl_vendor_id ssl_mobile_id

Req? Description

Y Transaction Sale Amount. Number with 2 decimal places:

 Multi-Currency: submit the correct number of decimal places as some currencies has no exponents and some can have three.



EMV: The amount must reflect the total amount which include tip.

 Non EMV: The amount passed should not contain the tip amount, tips must be passed separately. The total authorized amount will be calculated during the authorization if tip is provided. For example: 1.00.

Unique vendor identifier assigned by Elavon, up to 08 characters.

Optional. Unique assigned mobile identification number of each

Mobile device in use as determined by the merchant, required if the Mobile filter is enabled under the fraud prevention rules in

Converge, up to 50 characters. This will help the merchant to identify which device is sending transactions and can be used to allow or block transactions generating from a specific device.

When the filter is enabled, only those Mobile IDs listed under the

Mobile filter are allowed.

Card Data Elements (MagTek device with MagneSafe TM

Field Name

ssl_encrypted_track1_data ssl_encrypted_track2_data ssl_encrypted_loyalty_track1_data

Req? Description

Y Required for swiped or contactless (MSD) credit or gift transactions.

This is the encrypted Track 1 data extracted from the encrypting device.

Required for swiped or contactless (MSD) credit or gift transactions.

This is the encrypted Track 2 data extracted from the secure device.

Required for loyalty swiped or contactless

(MSD) transactions only.

This is the encrypted Track 1 data only of the loyalty card extracted from the encrypting device. ssl_encrypted_loyalty_track2_data Y Required for loyalty swiped or contactless

(MSD) transactions only.

This is the encrypted Track 2 data only of the loyalty card extracted from the encrypting device.

Converge Developer Guide: Additional Processing Options CON-0002-N

Card Data Elements (Ingenico device with Generic TDES DUKPT Encryption scheme):

Field Name

ssl_enc_track_data

Req? Description

C Required for swiped or contactless (MSD) credit or gift transactions.

This is the entire encrypted Track data combined into a single cipher text that was extracted from the Ingenico encrypting device. ssl_enc_loyalty_track_data C ssl_tlv_enc

Required for loyalty swiped or contactless (MSD) transactions only.

This is the entire encrypted Track data combined into a single cipher text that was extracted from the Ingenico encrypting device.

Required for EMV transactions.

The Tag Length Value data defining this EMV record. This value also includes the total amount sent for authorization

which includes the tip. Refer to the EMV section for more

information.

EMV

The following section provides the guidelines on how to process chip read transactions using your integrated application. This API assumes that the integrator is familiar with the processes involved in communicating with a chip card and a device. Additionally an EMV certification to the supported association is required once the integration is completed.

EMV which stands for Europay, MasterCard and Visa is a global standard for cards embedded with computer chips and the technology used to authenticate chip-card transactions. U.S. card issuers are migrating to this new technology to protect consumers and reduce the costs of fraud.

Chip card might be called any of the following terms:



Smart card



Chip card



Smart-chip card



Chip-enabled smart card



Chip-and-choice card (PIN or signature)



EMV smart card



EMV card

Converge Developer Guide: Additional Processing Options CON-0002-N

Transaction Summary

Developers can use processxml.do to process encrypted chip read credit and debit card transactions using an encrypting device. The transaction sent to processxml.do is formatted in

XML syntax and includes all supported transaction elements nested between one beginning and ending element <txn>.

Developers must integrate with a supported Ingenico device in order to extract the encrypted tag

length value (TLV); the device must use the generic TDES DUKPT encryption scheme. Both encryption and EMV add an additional layer of protection to the HTTPS POST request.

The following types of devices are supported:



Ingenico Smart Terminals: Multi lane such as the isc250 touch or PINpads such as the ipp320 PINpad running on RBA 14.X operating system



Ingenico Mobile Solutions: Mobile smart terminal such as an iCMP device or mPOS card reader such as RP457 or RP350

The following transactions are supported when processing chip transactions with processxml.do

Transaction Types

emvchipsale emvchipauthonly emvswipesale emvswipeauthonly emvchipupdatetxn emvreverse emvkeyexchange

Description

Process a chip read sale transaction for a credit or debit card. POS system will need to update the chip/device with the issuer script received from the authorization.

Process a chip read Auth Only transaction for a credit card. POS system will need to update the chip/device with the issuer script received from the authorization.

Process a swiped sale transaction for a chip card for a fallback situation where the chip card cannot be read.

Process a swiped Auth Only transaction for a fallback situation where the chip card cannot be read.

Update the system with data returned from a chip card after an

EMV sale if needed.

Reverse a chip card sale when the card declines the transaction after an approval has been received from the issuer.

Process a key exchange request and obtain the EMV keys. POS system will need to push the EMV keys to the device.

The following card brands/ associations are supported when processing Chip transactions:

Card Brand

Visa

MasterCard

American Express

Transaction Types

Credit Card Sale and Auth Only

Converge Developer Guide: Additional Processing Options CON-0002-N

Card Brand

Discover

Visa Interlink

MasterCard Maestro

Transaction Types

Credit Card Sale and Auth Only

Debit Card Sale

Transaction Flow

The following steps outline the process of sending a sale transaction with an EMV capable terminal with processxml.do:

Submit the transaction amount to the device to initiate a transaction:

1. If terminal is retail proceed to “Request a card read” in step 3

2. If terminal is service a) Request the Cardholder to select or key a tip amount b) Confirm the total amount c) Submit the new calculated total amount and proceed to step 3

3. Request a card read

4. Card is dipped (Chip read) a) Read error



Enable fallback



Attempt Swipe read b) Unsupported association for chip read transactions



Attempt Swipe read c) Perform “Chip Sale” Process

5. Card was swiped a) The card is a chip card

 Unsupported association for chip read transactions

 Perform “Swipe Sale” Process



In fallback status



Perform “Swipe Sale” Process



Supported association NOT in fallback

Converge Developer Guide: Additional Processing Options

 Attempt Chip read b) The card is non – chip card



Perform “Swipe Sale” Process

Chip Sale Process

1. Send request (EMVCHIPSALE API Command)

2. Receive response a) Update chip card with transaction results b) Finalize chip transaction



No additional action (most common use case)



Decline by card



Send request (EMVREVERSE API Command)



Receive response



Card responds with iccTSI/iccISR data



Send request (EMVCHIPUPDATETXN API Command)



Receive response c) ssl_update_emv_keys = “Y” (EMV key exchange required)



Send request (EMVKEYEXCHANGE API Command)



Receive keys in response



Perform EMV key exchange on chip reader

Swipe Sale Process

1. Send request (EMVSWIPESALE API Command)

2. Receive response

CON-0002-N

Converge Developer Guide: Additional Processing Options

Transaction Examples

Shown below are an XML example of Chip Visa Sale of 17.00:

CON-0002-N xmldata=<txn>

<ssl_merchant_id>my_virtualmerchant_id</ssl_merchant_id>

<ssl_user_id>my_user_id</ssl_user_id>

<ssl_pin>my_pin</ssl_pin>

<ssl_transaction_type>EMVCHIPSALE</ssl_transaction_type>

<ssl_tlv_enc>

5F3002020157114761730000000010D151220100000000009F2608A0B1AB453C8

6165D9F2701805A0847617300000000105F2A0208405F2D0265659F4005F000F0

A0019A031508159B02E8009F21030122399C01004004061820159F41040000023

082025C009F1E085343303130303438C00AFFFF44556600076000468407A00000

000310105F340101950502000080005F200C5445535420434152442030319F1A0

208409F1401039F02060000000017009F3901059F360202899F370478813F359F

0607A00000000310109F3501229F34031E03009F3303E0F8C89F0306000000000

0009F0902008C9F120B56697361204372656469744F07A00000000310109F1101

019F100706010A03A000009F0702FF005F24031512319F530152D02845AF34554

5C2841529B3E3673B7538E0EE4ACAA24DA3E4158BAC0763A4EF024BFABF04822E

063B865F28020124500B5649534120435245444954

</ssl_tlv_enc>

</txn>

Converge Developer Guide: Additional Processing Options CON-0002-N

Loyalty

Cardholder needs to be enrolled to the Merchant Loyalty Program offered to be able to accrue points and receive rewards and offers. Merchants need to be enrolled with Elavon loyalty program in order to offer rewards to their customers. The loyalty processing can be used as a standalone or integrated with the payment flow.

Processing Standalone Transactions

There are two Identification options available to the cardholder for enrollment to the Loyalty

Program under the standalone process:

1. Loyalty Card also called a non-linked ID

2. Phone number can be used as identification for enrollment

The following transactions types are supported when processing loyalty transactions as standalone:

Transaction Types

ltenrollment ltredeem ltreturn ltaddpoints

Description

Loyalty Card Enrollment

Loyalty Card Redemption

Loyalty Card Return

Loyalty Card Add Points ltinquiry Loyalty Card Balance Inquiry ltleadinquiry

Loyalty Card Lead Inquiry ltmemberinquiry Loyalty Card Member Inquiry

The following transactions types are supported when processing loyalty transactions as integrated with the payment flow:

Transaction Types Description

ccsale Credit Card Sale dbpurchase Debit Card Purchase

Converge Developer Guide: Additional Processing Options CON-0002-N

All standalone loyalty transactions must pass the following basic loyalty information. For complete

list of all required fields please refer to the Loyalty Card Transactions section:

Field Name

ssl_phone ssl_loyalty_track_data

Req? Description

Required when a loyalty card is not available, this will allow accessing the loyalty information based on phone number.

Max 10 digits, no spaces or dashes.

Note: Must be passed in enrollment.

Required when a loyalty card is available for swiped transactions.

Notes:

 If using a MagTek encrypting device (MagneSafe), pass the encrypted loyalty track1 data in the ssl_encrypted_loyalty_track1_data

and/or the encrypted loyalty track 2 data in the ssl_encrypted_loyalty_track2_data



If using an Ingenico encrypting device (Generic

TDES DUKPT), pass the entire encrypted track data of the loyalty card combined into a single cipher text in the ssl_enc_loyalty_track_data.



to Credit Card Sale (ccsale)

information. ssl_loyalty_card_number C ssl_loyalty_exp_date

Required when a loyalty card is available for hand-keyed transactions.

Loyalty card number as it appears on the loyalty card.

Optional when a loyalty card is available for hand-keyed transactions.

Loyalty card expiry date as it appears on loyalty card. If not sent it is defaulted to 1249. ssl_amount ssl_promo_code

Transaction sale amount, number with two decimal places.

For example: 1.00.

Note: Amounts are not required for enrollments.

Required for redeeming a promo code (for example: 10% discount).

Converge Developer Guide: Additional Processing Options CON-0002-N

Transaction Flow

The following steps outline the process of sending a loyalty transaction for standalone loyalty:

1. Cardholder keys or swipes a loyalty card or enters phone number in order to take advantage of a merchant offer, or the cardholder swipes credit/ debit card in order to find out if payment card is linked to a loyalty program and has current offers.

2. The integrated application/website processes Enrollment, Redeem, Balance Inquiry,

Return, Add point or Member inquiry transactions and collects the payment information using process.do or processxml.do as specified in the Loyalty Card Transactions section.

3. Submit a transaction request using HTTPS POST. Shown below are the key value pairs from the header by themselves for a Loyalty Card Enrollment request only: ssl_merchant_id=xxxxxx ssl_user_id=xxxxxxx ssl_pin=xxxxxx ssl_show_form=false ssl_transaction_type=ltenrollment ssl_phone=9999991234 ssl_loyalty_card_number=0000000000000000 ssl_loyalty_exp_date=1249 ssl_amount=50.00 ssl_result_format=HTML ssl_receipt_decl_method=REDG ssl_error_url=http://www.url.com/cgi-bin/testtran.cgi ssl_receipt_decl_get_url=http://www.url.com/cgibin/testtran.cgi ssl_receipt_apprvl_method=REDG ssl_receipt_apprvl_get_url=http://www.url.com/cgibin/testtran.cgi

Converge Developer Guide: Additional Processing Options CON-0002-N

Shown below are the key value pairs from the header by themselves for a Loyalty

Balance request: ssl_merchant_id=xxxxxx ssl_user_id=xxxxxxx ssl_pin=xxxxxx ssl_show_form=false ssl_transaction_type=ltinquiry ssl_loyalty_card_number=0000000000000000 ssl_loyalty_exp_date=1249 ssl_amount=50.00 ssl_result_format=HTML ssl_receipt_decl_method=REDG ssl_error_url=http://www.url.com/cgi-bin/testtran.cgi ssl_receipt_decl_get_url=http://www.url.com/cgibin/testtran.cgi

Shown below are the key value pairs from the header by themselves for a Loyalty Card

Redemption request: ssl_merchant_id=xxxxxx ssl_user_id=xxxxxxx ssl_pin=xxxxxx ssl_show_form=false ssl_transaction_type=ltredeem ssl_loyalty_card_number=0000000000000000 ssl_loyalty_exp_date=1249 ssl_promo_code=1234 ssl_amount=50.00 ssl_result_format=HTML ssl_receipt_decl_method=REDG ssl_error_url=http://www.url.com/cgi-bin/testtran.cgi ssl_receipt_decl_get_url=http://www.url.com/cgibin/testtran.cgi

=http://www.url.com/cgi-bin/testtran.cgi

Converge Developer Guide: Additional Processing Options CON-0002-N

Shown below are the key value pairs from the header by themselves for a lead inquiry, this transaction requires a credit card or debit card in order to determine if the payment card is linked to a loyalty program ssl_merchant_id=xxxxxx ssl_user_id=xxxxxxx ssl_pin=xxxxxx ssl_show_form=false ssl_transaction_type=ltleadinquiry ssl_card_number=0000000000000000 ssl_exp_date=1215 ssl_amount=50.00 ssl_result_format=HTML ssl_receipt_decl_method=REDG ssl_error_url=http://www.url.com/cgi-bin/testtran.cgi ssl_receipt_decl_get_url=http://www.url.com/cgibin/testtran.cgi

=http://www.url.com/cgi-bin/testtran.cgi

4. When Converge receives these posts, it starts to parse the data to look for a few key fields first. It validates the ssl_merchant_id, ssl_user_id, and ssl_pin to authenticate the user.

Note: User ID (ssl_user_id) and PIN (ssl_pin) are case sensitive.

5. If the supplied information is invalid, an error is returned that states that the information is invalid. If the data is valid, Converge continues to validate the other supplied information such as the card number, expiration date, amount of the transaction, type of transaction, address information, and other custom data fields that are passed. Other fields that are passed with transactions states how the transactions should be handled from a communications standpoint. These fields are: ssl_error_url=http://www.url.com/cgi-bin/testtran.cgi ssl_result_format=HTML ssl_receipt_decl_method=REDG ssl_receipt_decl_get_url=http://www.url.com/cgi-bin/testtran.cgi ssl_receipt_apprvl_method=REDG ssl_receipt_apprvl_get_url=http://www.url.com/cgibin/testtran.cgi ssl_show_form=false

Converge Developer Guide: Additional Processing Options CON-0002-N

6. By specifying the http://www.url.com/cgi-bin/testtran.cgi url in the ssl_error_url field for the redirect for the transaction above, for example, the following error is returned if one of the credentials in the request is invalid: errorCode=4025 errorName=Invalid Credentials errorMessage=The credentials supplied in the authorization request are invalid

7. By specifying the http://www.url.com/cgi-bin/testtran.cgi url in the ssl_apprvl_get_url

field for the redirect for the transaction above, the following values are returned for the approved transaction:

Shown below are the key value pairs from a successful balance inquiry transaction: ssl_result=0 ssl_result_message=APPROVAL ssl_approval_code=007157 ssl_account_balance=600 ssl_txn_id=AA4D3F5-0A4E3BAA-64E1-4097-8373-F7C93D53660A ssl_txn_time=04/16/2014 03:18:21 PM ssl_promo_code=1000 ssl_promo_code_name=Spend $50-Get $10Off ssl_promo_code_description=SAVE $10 ssl_promo_code_issue_points=Y

Processing Integrated Loyalty Transactions

There are three Identification options available to the cardholder for enrollment to the Loyalty

Program under the integrated process:

1. Loyalty Card also called a non-linked ID

2. Phone# number can be used as identification for enrollment.

3. Payment (Linked) card – credit card or debit card can be used as another form of identification.

Converge Developer Guide: Additional Processing Options CON-0002-N

The integrated loyalty must pass the following basic loyalty information in the authorization. Refer

and Debit Card Purchase (dbpurchase) sections for a complete list

of all required elements for these transaction types:

Field Name

ssl_enrollment ssl_phone ssl_loyalty_track_data

Req? Description

N Indicates enrollment action along with either a phone number or a loyalty card. The possible values listed as follows:

 00 – Already enrolled



10 – Already enrolled + link payment card

 01 – Enroll + link payment card



02 – Enroll + link loyalty card

 03 – Enroll + link only phone number

N Required when a loyalty card is not available, this will allow accessing the loyalty information based on phone number.

Max 10 digits, no spaces or dashes.

N Required when a loyalty card is available for swiped or contactless (MSD) transactions.

Notes:



If using a MagTek encrypting device (MagneSafe), pass the encrypted loyalty track1 data in the ssl_encrypted_loyalty_track1_data

and/or the encrypted loyalty track 2 data in the ssl_encrypted_loyalty_track2_data

 If using an Ingenico encrypting device (Generic

TDES DUKPT), pass the entire encrypted track data of the loyalty card combined into a single cipher text in the ssl_enc_loyalty_track_data.

