Step One

Three-Step: Recurring

Add Subscription to an Existing Plan

ElementDescription
<add-subscription>Associate payment information with a recurring plan.
api-key*api-key is obtained in the Security Keys section of the Control Panel Settings.
redirect-url*A URL on your web server that the gateway will redirect your customer to after sensitive data collection. Value is not required when sensitive data is not presented.
Example: Adding a Subscription using a Customer Vault ID.
customer-vault-idLoad customer details from an existing customer vault record. If set, no payment information is required during step two.
start-dateThe first day that the customer will be charged.
Format: YYYYMMDD
order-idOrder id.
po-numberCardholder’s purchase order number.
order-descriptionOrder description.
currencySet transaction currency.
Format: ISO 4217
tax-amountThe sales tax included in the transaction amount associated with the purchase. Setting tax equal to ‘-1’ indicates an order that is exampt from sales tax.
Default: 0.00′
Format: x.xx
shipping-amountTotal shipping amount.
merchant-defined-field-#Merchant specified custom fields.
Format: <merchant-defined-field-1>Value</merchant-defined-field-1>
<plan>
plan-id*The unique plan ID that references only this recurring plan.
</plan>
<billing>The customer’s billing information
billing-idSpecify billing id. Recommended when using customer vault hybrid action. Will be ignored if no hybrid add/update-customer is done.
first-nameCardholder’s first name.
last-nameCardholder’s last name.
address1Cardholder’s billing address.
cityCard billing city.
stateCard billing state/province.
Format: CC
postalCard billing postal code.
countryCard billing country code.
Format: CC/ISO 3166
phoneBilling phone number.
emailBilling email address.
companyCardholder’s company.
address2Card billing address, line 2.
faxBilling fax number.
account-type**The customer’s ACH account type.
Values: ‘checking’ or ‘savings’
entity-type**The customer’s ACH account entity.
Values: ‘personal’ or ‘business’
</billing>
<shipping>The customer’s shipping information.
shipping-idSpecify shipping id. Recommended when using customer vault hybrid action. Will be ignored if no hybrid add/update-customer is done.
first-nameShipping first name.
last-nameShipping last name.
address1Shipping address.
cityShipping city.
stateShipping state/province.
Format: CC
postalShipping postal code.
countryShipping country code.
Format: CC/ISO 3166
phoneShipping phone number.
emailShipping email address.
companyShipping company.
address2Shipping address, line 2.
faxShipping fax number.
</shipping>
</add-subscription>
*Always required
**Required for ACH transactions

Add Subscription to a Custom Plan

ElementDescription
<add-subscription>Associate payment information with a recurring plan.
api-key*api-key is obtained in the Security Keys section of the Control Panel Settings.
redirect-url*A URL on your web server that the gateway will redirect your customer to after sensitive data collection. Value is not required when sensitive data is not presented.

Example: Adding a Subscription using a Customer Vault ID.

customer-vault-idLoad customer details from an existing customer vault record. If set, no payment information is required during step two.
start-dateThe first day that the customer will be charged.

Format: YYYYMMDD

order-idOrder id.
po-numberCardholder’s purchase order number.
order-descriptionOrder description.
currencySet transaction currency.

Format: ISO 4217

tax-amountThe sales tax included in the transaction amount associated with the purchase. Setting tax equal to ‘-1’ indicates an order that is exampt from sales tax.

Default: ‘0.00’

Format: x.xx

shipping-amountTotal shipping amount.
merchant-defined-field-#Merchant specified custom fields.

Format: <merchant-defined-field-1>Value</merchant-defined-field-1>

<plan>
payments*The number of payments before the recurring plan is complete.

Notes: ‘0’ for until canceled

amount*The plan amount to be charged each billing cycle.

Format: x.xx

day-frequency***How often, in days, to charge the customer. Cannot be set with ‘month-frequency’ or ‘day-of-month’.
month-frequency****How often, in months, to charge the customer. Cannot be set with ‘day-frequency’. Must be set with ‘day-of-month’.

Values: 1 through 24

day-of-month****The day that the customer will be charged. Cannot be set with ‘day-frequency’. Must be set with ‘month-frequency’.

Values: 1 through 31 – for months without 29, 30, or 31 days, the charge will be on the last day

</plan>
<billing>The customer’s biling information
billing-idSpecify billing id. Recommended when using customer vault hybrid action. Will be ignored if no hybrid add/update-customer is done.
first-nameCardholder’s first name.
last-nameCardholder’s last name.
address1Cardholder’s billing address.
cityCard billing city.
stateCard billing state/province.

Format: CC

postalCard billing postal code.
countryCard billing country code.

Format: CC/ISO 3166

phoneBilling phone number.
emailBilling email address.
companyCardholder’s company.
address2Card billing address, line 2.
faxBilling fax number.
account-type**The customer’s ACH account type.

Values: ‘checking’ or ‘savings’

entity-type**The customer’s ACH account entity.

Values: ‘personal’ or ‘business’

</billing>
<shipping>The customer’s shipping information.
shipping-idSpecify shipping id. Recommended when using customer vault hybrid action. Will be ignored if no hybrid add/update-customer is done.
first-nameShipping first name.
last-nameShipping last name.
address1Shipping address.
cityShipping city.
stateShipping state/province.

Format: CC

postalShipping postal code.
countryShipping country code.

Format: CC/ISO 3166

phoneShipping phone number.
emailShipping email address.
companyShipping company.
address2Shipping address, line 2.
faxShipping fax number.
</shipping>
</add-subscription>
*Always required
**Required for ACH transactions
***Required unless ‘month-frequency’ and ‘day-of-month’ is set.
****Required unless ‘day-frequency’ is set.

Update Subscription Information

ElementDescription
<update-subscription>Update Customer’s information for a subscription.
api-key*api-key is obtained in the Security Keys section of the Control Panel Settings.
redirect-url*A URL on your web server that the gateway will redirect your customer to after sensitive data collection. Value is not required when sensitive data is not presented.
Example: Updating a Subscription using a Customer Vault ID.
subscription-id*The subscription that will be updated.
order-idOrder id.
po-numberCardholder’s purchase order number.
order-descriptionOrder description.
currencySet transaction currency.
Format: ISO 4217
merchant-defined-field-#Merchant specified custom fields.
Format: <merchant-defined-field-1>Value</merchant-defined-field-1>
<billing>The customer’s billing information
first-nameCardholder’s first name.
last-nameCardholder’s last name.
address1Cardholder’s billing address.
cityCard billing city.
stateCard billing state/province.
Format: CC
postalCard billing postal code.
countryCard billing country code.
Format: CC/ISO 3166
phoneBilling phone number.
emailBilling email address.
companyCardholder’s company.
address2Card billing address, line 2.
faxBilling fax number.
account-type**The customer’s ACH account type.
Values: ‘checking’ or ‘savings’
entity-type**The customer’s ACH account entity.
Values: ‘personal’ or ‘business’
</billing>
<shipping>The customer’s shipping information.
first-nameShipping first name.
last-nameShipping last name.
address1Shipping address.
cityShipping city.
stateShipping state/province.
Format: CC
postalShipping postal code.
countryShipping country code.
Format: CC/ISO 3166
phoneShipping phone number.
emailShipping email address.
companyShipping company.
address2Shipping address, line 2.
faxShipping fax number.
</shipping>
</update-subscription>
*Always Required.
**Required for ACH subscriptions.