Batch Import File Format
The Batch Import File is a properly formatted CSV or XML batch file of credit card transactions that is uploaded through the Batch Import (ccimport
) transaction.
CSV Format
The format of a CSV batch file is as follows:
- Header
- First line of the file.
- Contains all the field names.
- Each field name is enclosed within double quotes and followed by a comma.
- Transaction Data
- Starts after the header line.
- Each transaction data is placed on a single line.
- Each transaction data is enclosed within double quotes and followed by a comma.
- The transaction data is placed in the same order of the field names.
You can download a csv template for batch imports.
Example
"ssl_card_number","ssl_exp_date","ssl_amount","ssl_transaction_type",
"0000000000000000","1212","2.00","ccsale",
"0000000000000000","1213","5.00","ccforce",
XML Format
The format of an XML batch file is as follows:
- The file contains a single
<txnimport>
element and multiple<txn>
(transaction) nested elements. - Every transaction is a set of XML tags.
- The number of
<txn>
corresponds to the number of transactions in the file. - All elements must be closed in the order that these were opened.
Example
<txnimport>
<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>
</txn>
</txnimport>
Fields
error_outline
note
- A single file can have a mix of tokens and card numbers.
- You must provide either the card number (
ssl_card_number
) or the token (ssl_token
) from a previously tokenized card number in each record. - CVV2/CVC/CID values and Track data should never be stored, and therefore cannot be passed to Converge on the file.
Field name | Description | Required | Length | Data type |
---|---|---|---|---|
ssl_card_number | Card Number Card Number as it appears on the credit card. | Conditional | 18 | numeric |
ssl_exp_date | Card’s Expiry Date Date when the card becomes invalid. Important: Required if ssl_card_number is not null.Format: MMYY | Conditional | 4 | numeric |
ssl_token | Credit Card Token Encrypted card data that can replace ssl_card_number . Important: - The token must already be stored in Card Manager. - Use only if the terminal is set up with the Tokenization terminal option. | Conditional | 20 | alphanumeric |
ssl_amount | Transaction Amount Format: Number with 2 decimal places | Required | 11 | numeric |
ssl_transaction_type | Transaction Type Valid values: ccsale (Sale), ccauthonly (Auth Only), ccverify (Verification), ccforce (Force) | Required | 20 | alphanumeric |
[Optional Fields] | ||||
ssl_invoice_number | Invoice/Ticket Number Unique identifier of the invoice or ticket. | Optional | 25 | alphanumeric |
ssl_first_name | First Name First name on the cardholder’s / customer’s account or billing address. | Optional | 50 | alphanumeric |
ssl_last_name | Last Name Last name on the cardholder’s / customer’s account or billing address. | Optional | 50 | alphanumeric |
ssl_company | Company Name Company name on the cardholder’s / customer’s account or billing address. | Optional | 50 | alphanumeric |
ssl_avs_address | Address Line 1 Commonly the house number and street name on the cardholder’s / customer’s account or billing address. | Optional | 30 | alphanumeric |
ssl_address2 | Address Line 2 Apartment or condominium unit number and floor number on the cardholder’s or customer’s account or billing address. | Optional | 30 | alphanumeric |
ssl_city | City City name on the cardholder’s / customer’s account or billing address. | Optional | 30 | alphanumeric |
ssl_state | State Code State or province code on the cardholder’s / customer’s account or billing address. | Optional | 2 | alphanumeric |
ssl_avs_zip | Postal or ZIP Code Postal or ZIP code on the cardholder’s / customer’s account or billing address. | Optional | 9 | alphanumeric |
ssl_country | Country ISO Code Country ISO code on the cardholder’s / customer’s account or billing address. | Optional | 3 | alphanumeric |
ssl_phone | Phone Phone number on the cardholder’s / customer’s account or billing address. Important: Accepts dashes. | Optional | 20 | numeric |
ssl_email | Email Address The cardholder’s or customer’s email address. | Optional | 100 | alphanumeric |
ssl_ship_to_first_name | Ship To First Name First name of the recipient on the shipping address. | Optional | 50 | alphanumeric |
ssl_ship_to_last_name | Ship To Last Name Last name of the recipient on the shipping address. | Optional | 50 | alphanumeric |
ssl_ship_to_company | Ship To Company Name Name of the company (recipient) on the shipping address. | Optional | 50 | alphanumeric |
ssl_ship_to_address1 | Ship To Address Line 1 House number and street name on the shipping address. | Optional | 30 | alphanumeric |
ssl_ship_to_address2 | Ship To Address Line 2 Apartment or condominium unit number and floor number on the shipping address. | Optional | 30 | alphanumeric |
ssl_ship_to_city | Ship To City Name of the city on the shipping address. | Optional | 30 | alphanumeric |
ssl_ship_to_state | Ship To State Code State code on the shipping address. | Optional | 2 | alphanumeric |
ssl_ship_to_zip | Ship To ZIP Code Postal or ZIP code on the shipping address. | Optional | 9 | alphanumeric |
ssl_ship_to_country | Ship To Country Country ISO code on the shipping address. | Optional | 3 | alphanumeric |
ssl_ship_to_phone | Ship To Phone Phone number on the shipping address. | Optional | 10 | numeric |
ssl_bin_override | Override Bank Identification Number (BIN) Allows the integrated application to pass the ssl_Customer_code and/or ssl_salestax values for non-corporate cards.Valid value: 1 - Pass customer code and/or sales tax for non-corporate card transaction requests | Optional | 1 | numeric |
ssl_description | Merchant-defined Transaction Description Short and custom text to describe the transaction. | Optional | 255 | alphanumeric |
ssl_customer_code | Customer Code or Purchase Order Number Customer ID or PO number specified in the billing statement of the cardholder. | Optional | 17 | alphanumeric |
ssl_salestax | Sales Tax Tax amount to add to the purchase or sales amount. For a tax exempt transaction, enter 0.00. Format: Amount with 2 decimal places. | Optional | 8 | alphanumeric |
ssl_get_token | Generate Token Indicator Indicates whether to generate a token when submitting the card data. Valid values:
| Optional | 1 | alphanumeric |
ssl_approval_code | Transaction Approval Code Unique code returned by the credit card processor that indicates the approval status of the transaction. Required if ssl_transaction_type = ccforce. | Conditional | 6 | numeric |
ssl_transaction_currency | Transaction Currency The currency ISO code that the merchant applies to their goods or services. Default: USD or CAD Use only on terminals that are set up with the Multi Currency credit card payment option. | Optional | 3 | alphanumeric |
ssl_do_customer_email | Send email to customer indicator. Indicates whether to send emails to customers when transactions are approved or declined. Default value: Set in terminal-Email form Valid value:
| Optional | 1 | alphanumeric |
Custom Fields | User-defined Fields Up to 25 custom fields can be passed in the batch file. The fields entered in the file must match those specified in Terminal Setup, Merchant, Payment Fields, Add New Field. | Optional | - | - |