Introduction

The eProcessing Network Transparent Database Engine Template (TDBE) is an Application Programming Interface (API) that allows you to integrate your website or application with the eProcessingNetwork Transaction Processing Gateway to perform credit card, debit card, gift card, and check transactions. Integrating with the TDBE requires advanced computer skills, including programming.

Websites and applications that collect and maintain a customer's order information can use the TDBE to seamlessly process transactions without the customer ever leaving the website. Applications communicate with the TDBE using HTTPS to ensure transactions are transmitted securely. All connections to the TDBE must be done with the TLSv1.2 protocol. Any connection attempts that do not utilize this protocol will fail. Developers generally must install the required HTTPS libraries for the language being used on their own server. Installing these libraries is beyond the scope of the support offered by eProcessingNetwork. Consult the documentation for your desired library for instructions on installation and use. This section describes the information required to perform transactions using the TDBE and provides examples of the values to send and the responses received. Examples are provided as sample JSON and XML, showing the HTTP POST values sent to the TDBE.

This API does not support Cross-Origin Resource Sharing (CORS) requests.

API URLs

The REST TDBE API uses a different set of URLs but it is backwards compatible with the old TDBE API. This allows you to submit a form like you would with the ad TDBE API but to the new TDBE API. The new TDBE API also allows you to also post JSON or XML. The parameters names are consistent across all content-types. To use JSON or XML, make sure your content-type for the POST is 'application/json' for JSON or text/xml' for XML. Examples can be found in the Sample Transactions section and the Appendix.

BEFORE THE SYSTEM WILL ALLOW A TRANSACTION USING THE TDBE:
In your developer account or any live accounts that use the TDBE API, go to the Web Services / Processing Controls Section / Disabled Integrations section and uncheck the TDBE (Transparent Database Engine)

Required for All Requests

The following fields are required for all requests sent to the TDBE.

transaction Requests

The following table lists the minimum fields you must submit for a credit card not present transaction. All fields are case sensitive. In addition, we recommend you submit the fields listed in the Optional Fields section. If you run EMV transactions, the "CardNo" field is replaced with the "EncData", "EncFormat", and "EmvData" fields.See EMV for more information.

<TranType>

The transaction types available to developers are authorizations, voice authorization, authorization capture, authorization delete, authorization conversion, sale, store, debit, credit/refund, cash sale, cash return, void and close batch transactions, and credit/refund transactions. The following table lists the <TranType> values for transactions that are supported. Note: Individual merchant accounts may not support all transaction types.

EMV/Encrypted Swiped Transactions

TDBE allows for encrypted swiped transactions with the devices below. They MUST be encrypted with the eProcessing Network encryption key. In order to run an EMV transaction, you will have to provide the EMV data and it will be sent with the parameter 'EmvData.' EMV can only be utilized by using an encrypted device such as the MP200 from Castles.

Note: If your device ever declines the transaction prior to actually sending the transaction, you will have to use the parameter 'EMVOfflineDecline' and set it to 'Y'. This ensures that the transaction shows up under declines in Activity Reports.

View Compatible Devices

EMV IssuesDoubleFallback

Reading EMV card data can have issues and result in EMV devices demanding the card be swiped. When this happens, the device will still return some EMV tags and the POS Entry Mode tag (9F39) indicates that the transaction is a fallback. Nothing special needs to be done until there are 2 fallback transactions in a row. The application needs to keep track of this and if it does occur, a new parameter must be passed with the transaction. The parameter is DoubleFallback and it would be set to 1.

DebitSale Transactions

PIN debit transactions are similar to swiped transactions; but require PIN and Key Serial data from the PIN pad. The following table describes the required fields for PIN debit transactions.

Signature Capture/Image

You can include a signature image file with a transaction. If the transaction approves the image is kept with the transaction and can be viewed later. This is used for Signature Capture but could also be used for some other relevant image as well. Two additional parameters are required "SignatureFile" and "SignatureHexData".

