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:
  • 1 - 1st and 15th of the month
  • 2 - 15th and last day of the month
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:
  • 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).
ssl_skip_payment
1 | alphanumeric | optional
Skip Payment Indicator
Valid values:
  • Y - Skip payment
  • N - Do not skip payment (Default)
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.