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 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_amountTransaction Amount
Format: Number with 2 decimal places
Required11numeric
ssl_transaction_typeTransaction Type
Valid values:ccaddrecurring (Add Recurring), ccaddinstall (Add Installment)
Required20alphanumeric
ssl_next_payment_dateNext Payment Date
The date of the next scheduled payment for the recurring or installment record.
Format: MM/DD/YYYY
Required10alphanumeric
ssl_billing_cycleBilling Cycle
Valid values:DAILY, WEEKLY, BIWEEKLY, SEMIMONTHLY, MONTHLY, BIMONTHLY, QUARTERLY, SEMESTER, SEMIANNUALLY, ANNUALLY, SUSPENDED
Required12alphanumeric
ssl_bill_on_halfHalf 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
Conditional1numeric
ssl_end_of_monthEnd 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).
Conditional1alphanumeric
ssl_skip_paymentSkip Payment Indicator
Valid values:
- Y - Skip payment
- N - Do not skip payment (Default)
Optional1alphanumeric
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.
Optional20alphanumeric
ssl_last_nameLast Name
Last name on the cardholder’s / customer’s account or billing address.
Optional30alphanumeric
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: Must not include spaces or dashes.
Optional10numeric
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.
Optional20alphanumeric
ssl_ship_to_last_nameShip To Last Name
Last name of the recipient on the shipping address.
Optional30alphanumeric
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_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
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--