Signature Capture Upload Post

If you would rather upload the signature capture image after the transaction has approved, you will need to post these additional fileds to the "secure_signature_upload.pl"

Purchase Level Cards

Credit cards can be processed at three different levels. These levels are determined by the card that is being processed and can affect the rates that the cards are processed at. In order for a transaction to qualify for special rates, there must be additional data passed with the transaction. For example, Level I card data is typically associated with consumer transactions and limited purchase data returned to the cardholder. Below is a chart of the required data for each card level.
For keyed transactions see the Transaction Request Section. Use test CardNo = 4484070000000000

Sale from XactID

For most transaction types that require credit card information, such as sale and credit/return, you can submit the XactID of a previously closed transaction instead of the credit card information. The TDBE looks up the card information without displaying it to the merchant. ExpMonth and ExpYear are not required; however, you can submit these values to update the information stored on the TDBE. Please make sure to set the TranType to Sale.

Required:

Sale from CDM Identifier

If a merchant account has CDM Advanced, you can submit a customer Identifier or Email and automatically run a sale from the customer's stored default payment. It uses the billing address information associated with the default payment. Please make sure to set the TranType to Sale.

Required:

PC Level II Transactions

Level II purchasing card data benefit the corporate/government/industrial buyer and includes the same information captured at Level I, plus: sales tax amount, plus a field called CustCode. The CustCode can be the customer's accounting code, tax ID number or the purchase order number. The following table describes the fields required for Purchase Card level II transactions.

PC Level III Transactions

(TSYS, Elavon, and FDMS North ONLY)

For transactions to qualify for LevelII rates, additional information needs to be included with the transaction. This information will transform the items in the sale from a list to an itemized invoice. Level III purchasing card data includes the same information captured at Levels I and II transactions; plus: quantities, product codes, product descriptions, destination ZIP, freight amount, order/ticket number, unit of measure, extended item amount, discount indicator, discount amount, net/gross indicator, tax rate applied, tax type applied, debit or credit indicator and alternate tax identifier.

Optional Fields

The following fields are optional and can be submitted with the transaction data.

Dynamic / Soft Descriptor - (TSYS ONLY)

eProcessing Network gives merchants the ability to control the line item description displayed on the cardholder's credit card statement on a per transaction basis.

It is important to note that this feature is only available via our TDBE API for merchants that have a TSYS merchant account. The descriptor cannot exceed 25 characters.

To set a merchant up for this service, follow these steps:

• Confirm gateway is setup to work with TSYS and has a TSYS processing account we can connect to.
• Notify eProcessingNetwork what gateway ID needs this feature. (We need to set a flag on the account.)
• A special field <MerchantName> needs to be passed in to be used as the descriptor. Make sure the field does not exceed 25 characters.

ePNPlugin for QuickBooks™

You can associate a transaction with a QuickBooks™. Invoice, Sales Receipt or Credit Memo. If you associate a transaction with a QuickBooks Invoice, Sales Receipt or Credit Memo the ePNPlugIn Download Transaction Manager will auto-associate this with the appropriate QuickBooks transaction.

The transaction can be associated with one Invoice, one Sales Receipt or one Credit Memo using the AppData field.

To associate the transaction you need to pass in a field named <AppData> and the value of the field needs to be as the following table describes.

Postback Option with TDBE via Processing Controls

You may provide a TDBE Postback URL to allow a Postback with the transaction response from the TDBE. This transaction response is sent to the specified URL if the PostbackID parameter is passed within the TDBE POST

The Postback will be of content-type "application/x-www-form-urlencoded" and include the provided PostbackID, as well as the full response (as normally returned): XactID, Invoice, AVS Response, and CVV Response

You may provide the Postback URL by accessing the Processing Controls section from the sidebar and navigating to the "TDBE Postback" section.

