Parameter Name

Opt/Req

Description

UserName

R

User name assigned in the payment server. The user must have an appropriate level of access within the system in order to utilize the web service.

Password

R

Password associated with the user name provided.

TransType

R

Indicates whether the contract is being added, updated, or deleted. Valid entries are:

•      ADD

•      UPDATE

•      DELETE

Vendor

R

Unique numeric value used to identify the merchant.

Note: Vendor key may also be called Merchant ID, Merchant Number, or RPNum. To locate your Vendor key on the virtual terminal, click Password under the Preferences menu.

CustomerKey

R

Unique identifier assigned to the customer record by the system at the time the customer record is created.

Note: The CustomerKey value can be found on the virtual terminal by accessing the View Customers option under the Recurring Billing menu. Display a list of customers by entering search criteria. The CustomerKey appears in the Key column.

ContractKey

R*

Unique identifier assigned to the contract by the system at the time the contract record is created.

Note: The ContractKey value appears in the return results (see <ContractKey></ContractKey> tags) when a new contract is added to the system.

PaymentInfoKey

R^$

Information passed in the PaymentInfoKey parameter will vary depending on the PaymentType value passed.

•      If a PaymentType of CC (credit card) is passed, send the CardInfoKey value

•      If a PaymentType of CK (check) is passed, send the CheckInfoKey value

PaymentType

R^$

Identifies the type of payment method used. Valid values are:

•      CC – Credit card

•      CK – Check/ACH

Note: This parameter is case sensitive. Lower case entries will result in an error.

Customer ID

R

Unique identifier assigned to the customer by the merchant at the time the customer record is created.

Note: The CustomerID value can be found on the virtual terminal by accessing the View Customers option under the Recurring Billing menu. Display a list of customers by entering search criteria. The CustomerID appears in the Customer ID column.

CustomerName

R

Individual or customer business name.

Note: The CustomerName can be found on the virtual terminal by accessing the View Customers option under the Recurring Billing menu. Display a list of customers by entering search criteria. The CustomerName appears in the Customer Name column.

FirstName

O

Customer contact first name.

LastName

O

Customer contact last name.

Title

O

Customer contact job or professional title. For example, “Business Unit Manager,” or “Dr.”

Department

O

Customer contact department. For example, “Sales,” or “Operations.”

Street1

O

Customer contact street address – line 1.

Street2

O

Customer contact street address – line 2.

Street3

O

Customer contact street address – line 3.

City

O

Customer contact city.

StateID

O

Customer contact’s standard U.S. postal service two-character state code (U.S. customers only).

Note: Valid entries should follow USPS two-character state code standards. For more information, see http://www.usps.com/ncsc/lookups/usps_abbreviations.html

Province

O

Customer contact’s province (countries outside the U.S., only).

Zip

O

Customer contact’s zip or postal code.

CountryID

O

Customer contact’s three-character country code. For example, USA = United States or CAN = Canada.

DayPhone

O

Customer contact’s daytime phone number.

NightPhone

O

Customer contact’s after-hours phone number.

Fax

O

Customer contact’s fax number.

Email

O

Customer contact’s email address.

Mobile

O

Customer contact’s mobile phone number.

ContractID

R

Unique identifier assigned to the contract by the merchant at the time the contract record is created.

Note: The ContractKey value can be found on the virtual terminal by accessing the View Contracts option under the Recurring Billing menu. Display a list of contracts by entering search criteria. The ContractKey appears in the Contract ID column.

ContractName

O

Name assigned to the contract (used for easier identification).

BillAmt

R

Amount billed each time the contract comes due in DD.CCCC format.

TaxAmt

O

Additional tax amount applied to the BillAmt each time the contract comes due in DD.CCCC format.

TotalAmt

R

Total amount billed each time the contract comes due in DD.CCCC format.

BillAmt + TaxAmt = TotalAmt

StartDate

R

Date that the contract becomes effective in MM/DD/YYYY format. The start date must be greater than today’s date.

The StartDate represents the first time the customer will be billed per the contract. Future bill dates are calculated using the BillingPeriod and BillingInterval parameters.

EndDate

R

Date that the contract is completed in MM/DD/YYYY format. The end date must be greater than the start date.

NextBillDt

R^$

Identifies the next time the contract will come due in MM/DD/YYYY format.

Note: The NextBillDe can be found on the contract detail in the virtual terminal. Click View Contracts under the Recurring Billing menu and search for the contract you want to work with. Click the linked Contract ID and locate the Next Bill Date field.

See also ManageContractAddDaysToNextBillDt for simplified processing where only NextBillDt will be updated.

BillingPeriod

R

This value is used in conjunction with the BillingInterval to compute the next bill date for a contract. Valid values are:

•      DAY

•      WEEK

•      MONTH

•      YEAR

Note: The system will automatically account for 31 day months and/or leap years. For example:

•      Recurring billing is set to run once monthly

•      The contract start date is set for the 31^st

If the next month only has 30 days, recurring billing will automatically run the transaction on the 30^th.

Note: This parameter is case sensitive.

Examples of billing cycles and how are shown in this table:

BillingInterval

R

This value is used in conjunction with the BillingPeriod to compute the next bill date for a contract. Valid values are:

•      1

•      2

•      4

•      14

•      21

•      28

MaxFailures

O

The number of times the system will try to re-process a failed payment before the contract is placed in suspended state. Valid entries are integers 0-10.

If left blank, the default value is zero (0). A MaxFailure = 0 means that the system will not try to reprocess a failed payment.

IMPORTANT: When a payment fails to process and the MaxFailures parameter is set to a value greater than zero (0), all future payments will be ignored until the failed payment is either successfully processed or the contract is suspended.

FailureInterval

O

Note: This parameter has been deprecated.

EmailCustomer

O

Indicates whether the system will send an email to the customer after successfully processing a scheduled payment. Valid values are:

•      TRUE – Email is sent to the customer after successful payment

•      FALSE – (default) Customer is not notified after successful payment

Note: Email notifications can only be sent if a valid customer contact email has been provided in the customer record.

EmailMerchant

O

Indicates whether the system will send an email to the merchant after successfully processing a scheduled payment. Valid values are:

•      TRUE – Email is sent to the merchant after successful payment

•      FALSE – (default) Merchant is not notified after successful payment

EmailCustomerFailure

O

Indicates whether the system will send an email to the customer after failing to process a scheduled payment. Valid values are:

•      TRUE – Email is sent to the customer after failed payment

•      FALSE – (default) Customer is not notified after failed payment

Note: mail notifications can only be sent if a valid customer contact email has been provided in the customer record.

EmailMerchantFailure

O

Indicates whether the system will send an email to the merchant after failing to process a scheduled payment. Valid values are:

•      TRUE – Email is sent to the merchant after failed payment

•      FALSE – (default) Merchant is not notified after failed payment

Note: Email notifications can only be sent if a valid merchant contact email has been provided in the merchant record.

Status

O

Indicates whether the contract is currently active (reviewed each day for pending payments due) or inactive. Valid values are:

•      ACTIVE – Contract is reviewed each day for pending payments

•      INACTIVE – Contract is not reviewed for pending payments

•      PENDING – Payment had failed to process

•      CLOSED – contract has been programmatically closed and is no longer used

ExtData

O

Reserved for future use.