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
"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",
You can download a csv template for batch imports. Note, the file download will begin when you click the link.
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.
| 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:
| 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:
Select Y to process the recurring transaction:
| Conditional | 1 | alphanumeric |
ssl_skip_payment | Skip Payment Indicator Valid values:
| 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 | 50 | alphanumeric |
ssl_last_name | Last Name Last name on the cardholder’s / customer’s account or billing address. | Optional | 50 | 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: Accepts dashes. | Optional | 20 | 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 | 50 | alphanumeric |
ssl_ship_to_last_name | Ship To Last Name Last name of the recipient on the shipping address. | Optional | 50 | 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 | NA | NA |