SubscriptionBridge: recurring billing and subscription management system - Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Notifications: events posted to the Callback URL ======

===== Overview =====

This is a list of events that are posted to the **Callback URL** defined in the [[merchant_guide:notifications|Notification Settings]]. Some of these events are configurable on the "Events" section of the Notification Settings page (e.g. how many days after a declined payment should SubscriptionBridge reminder a customer to pay the outstanding balance?), other are not (e.g. you have no control on "when" a new customer buys a new subscription). The Notification Settings are defined at the store level within the SubscriptionBridge Merchant Center.


===== Using Events =====

Events are posted in a universal XML standard formatting.  The callback application or file you specify in your **Callback URL** must receive the event message.  Next, it must parse the message to determine the event code.  After the callback application knows event code of the message it has received it can use the GUID (unique subscription identifier) to perform a specific action.  For example, if a callback application receives a message with event code "sb_n_3a" it will know that a trail was converted to full.  The application can then parse the GUID from the message and use it to update the local database, perhaps enabling some new content or features that not available during the trial.

===== Event Messages =====

All event messages contain the same basic information:

  * GUID:  This is the unique subscription identifier returned in the [[:developer_guide:call_reference:SubscriptionRequest|SubscriptionResponse]] when you create a new subscription via the API. If you application saves the GUID after it creates a subscription, then it can use this information to manage the subscription.
  * Event_Code: This is a string that tells the application what event has just occurred. 

A typical event message will appear as follows:

  * Sample XML: <code><?xml version="1.0" encoding="utf-8"?>
<SB_Callback>
<GUID>string</GUID>
<Event_Code>sb_n_1a</Event_Code>
</SB_Callback></code>




===== Events/ Event Codes =====

