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:
|
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:
|
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. |