Subscription Service ==================== The Subscription service allows merchants to run a subscriptions-style program for their guests. When implemented, these endpoints allow guests to manage their subscriptions with a merchant. .. contents:: Topics General Lifecycle ~~~~~~~~~~~~~~~~~~ .. image:: subscription_flow.png :align: center Endpoints ~~~~~~~~~~ Subscribe ---------- .. http:post:: subscription/subscribe.json Adds a subscription to the guest's account by charging the given :http:jsonentity:`PaymentMethod (Subscription)`. The guest's renewal date is set for one month from their enrollment date and a confirmation email is sent to the guest. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` * :ref:`oauth_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID in which to perform the operation in. :jsonparam String printedCardNumber: *(required)* The card of the user. :jsonparam String subscriptionCode: *(required)* Merchant-unique code used to identify a specific subscription and its associated information. :jsonparam Object paymentMethod: *(required)* See :http:jsonentity:`PaymentMethod (Subscription)` for format of the object. :jsonparam String storeCode: *(optional)* Unique code associated with store that a subscription was set-up at. .. http:response:: success Indicates that the operation succeeded. :jsonparam String result: *(required)* ``success`` :jsonparam Object accountSubscriptionInfo: *(required)* Present if result=success. See :http:jsonentity:`AccountSubscriptionInfo` for format of the object. .. http:response:: failure Indicates that the operation did not complete successfully, and any adjustments were rolled back as best as possible (if necessary). :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure Update Payment Method ---------------------- .. http:post:: subscription/updatePaymentMethod.json Change the guest's current :http:jsonentity:`PaymentMethod (Subscription)` for a certain subscription to a new method and see the status of the account's subscription after a successful update. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` * :ref:`oauth_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID in which to perform the operation in. :jsonparam String printedCardNumber: *(required)* The card of the user. :jsonparam Object paymentMethod: *(required)* See :http:jsonentity:`PaymentMethod (Subscription)` for format of the object. .. http:response:: success Indicates that the operation succeeded. :jsonparam String result: *(required)* ``success`` :jsonparam Object accountSubscriptionInfo: *(required)* Present if result=success. See :http:jsonentity:`AccountSubscriptionInfo` for format of the object. .. http:response:: failure Indicates that the operation did not complete successfully, and any adjustments were rolled back as best as possible (if necessary). :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure Get Account Subscription Info ------------------------------ .. http:get:: subscription/accountSubscriptionInfo.json Get the current information about a guest's subscriptions, including details about the subscription. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` * :ref:`oauth_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant ID in which to perform the operation in. :query String printedCardNumber: *(required)* The card of the user. .. http:response:: success Indicates that the operation succeeded. :jsonparam String result: *(required)* ``success`` :jsonparam List[Object] subscriptions: *(required)* List of subscriptions associated with the guest's account, present if result=success. See :http:jsonentity:`AccountSubscriptionInfo` for format of the object. .. http:response:: failure Indicates that the operation did not complete successfully, and any adjustments were rolled back as best as possible (if necessary). :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure Get Subscription Info --------------------- .. http:get:: subscription/subscriptionInfo.json Get the current information about a merchant's subscriptions. The following authentication methods are allowed for this endpoint: * :ref:`anonymous_auth` :query Integer merchantId: *(required)* Paytronix-assigned merchant ID in which to perform the operation in. .. http:response:: success Indicates that the operation succeeded. :jsonparam String result: *(required)* ``success`` :jsonparam List[Object] subscriptions: *(required)* List of subscriptions associated with the merchant, present if result=success. See :http:jsonentity:`AccountSubscriptionInfo` for format of the object. .. http:response:: failure Indicates that the operation did not complete successfully, and any adjustments were rolled back as best as possible (if necessary). :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure Unsubscribe ------------ .. http:post:: subscription/unsubscribe.json Cancel a guest's subscription. This will send an email to the guest notifying them of the cancellation and remove the guest's credit card information form the database. The guest will still have access to benefits until expiration date. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` * :ref:`oauth_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID in which to perform the operation in. :jsonparam String printedCardNumber: *(required)* The card of the user. :jsonparam String storeCode: *(optional)* Unique code associated with store that a subscription was set-up at. .. http:response:: success Indicates that the operation succeeded. :jsonparam String result: *(required)* ``success`` .. http:response:: failure Indicates that the operation did not complete successfully, and any adjustments were rolled back as best as possible (if necessary). :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure Change Plan ------------ .. http:post:: subscription/changePlan.json Change a guest's subscription plan to another. This will send an email to the guest notifying them of the enrollment in the new subscription plan. The new plan will take effect after the guest's current plan expires. The following authentication methods are allowed for this endpoint: * :ref:`b2b_auth` * :ref:`oauth_auth` :jsonparam Integer merchantId: *(required)* Paytronix-assigned merchant ID in which to perform the operation in. :jsonparam String printedCardNumber: *(required)* The card of the user. :jsonparam String subscriptionCode: *(required)* Code used to identify a specific subscription and its associated information. :jsonparam String storeCode: *(optional)* Unique code associated with store that a subscription was set-up at. .. http:response:: success Indicates that the operation succeeded. :jsonparam String result: *(required)* ``success`` :jsonparam Object accountSubscriptionInfo: *(required)* See :http:jsonentity:`AccountSubscriptionInfo` for format of the object. .. http:response:: failure Indicates that the operation did not complete successfully, and any adjustments were rolled back as best as possible (if necessary). :jsonparam String result: *(required)* ``failure`` :jsonparam String errorCode: *(required)* The error code of the failure :jsonparam String errorMessage: *(required)* The (human readable) error message of the failure Reply Objects ~~~~~~~~~~~~~ Account Subscription Info --------------------------- .. http:jsonentity:: AccountSubscriptionInfo Information about the subscription available for a guest's account. .. note:: This response object is returned on success from subscription endpoints ```updatePaymentMethod```, ```subscribe```, and ```getAccountSubscriptionInfo```. :jsonparam Object subscription: *(required)* Present if result=success. See :http:jsonentity:`SubscriptionInfo` for format of the object. :jsonparam String subscriptionStatus: *(required)* One of ``SUBSCRIBED``, ``SUBSCRIPTION_RENEW_FAILED``, or ``UNSUBSCRIBE`` . :jsonparam LocalDateTime subscribeDatetime: *(optional)* Date and time the guest subscribed, in the format ``yyyy-MM-ddT00::00:00`` (e.g. ``2021-01-01T10:15:30``). :jsonparam LocalDate expirationDate: *(optional)* Date the subscription ends, in the format: ``yyyy-MM-dd`` (e.g. ``2021-12-31``). :jsonparam Object paymentInfo: *(optional)* See :http:jsonentity:`PaymentInfo` for format of the object. Subscription Info ------------------ .. http:jsonentity:: SubscriptionInfo More detailed information about a subscription that the guest is subscribed to. .. note:: This response object contained in :http:jsonentity:`AccountSubscriptionInfo`. and lists information about the specific subscription. :jsonparam String code: *(required)* Code used to identify a specific subscription and its associated information. :jsonparam String label: *(required)* String shorthand to refer to the subscription. :jsonparam String description: *(optional)* A description of the subscription. :jsonparam Decimal price: *(required)* Cost to enroll in the subscription. :jsonparam String periodicType: *(required)* Period on which subscription becomes available, one of ``DAY`` or ``MONTH`` . :jsonparam Integer numberOfPeriod: *(required)* The length of the subscription period i.e. for a monthly subscription, ``periodicType`` is ``MONTH`` and ``numberOfPeriod`` might be 1. :jsonparam Integer minRedemptionInterval: *(required)* Minutes between redemption of subscriptions. :jsonparam Boolean acceptEnrollees: *(required)* Allow unsubscribed guests to enroll in the subscription, ``true`` or ``false``. Payment Info ------------- .. http:jsonentity:: PaymentInfo Information about the :http:jsonentity:`PaymentMethod (Subscription)` a guest is using. .. note:: This response object contained in :http:jsonentity:`AccountSubscriptionInfo`. and lists information about the guest's payment method. :jsonparam String paymentMethodType: *(required)* One of ``SPREEDLY_TOKEN`` or ``SAVED_SPREEDLY_TOKEN``. :jsonparam String paymentTokenType: *(optional)* One of ``CREDIT_CARD``, ``APPLE_PAY``, ``ANDROID_PAY``, or ``GOOGLE_PAY`` . :jsonparam String creditCardType: *(optional)* Choose one of :ref:`card_type_values` :jsonparam String ccLastFour: *(optional)* Last four digits of the credit card used to make Payment. :jsonparam Integer ccExpirationMonth: *(optional)* Expiration month of the credit card used to make Payment. :jsonparam Integer ccExpirationYear: *(optional)* Expiration year of the credit card used to make Payment. :jsonparam String nickname: *(optional)* Nickname the guest sets for the Payment Method. :jsonparam String tokenLastFour: *(required)* Last four digits of the payment token. :jsonparam String savedCardCode: *(required)* This code was returned by the Payment Service endpoint ``savedPaymentMethod`` or ``savedPaymentMethods`` Request Objects ~~~~~~~~~~~~~~~ Payment Method --------------- .. http:jsonentity:: PaymentMethod (Subscription) Data about the guest's PaymentMethod used to pay for subscription .. note:: Currently, PaymentMethod is only configured with :http:jsonentity:`SpreedlyTokenPaymentMethod` and :http:jsonentity:`SavedSpreedlyTokenPaymentMethod`, see object for more details. .. _card_type_values: Credit Card Type Values ~~~~~~~~~~~~~~~~~~~~~~~ ``AMEX`` American Express ``DINERS_CLUB`` Diners Club ``DISCOVER`` Discover ``JCB`` JCB ``MASTERCARD`` MasterCard ``VISA`` Visa ``ALELO`` Alelo ``CABAL`` Cabal ``CARNET`` Carnet ``DANKORT`` Dankort ``ELO`` Elo ``MAESTRO`` Maestro ``NARANJA`` Naranja ``SODEXO`` Sodexo ``VR`` Vr Error Codes ~~~~~~~~~~~ The following are the possible codes and messages that can be returned by the Subscription Service. There are other system-level errors which may be returned which are not documented here. The caller of the endpoint can use the returned message to display to the end user or, if different wording is desired, can provide their own mapping of code to message. +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | Code | Message | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``subscribe.server_error`` | Internal server error | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``subscribe.invalid_merchant`` | Invalid merchant | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``subscribe.invalid_card`` | Invalid card number | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``subscribe.invalid_subscription`` | Invalid subscription | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``subscribe.invalid_subscription_code`` | Invalid subscription code | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``subscribe.card_already_subscribed`` | Card is already subscribed | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``subscribe.not_available_to_card`` | Subscription not available to card | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``subscribe.invalid_payment_method`` | Invalid payment method | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``subscribe.save_payment_method_failed`` | Save payment method failed | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``subscribe.update_payment_method_usage_failed`` | Update payment method usage failed | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``subscribe.invalid_saved_payment_method`` | Invalid saved payment method | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``subscribe.payment_auth_failed`` | Payment authorization failed | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``subscribe.payment_capture_denied`` | Payment capture denied | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``subscribe.payment_capture_failed`` | Payment capture failed | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``subscribe.create_payment_detail_failed`` | Create payment detail failed | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``subscribe.update_payment_detail_failed`` | Update payment detail failed | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``subscribe.update_account_failed`` | Update account failed | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``subscribe.closed_to_new_enroll`` | Subscription closed to new enrollment | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``update_payment_method.server_error`` | Internal server error | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``update_payment_method.invalid_merchant`` | Invalid merchant | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``update_payment_method.invalid_card`` | Invalid card number | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``update_payment_method.invalid_subscription`` | Invalid subscription | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``update_payment_method.invalid_subscription_code`` | Invalid subscription code | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``update_payment_method.not_subscribed`` | Not subscribed | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``update_payment_method.get_current_payment_method_failed`` | Cannot find current payment method for subscription | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``update_payment_method.invalid_payment_method`` | Invalid payment method | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``unsubscribe.server_error`` | Internal server error | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``unsubscribe.invalid_merchant`` | Invalid merchant | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``unsubscribe.invalid_subscription_code`` | Invalid subscription code | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``unsubscribe.invalid_subscription`` | Invalid subscription | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``unsubscribe.invalid_card`` | Invalid card number | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``unsubscribe.not_subscribed`` | Not subscribed | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``unsubscribe.update_account_failed`` | Update account failed | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``change_plan.server_error`` | Internal server error | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``change_plan.invalid_merchant`` | Invalid merchant | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``change_plan.invalid_card`` | Invalid card number | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``change_plan.invalid_saved_payment_method`` | Invalid saved payment method | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``change_plan.invalid_subscription_code`` | Invalid subscription code | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``change_plan.invalid_subscription`` | Invalid subscription | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``change_plan.card_already_subscribed`` | Card is already subscribed | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``change_plan.not_available_to_card`` | Subscription not available to card | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``change_plan.update_account_failed`` | Update account failed | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``change_plan.closed_to_new_enroll`` | Subscription closed to new enrollment | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``change_plan.not_subscribed`` | Not subscribed | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``change_plan.unsubscribe_failed`` | Unsubscribe failed | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``change_plan.subscribe_failed`` | Subscribe failed | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``account_subscription_info.server_error`` | Internal server error | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``account_subscription_info.invalid_merchant`` | Invalid merchant | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``account_subscription_info.invalid_card`` | Invalid card number | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``account_subscription_info.get_current_payment_method_failed`` | Cannot find current payment method for subscription | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``recharge.save_payment_method_failed`` | Save payment method failed | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``.update_payment_method_usage_failed`` | Update payment method usage failed | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``.invalid_saved_payment_method`` | Invalid saved payment method | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``.payment_auth_denied`` | Payment authorization denied | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+ | ``.payment_auth_failed`` | Payment authorization failed | +---------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------+