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

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 nameDescriptionRequiredLengthData type
ssl_card_numberCard Number
Card Number as it appears on the credit card.
Conditional18numeric
ssl_exp_dateCard’s Expiry Date
Date when the card becomes invalid.
Important: Required if ssl_card_number is not null.
Format: MMYY
Conditional4numeric
ssl_tokenCredit 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.
Conditional20alphanumeric
ssl_amountTransaction Amount
Format: Number with 2 decimal places
Required11numeric
ssl_transaction_typeTransaction Type
Valid values:  ccsale (Sale), ccauthonly (Auth Only), ccverify (Verification), ccforce (Force)
Required20alphanumeric
[Optional Fields]
ssl_invoice_numberInvoice/Ticket Number
Unique identifier of the invoice or ticket.
Optional25alphanumeric
ssl_first_nameFirst Name
First name on the cardholder’s / customer’s account or billing address.
Optional50alphanumeric
ssl_last_nameLast Name
Last name on the cardholder’s / customer’s account or billing address.
Optional50alphanumeric
ssl_companyCompany Name
Company name on the cardholder’s / customer’s account or billing address.
Optional50alphanumeric
ssl_avs_addressAddress Line 1
Commonly the house number and street name on the cardholder’s / customer’s account or billing address.
Optional30alphanumeric
ssl_address2Address Line 2
Apartment or condominium unit number and floor number on the cardholder’s or customer’s account or billing address.
Optional30alphanumeric
ssl_cityCity
City name on the cardholder’s / customer’s account or billing address.
Optional30alphanumeric
ssl_stateState Code
State or province code on the cardholder’s / customer’s account or billing address.
Optional2alphanumeric
ssl_avs_zipPostal or ZIP Code
Postal or ZIP code on the cardholder’s / customer’s account or billing address.
Optional9alphanumeric
ssl_countryCountry ISO Code
Country ISO code on the cardholder’s / customer’s account or billing address.
Optional3alphanumeric
ssl_phonePhone
Phone number on the cardholder’s / customer’s account or billing address.
Important: Accepts dashes.
Optional20numeric
ssl_emailEmail Address
The cardholder’s or customer’s email address.
Optional100alphanumeric
ssl_ship_to_first_nameShip To First Name
First name of the recipient on the shipping address.
Optional50alphanumeric
ssl_ship_to_last_nameShip To Last Name
Last name of the recipient on the shipping address.
Optional50alphanumeric
ssl_ship_to_companyShip To Company Name
Name of the company (recipient) on the shipping address.
Optional50alphanumeric
ssl_ship_to_address1Ship To Address Line 1
House number and street name on the shipping address.
Optional30alphanumeric
ssl_ship_to_address2Ship To Address Line 2
Apartment or condominium unit number and floor number on the shipping address.
Optional30alphanumeric
ssl_ship_to_cityShip To City
Name of the city on the shipping address.
Optional30alphanumeric
ssl_ship_to_stateShip To State Code
State code on the shipping address.
Optional2alphanumeric
ssl_ship_to_zipShip To ZIP Code
Postal or ZIP code on the shipping address.
Optional9alphanumeric
ssl_ship_to_countryShip To Country
Country ISO code on the shipping address.
Optional3alphanumeric
ssl_ship_to_phoneShip To Phone
Phone number on the shipping address.
Optional10numeric
ssl_bin_overrideOverride 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
Optional1numeric
ssl_descriptionMerchant-defined Transaction Description
Short and custom text to describe the transaction.
Optional255alphanumeric
ssl_customer_codeCustomer Code or Purchase Order Number
Customer ID or PO number specified in the billing statement of the cardholder.
Optional17alphanumeric
ssl_salestaxSales 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.
Optional8alphanumeric
ssl_get_tokenGenerate Token Indicator
Indicates whether to generate a token when submitting the card data.
Valid values:
  • Y - Generate token
  • N - Do not generate token (Default)
Optional1alphanumeric
ssl_approval_codeTransaction Approval Code
Unique code returned by the credit card processor that indicates the approval status of the transaction.
Required if ssl_transaction_type = ccforce.
Conditional6numeric
ssl_transaction_currencyTransaction 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.
Optional3alphanumeric
ssl_do_customer_emailSend 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:
  • T - Send email to customer. Defaults to T if the customer’s email address is present in the original transaction and ssl_do_customer_email is null.
  • F - Do not send email to customer
Optional1alphanumeric
Custom FieldsUser-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--