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

note

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_amount`	Transaction Amount Format: Number with 2 decimal places	Required	11	numeric
`ssl_transaction_type`	Transaction Type Valid values:`ccaddrecurring` (Add Recurring), `ccaddinstall` (Add Installment)	Required	20	alphanumeric
`ssl_next_payment_date`	Next Payment Date The date of the next scheduled payment for the recurring or installment record. Format: MM/DD/YYYY	Required	10	alphanumeric
`ssl_billing_cycle`	Billing Cycle Valid values:`DAILY`, `WEEKLY`, `BIWEEKLY`, `SEMIMONTHLY`, `MONTHLY`, `BIMONTHLY`, `QUARTERLY`, `SEMESTER`, `SEMIANNUALLY`, `ANNUALLY`, `SUSPENDED`	Required	12	alphanumeric
`ssl_bill_on_half`	Half of the Month or Semimonthly Indicator Indicates when to process recurring or installment payment transactions if `ssl_billing_cycle` = SEMIMONTHLY. Valid values: - `1` - 1st and 15th of the month - `2` - 15th and last day of the month	Conditional	1	numeric
`ssl_end_of_month`	End of Month Indicator Indicates whether to process the recurring or installment transaction on the last day of the month. Valid values: - `Y` - Yes - `N` - No Select Y to process the recurring transaction: - If `ssl_billing_cycle` = MONTHLY, BIMONTHLY, QUARTERLY, SEMESTER or SEMIANNUALLY and the Start Payment Date is April 30, June 30, September 30, November 30, February 28 (non-Leap year) or February 29 (Leap year). - If `ssl_billing_cycle` = ANNUALLY and the Start Payment Date is February 28 (non-Leap year) or February 29 (Leap year).	Conditional	1	alphanumeric
`ssl_skip_payment`	Skip Payment Indicator Valid values: - `Y` - Skip payment - `N` - Do not skip payment (Default)	Optional	1	alphanumeric
`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	20	alphanumeric
`ssl_last_name`	Last Name Last name on the cardholder’s / customer’s account or billing address.	Optional	30	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: Must not include spaces or dashes.	Optional	10	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	20	alphanumeric
`ssl_ship_to_last_name`	Ship To Last Name Last name of the recipient on the shipping address.	Optional	30	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_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
`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	-	-