Recurring Batch Import File Format
The Recurring Batch Import File is a properly formatted CSV or XML batch file of recurring and installment transactions that is uploaded through the Recurring Batch Import (ccrecimport
) 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.
Example
You can download a template csv for batch imports.
"ssl_card_number","ssl_exp_date","ssl_amount","ssl_transaction_type","ssl_next_payment_date","ssl_billing_cycle",
"0000000000000000","1212","2.00","ccaddrecurring","10/21/2012","WEEKLY",
"0000000000000000","1213","5.00","ccaddinstall","06/21/2012","MONTHLY",
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>ccaddrecurring</ssl_transaction_type>
<ssl_next_payment_date>10/21/2012</ssl_next_payment_date>
<ssl_billing_cycle>WEEKLY</ssl_billing_cycle>
</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>addinstall</ssl_transaction_type>
<ssl_next_payment_date>10/21/2012</ssl_next_payment_date>
<ssl_billing_cycle>MONTHLY</ssl_billing_cycle>
</txn>
</txnimport>
Fields
error_outline
note
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_amount 11 | numeric | required | Transaction Amount Format: Number with 2 decimals places |
ssl_transaction_type 20 | alphanumeric | required | Transaction Type Valid values: ccaddrecurring (Add Recurring), ccaddinstall (Add Installment) |
ssl_next_payment_date 10 | alphanumeric | required | Next Payment Date The date of the next scheduled payment for the recurring or installment record. Format: MM/DD/YYYY |
ssl_billing_cycle 12 | alphanumeric | required | Billing Cycle Valid values: DAILY , WEEKLY , BIWEEKLY , SEMIMONTHLY , MONTHLY , BIMONTHLY , QUARTERLY , SEMESTER , SEMIANNUALLY , ANNUALLY , SUSPENDED |
ssl_bill_on_half 1 | numeric | conditional | Half of the Month or Semimonthly Indicator Indicates when to process recurring or installment payment transactions if ssl_billing_cycle = SEMIMONTHLY.Valid values:
|
ssl_end_of_month 1 | alphanumeric | conditional | End of Month Indicator Indicates whether to process the recurring or installment transaction on the last day of the month. Valid values:
|
ssl_skip_payment 1 | alphanumeric | optional | Skip Payment Indicator Valid values:
|
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. |
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. |