Recurring Charges

Recurring charges are subscription payments that are linked to a customer record. Customers are billed $X.XX every X days. Recurring charges can be linked to Recurring Plans via a plan_id or can be independent subscriptions.

Recurring charges that do not have a free trial are processed immediately via the gateway specified by the gateway_id in the request or by the default gateway associated with the API client. If there is only one gateway associated with the API account, this gateway will be for the charge and all subsequent charges related to the subscription.

Notifications

You have the option of specifying a notification_url for each subscription created. These notification URL's can also be specified in Recurring Plans. If a subscription is linked to a notification_url, an HTTP POST request will be sent to this URL when any of the following actions occur:

• Charge (posted as: "charge")
• New Recurring (posted as: "new_recurring")
• Recurring Charge (posted as: "recurring_charge")
• Recurring Expiration (posted as: "recurring_expire")
• Recurring Cancellation (posted as: "recurring_cancel")
• Recurring to Expire in a Week (posted as: "recurring_expiring_in_week")
• Recurring to Expire in a Month (posted as: "recurring_expiring_in_month")
• Recurring to Autocharge in a Week (posted as: "recurring_autorecur_in_week")
• Recurring to Autocharge in a Month (posted as: "recurring_autorecur_in_month")
• New Customer (posted as: "new_customer")

Each HTTP POST request will include the following variables:

• "action" - The action that tripped the notification (one from the list above).
• "client_id" - Your client ID.
• "secret_key" - Your API secret key.
• "plan_id" - The ID of the plan.
• "customer_id" - The ID of the customer.
• "recurring_id" - The ID of the recurring subscription.
• "charge_id" - The ID of the specific charge, if the event relates to a charge.

Method: Recur

A Recur request creates a subscription via a payment gateway. One makes a request of this type to charge a credit card at a consistent interval.

All individual charges for a recurring subscription are stored in the charges database and returned in GetCharge and GetCharges requests. These request will return a recurring_id - the ID of the recurring payment scheme that generated the individual charge.

Recur requests can be linked to customers via either a customer_id or an embedded customer node embedded within this request to the API. For more information on embedding customer data in a Recur request, see the customers page. If neither a customer_id or customer node are included in the request, a customer record will be created automatically from the included credit_card > name variable. Because of this procedure, all recurring charges are linked to a customer record.

How to charge a different fee for the first interval (e.g. charge $2.99 up-front but $9.99 per month afterwards):
To charge a different fee for the first interval than subsequent intervals, specify a different value for the parent amount parameter. Then, if you aren't using a plan, specify the recurring fee in recur > amount. If you are using a plan, the latter parameter is not required.

How to add a free recurring charge to an account (e.g., to link a customer to a plan):
Pass amount and recur > amount as "0". Complete dummy credit card information with "0000000000000000" as the credit card number and any future expire date. Your gateway will not be passed this charge.

Request data:

Variable	Type	Required	Format/Example
amount	money	yes	e.g. "45.67". This amount is charged upon creation of the subscription. This price will be charged for the first recurring interval.
coupon	string		A coupon code that relates to a coupon in the database (e.g., "TEST123"). If the coupon code is invalid, it will be ignored.
credit_card	node	yes	All credit card sub-nodes must be included with accurate credit card information regarding the purchaser.
card_num	int	yes	The purchaser's credit card number, e.g. "1234567809876543".
name	string	yes	The purchaser's name. This must match the name on the credit card.
exp_month	int	yes	The purchaser's credit card expiry month with 2-digit representation, e.g. "10".
exp_year	int	yes	The purchaser's credit card expiry year with 2-digit representation, e.g. "14".
cvv	int	yes	The purchaser's credit card CVV2/security number. It's required for any card where it is available. If not available on the card, send this parameter as empty.
gateway_id	int		The system ID for the payment gateway used for the charge. If left empty, the default/only gateway will be used.
customer_id	int		The ID of the customer to link the charge to, e.g. "4". Only include this parameter if you are not embedding customer information below. Charges do not need to be linked to a customer.
customer	node		Include sub-nodes with any/all available customer data. For more information, see the "Embedding customer data in Charge/Recur requests" on the customers page. Only include this parameter if you are not including a customer_id. Charges do not need to be linked to a customer.
customer_ip_address	string		You can optionally send the purchaser's IP address.
renew	int		If an existing "recurring_id" is passed in this parameter, expiration notices/POSTS will not be sent for the old subscription, because we know that this new subscription is renewing it.
recur	node	yes	The "recur" node specifies the characteristics of this subscription payment.
plan_id	int		To use a set of pre-determined and shared characteristics for a subscription payment, it can be linked to a plan_id. This gives the added ability to check which plans a customer is currently subscribed to with GetCustomer, or pull all customers who are currently subscribed to a plan with GetCustomers and the optional plan_id filter. If a plan_id is given, no other parameters are required in the recur node. However, if you pass any other parameters, they will override the plan's default values. For example, passing an amount parameter in the recur node will change the subscription fee altogether.
interval	int		Required if no plan_id is passed. The interval is the number of days between subscription payments. For example, a monthly subscription could be represented as an interval of "30" or "31".
amount	money		The amount to charge the user every "interval" days. If not included in the request, it will default to the plan's amount (if a plan_id is passed) and, if not linked to plan, the main amount parameter will be used.
free_trial	int		The number of days to wait before charging the first subscription payment. If passed, this will override the start_date value.
occurrences	int		The total number of times to charge the user (inclusive of the first charge).
start_date	shortdate		This is the date at which you would like to start the subscription payments. It will override the start_date automatically created by a free_trial, if given.
end_date	shortdate		The date at which this recurring charge will never be charged again to the customer. If passed, this will override the occurrences value.

