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 template csv 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.

ssl_card_number
18 | numeric | conditional
Card Number
Card Number as it appears on the credit card.
ssl_exp_date
4 | numeric | conditional
Card's Expiry Date
Date when the card becomes invalid.
Important: Required if ssl_card_number is not null.
Format: MMYY
ssl_token
20 | alphanumeric | conditional
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.
ssl_amount
11 | numeric | required
Transaction Amount
Format: Number with 2 decimals places
ssl_transaction_type
20 | alphanumeric | required
Transaction Type
Valid values: ccsale (Sale), ccauthonly (Auth Only), ccverify (Verification), ccforce (Force)
ssl_invoice_number
25 | alphanumeric | optional
Invoice/Ticket Number
Unique identifier of the invoice or ticket.
ssl_first_name
20 | alphanumeric | optional
First Name
First name on the cardholder's / customer's account or billing address.
ssl_last_name
30 | alphanumeric | optional
Last Name
Last name on the cardholder's / customer's account or billing address.
ssl_company
50 | alphanumeric | optional
Company Name
Company name on the cardholder's / customer's account or billing address.
ssl_avs_address
30 | alphanumeric | optional
Address Line 1
Commonly the house number and street name on the cardholder's / customer's account or billing address.
ssl_address2
30 | alphanumeric | optional
Address Line 2
Apartment or condominium unit number and floor number on the cardholder's or customer's account or billing address.
ssl_city
30 | alphanumeric | optional
City
City name on the cardholder's / customer's account or billing address.
ssl_state
2 | alphanumeric | optional
State Code
State or province code on the cardholder's / customer's account or billing address.
ssl_avs_zip
9 | alphanumeric | optional
Postal or ZIP Code
Postal or ZIP code on the cardholder's / customer's account or billing address.
ssl_country
3 | alphanumeric | optional
Country ISO Code
Country ISO code on the cardholder's / customer's account or billing address.
ssl_phone
10 | numeric | optional
Phone
Phone number on the cardholder's / customer's account or billing address.
Important: Must not include spaces or dashes.
ssl_email
100 | alphanumeric | optional
Email Address
The cardholder's or customer's email address.
ssl_ship_to_first_name
20 | alphanumeric | optional
Ship To First Name
First name of the recipient on the shipping address.
ssl_ship_to_last_name
30 | alphanumeric | optional
Ship To Last Name
Last name of the recipient on the shipping address.
ssl_ship_to_company
50 | alphanumeric | optional
Ship To Company Name
Name of the company (recipient) on the shipping address.
ssl_ship_to_address1
30 | alphanumeric | optional
Ship To Address Line 1
House number and street name on the shipping address.
ssl_ship_to_address2
30 | alphanumeric | optional
Ship To Address Line 2
Apartment or condominium unit number and floor number on the shipping address.
ssl_ship_to_city
30 | alphanumeric | optional
Ship To City
Name of the city on the shipping address.
ssl_ship_to_state
2 | alphanumeric | optional
Ship To State Code
State code on the shipping address.
ssl_ship_to_zip
9 | alphanumeric | optional
Ship To ZIP Code
Postal or ZIP code on the shipping address.
ssl_ship_to_country
3 | alphanumeric | optional
Ship To Country
Country ISO code on the shipping address.
ssl_ship_to_phone
10 | numeric | optional
Ship To Phone
Phone number on the shipping address.
ssl_description
255 | alphanumeric | optional
Merchant-defined Transaction Description
Short and custom text to describe the transaction.
ssl_customer_code
17 | alphanumeric | optional
Customer Code or Purchase Order Number
Customer ID or PO number specified in the billing statement of the cardholder.
ssl_salestax
8 | alphanumeric | optional
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.
ssl_get_token
1 | alphanumeric | optional
Generate Token Indicator
Indicates whether to generate a token when submitting the card data.
Valid values:
  • Y - Authorize transaction and generate token
  • N - Do not generate token (Default)
ssl_approval_code
6 | numeric | conditional
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.
ssl_transaction_currency
3 | alphanumeric | optional
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.
Custom Fields
- | - | optional
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.