If you wish for your app to recieve the transaction response and the postback response, send the parameter COMBINE_PB_RESPONSE with a value of 1. The postback response will appear under the PostbackResponse element within the transaction response. If you still submit transactions with the "application/x-www-form-urlencoded" content type, the postback response will appear in the CSV string like "PostbackResponse=...".

If you wish to have other parameters reflected in the postback, you need to not only send the original parameter, but also the same parameters with "Postback." prepended to it. Ex: Postback.Description, Postback.FirstName, Postback.LastName, etcetera

Fields with sensitive data will NOT be posted back. See the list below:

• Postback.CardNo
• Postback.ExpMonth
• Postback.ExpYear
• Postback.CVV2
• Postback.NCNAccountNum
• Postback.NCNDLNum
• Postback.IdentitySSN4
• Postback.IdentityDOB
• Postback.IdentityDOBYear
• Postback.Check21ImageBytes1
• Postback.Check21ImageBytes2
• Postback.PINBlock
• Postback.KeySerial
• Postback.EncData
• Postback.EmvData

Testing Key Response Values

When testing, you can trigger an expected response value based on the specific key value submitted.

<Success>

The Success Key can be one of three values to indicate if the transaction was successful or not.

1. Y - Approved
2. N - Declined
3. U - Unable to process the transaction.

<RespText>

Specific <Total> amounts can be submitted to trigger the following responses.

<AVSCode> & <AVSText>

To receive a specific set of Address Verification System responses values;<AVSCode> & <AVSText>, pass in one of the following values for the <Address>.

<CVV2Code> & <CVV2Text>

By default, the TDBE returns a response of:
<CVV2Code>M</CVV2Code>
<CVV2Text>Card Verification Value matches</CVV2Text>

To receive a specific response values, submit one of the following values as the first the <CVV2> value.

Integration Diagnostic Tool

Follow the steps below to diagnose problems you may encounter with your integration. This URL will generate a web page that displays exactly what was sent to it, helping you confirm that you are sending the required information correctly.

1. Temporarily change the URL to which you are posting your transaction to https://www.eprocessingnetwork.com/cgi-bin/reflect/transact.pl
2. Include <Email>myemail@gmail.com</Email> to send a reflection of your variables and their value to that email address.
3. Include <MerchantEmail>on</MerchantEmail> to have the sytem send an diagnostic reflection of your variables to the email address we have on file for the merchant.
4. Include <PostURL>URL</PostURL>with the URL that you are posting to.

Advanced Recurring Billing

In order to use Advanced Recur Billing, your ePN Account must be setup for Internet payment processing and Advanced Recur before any recur transaction data is submitted. You can view your recurring transactions in the Merchant Support Center at www.eprocessingnetwork.com/msclogin.html and navigating to the Recur Billing section. There are two ways to create recurring transactions with the TDBE:

Recur Postback URL

The Recur System can post a message to your application each time it runs a recurring transaction. To receive a postback, set your Postback URL on the Recur Billing page in the Merchant Support Center.

The Recur System can post a message to your application each time it runs a recurring transaction. Once you are logged in, choose Recur Billing then look for Recur Postback URL. The URL must be HTTPS and cannot have a question mark (?) in it. Once you have entered your URL click the Save Recur Postback URL.

The postback includes the standard transaction information including approval values, invoice number and transaction, customer data, and recurring period. The postback also returns the following values:

The Recur System sends a post with the following values to the URL specified Execute transactions:

The Recur System sends the following to the postback URL for Cancel transactions:

On The Fly

If you want to process of each of your order details in your recurring transaction separately, you can set the details for each transaction as you submit it. This is creating a Recur on the Fly. Use the following fields to create a recurring transaction on the fly.
Notice: In the Request Example the <Total>100.00</Total> and <RCRRecurAmount>50.00</RCRRecurAmount>so this transaction would be charged 100.00 now and 50.00 when it recurs in a month.