==== 1. Thank You ====

  * Scenario: customer signs up for new product/service and a new subscription is created in SubscriptionBridge. There may or may not be a trial period.
  * Event Codes:
    * **sb_n_1a** - Sent to Customer: Trial Exists Message ([[http://www.earlyimpact.com/images/2009/sb_notification_trialAccount.gif|see example]])
    * **sb_n_1b** - Sent to Customer: No Trial Message
    * **sb_n_1c** - Sent to Merchant: Notification of new subscription created
    * **sb_n_1d** - Sent to Merchant: Notification of new subscription created, in which first payment is a Trial or different from regular amount.


==== 2. Trial To Expire ====

  * Scenario: new subscription included a trial period, which is about to expire. The trial may or may not have been free (could have been just a reduced rate), but in any case there is a change in the subscription amount or in the terms of the subscription.
  * Event Codes:
    * **sb_n_2a** - Sent to Customer: alert message: "N days to go"
    * **sb_n_2b** - Sent to Customer: final alert message: "M days to go" ([[http://www.earlyimpact.com/images/2009/sb_notification_trialAccountExpiring.gif|see example]])

... where the number of days ("N" and "M") is defined in the [[notifications|Notification Settings]] for the store.
==== 3. Subscription Status Switched ====

  * Scenario: new subscription included a trial period, and the trial is stopped before it was scheduled to end. The trial may be stopped directly by the customer (e.g. via the SubscriptionBridge Customer Center) or by the merchant (e.g. customer calls in or sends an email asking for the subscription to be switched to full mode).
  * Event Codes:
    * **sb_n_3a** - Sent to Customer: confirmation of subscription updated from "Trial" to "Full" status
    * **sb_n_3b** - Sent to Merchant: notification of change in subscription status

==== 4. Transaction Successful ====

  * Scenario: Regular subscription payment, charged successfully. This is not a payment receipt, since SubscriptionBridge is not the payment processor. A separate payment receipt might be sent directly by the payment gateway. This notification is instead a "Subscription Statement" which confirms that payment has been processed and provides other information on the subscription.
  * Event Codes:
    * **sb_n_4a** - Sent to Customer: subscription statement following successful payment
    * **sb_n_4b** - Sent to Customer: final subscription statement following last payment occurrence (limited time subscription)
    * **sb_n_4c** - Sent to Merchant: notification of successful payment

==== 5. Transaction NOT Successful ====

  * Scenario: Regular subscription payment that does not go through successfully. A separate "payment declined" message might be sent directly by the payment gateway. That message, however, does not tell the customer what to do next, unlike the message sent by SubscriptionBridge.
  * Event Codes:
    * **sb_n_5a** - Sent to Customer: Payment NOT OK -> Action to take
    * **sb_n_5b** - Sent to Merchant: notification of unsuccessful payment

==== 6. Subscription Balance Paid ====

  * Scenario: one or more subscription payments did not go through successfully. Therefore, there was an outstanding balance on the account, which the customer has now paid (e.g. through the SubscriptionBridge Customer Center). There is no notification for unsuccessful payment because the notification is in real time, on the payment page, since this is not an automatic payment.
  * Event Codes:
    * **sb_n_6a** - Sent to Customer: "Thank You" message for Balance Paid. Subscription Account Statement.
    * **sb_n_6b** - Send to Merchant: notification of successful customer payment against outstanding balance

==== 7. Subscription Balance Unpaid ====

  * Scenario: one or more subscription payments did not go through successfully. Therefore, there is an outstanding balance on the account. The customer has not paid the balance and a certain number of days have passed (where "P" and "Q" - the number of days mentioned below - are defined in the [[merchant_guide:notifications|Notification Settings]] area of the Merchant Center).
  * Event Codes:
    * **sb_n_7a** - Sent to Customer: P days have passed since unsuccessful payment
    * **sb_n_7b** - Sent to Customer: Q days have passed since unsuccessful payment, final notice
    * **sb_n_7c** - Sent to Merchant: notification of the 7a
    * **sb_n_7d** - Sent to Merchant: notification of the 7b
    * **sb_n_7e** - Sent to Customer: R days have passed since unsuccessful payment, action taken
    * **sb_n_7f** - Sent to Merchant: notification of action taken in 7.e

==== 8. Subscription Canceled ====

  * Scenario: the subscription has been canceled. There are different reasons for it, which lead to different notifications.
  * Event Codes:
    * **sb_n_8a** - Sent to Customer: confirmation of subscription cancellation (customer canceled the subscription)
    * **sb_n_8b** - Sent to Customer: subscription canceled for non-payment: sent R days after 7.b is sent (where "R" is the number of days after which a subscription is cancelled for non-payment, which is set in the [[merchant_guide:notifications|Notification Settings]] area of the Merchant Center)
    * **sb_n_8c** - Sent to Customer: confirmation of subscription cancellation (merchant canceled the subscription: e.g. violation of certain terms of the Merchant’s Terms and Conditions, unrelated to billing).
    * **sb_n_8d** - Sent to Merchant: notification of subscription cancellation (sent in scenario 8.a & 8.b, not needed for 8.c since the cancellation was triggered by the merchant)

==== 9. Subscription Changed ====

  * Scenario: the customer upgraded (different Packages sharing the same Plan), downgraded, added Feature(s), removed Feature(s).
  * Event Codes:
    * **sb_n_9a** - Sent to Customer: confirmation of change of Package
    * **sb_n_9b** - Sent to Customer: confirmation of change of Features
    * **sb_n_9c** - Sent to Merchant: notification of change of Package
    * **sb_n_9d** - Sent to Merchant: notification of change of Features



==== 10. New Balance ====

  * Scenario: Merchant **adds a feature** on behalf of the customer, and there is a balance due for the current billing period (pro-rated amount), or makes a **Custom Subscription Change** that is associated with a balance due for the current billing period.
  * Event Codes:
    * **sb_n_10a** - Sent to Customer: Notification of New Balance

==== 11. Credit Card Expiring ====

  * Scenario: The system detects that the credit card expiration date is before the next payment date.
  * Event Codes:
    * **sb_n_11a** - Sent to Customer: Notification of expiring credit card
    * **sb_n_11b** - Sent to Customer: Notification credit card has expired

===== Related articles =====	 
  * [[merchant_guide:notifications|Notification settings]]	 
  * [[merchant_guide:notifications_list|Notifications sent via e-mail]] \\ A list of e-mail notifications sent by SubscriptionBridge when various events happen during the life of a subscription.	 
  * [[developer_guide:developer_guide|SubscriptionBridge API home]]