Response data:

• response_code - "100" upon success, "2" upon failure.
• response_text - A verbose description of the response_code.
• recurring_id - The ID of the recurring charge.
• charge_id - The ID of the charge record, if the a charge was made immediately. Recurring charges are only delayed if a start_date after today is passed or if a free_trial value is set.
• customer_id - The ID of the new customer created and linked to the recurring charge. This is only returned if a customer_id was not passed in the request (and thus a new customer record was created).
• amount - The amount of the initial charge, useful for coupon-adjusted requests.
• recur_amount - The amount of the recurring charge.
• free_trial - The number of days prior to the start of the subscription.
• start_date - The start date of the subscription.

Method: UpdateCreditCard

Updates the credit card associated with a subscription.

Required data:

• recurring_id
• credit_card
  • card_num
  • name
  • exp_month
  • exp_year
  • cvv (optional)

Optional data:

• plan_id

Response data:

• response_code - "104" upon success, "105" upon failure.
• response_text - A verbose description of the response_code.
• recurring_id - The ID of the NEW recurring charge. ReceivePay creates a new subscription from this new data.

Method: GetRecurring

Retrieves available information about a recurring charge.

Required data:

• recurring_id - The ID of the recurring charge.

Response data:

Variable	Type	Required	Format/Example
id	automatic		123456789
gateway_id	int		The system ID for the payment gateway used for each charge related to this recurring charge.
date_created	shortdate		The date that the recurring charge was created.
amount	money	yes	The amount of the recurring charge, e.g. "45.67"
interval	int		The number of days between subscription charges.
start_date	shortdate		The start date of the subscription.
end_date	shortdate		The date at which this subscription will not be charged again.
next_charge_date	shortdate		The date that the next subscription payment will be made.
number_occurrences	int		The number of times that the "amount" will be charged to the customer, inclusive of the first payment.
notification_url	string		The URL at which notifications will be posted to. Empty if no URL is set.
status	int		Either "active" or "inactive", depending on if the subscription is ongoing or completed/cancelled.
customer	node		A node containing all available customer information for the customer linked to this recurring charge.
id	automatic		123456789
internal_id	string		A username or user ID in your own records, e.g. "Simulatedusername", "98765432".
first_name	string	yes	Joe
last_name	string	yes	Smith
address_1	string		12345 Simulated St.
address_2	string		For apartment/unit/suite #'s, eg. "Unit 2".
city	string		Toronto
state	string		The state/province/region of the customer, eg. "ON".
country	country		The ISO 3166-1 alpha-2 code of the customer's country, e.g. "CA", "US".
postal_code	string		The zip or postal code of the user, e.g. "A1B2C3", "90210".
email	email		A valid email address for the customer.
phone	string		1-555-555-0000
date_created	date		The date the customer record was created, e.g. 2009-05-29 04:44:04
plan	node		If this recurring charge is linked to a Recurring Plan, the plan information is returned in a node.
id	int		The ID of the linked plan.
type	string		Either "free" or "paid" depending on the price of the subscription.
name	string		The name of the recurring plan.
amount	money		The amount charged at each interval.
interval	int		The number of days between each individual charge for the recurring charge.
notification_url	string		The URL to POST notifications to for recurring charges of this plan type.

Method: GetRecurrings

Returns records of recurring charges, with optional filters. If a request is made without any filters, the latest created 100 active recurring charges are returned.

Optional filters:

• id
• gateway_id
• customer_id
• customer_last_name
• customer_internal_id
• created_before - A date in the format of date.
• created_after - A date in the format of date.
• amount - Only pull recurring charges that charge this amount.
• active - Set to "0" to retrieve inactive recurring charges. Default: "1" (only active recurring charges).
• plan_id - Only retrieve recurring charges linked to this plan.
• offset - Retrieval will begin after offset # of records. Useful for pagination. Default: 0.
• limit - The total number of records to retrieve, beginning at the offset. Maximum: 100. Default: 100.
• sort - The field on which to sort retrieved records. Default: "date". Available values:
  • customer_first_name
  • customer_last_name
  • date (the date the recurring charge was created)
  • amount
• sort_dir - The direction in which to sort retrieved records. Default: "desc". Can also be "asc".

Response data:

• results - Number of records in this response
• total_results - Total # of records to retrieve. Use offset to gather all records over multiple iterated requests.
• recurrings
  • A recurring node for each returned recurring charge
    • All data available for the recurring charge, in the format of GetRecurring.

Method: ChangeRecurringPlan

Change the plan of a recurring charge. This will update the interval, amount, notification_url, and plan_id of the recurring charge. It will not affect the start_date, end_date, date_created, or total_occurrences.

Required data:

• recurring_id - The ID of the recurring charge.
• plan_id - The ID of the new plan to link the recurring charge too.

Response data:

• recurring_id - The ID of the updated recurring charge.

Method: UpdateRecurring

Updates a recurring charge.

Required data:

• recurring_id

Optional data that can be updated:

• recurring_id
• customer_id
• notification_url
• amount
• recur
  • interval

Method: CancelRecurring

Cancels an active recurring charge.

Required data:

• recurring_id