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.

Topics

• Subscription Service
  • General Lifecycle
  • Endpoints
    • Subscribe
    • Update Payment Method
    • Get Account Subscription Info
    • Get Subscription Info
    • Unsubscribe
    • Change Plan
  • Reply Objects
    • Account Subscription Info
    • Subscription Info
    • Payment Info
  • Request Objects
    • Payment Method
  • Credit Card Type Values
  • Error Codes

General Lifecycle

Endpoints

Subscribe

POST subscription/subscribe.json

Adds a subscription to the guest’s account by charging the given 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:

• B2B authentication
• OAuth authentication

JSON Parameters:  

• merchantId (Integer) – (required) Paytronix-assigned merchant ID in which to perform the operation in.
• printedCardNumber (String) – (required) The card of the user.
• subscriptionCode (String) – (required) Merchant-unique code used to identify a specific subscription and its associated information.
• paymentMethod (Object) – (required) See PaymentMethod (Subscription) for format of the object.
• storeCode (String) – (optional) Unique code associated with store that a subscription was set-up at.

"result": "success"

Indicates that the operation succeeded.

JSON Parameters:  

• result (String) – (required) success
• accountSubscriptionInfo (Object) – (required) Present if result=success. See AccountSubscriptionInfo for format of the object.

"result": "failure"

Indicates that the operation did not complete successfully, and any adjustments were rolled back as best as possible (if necessary).

JSON Parameters:  

• result (String) – (required) failure
• errorCode (String) – (required) The error code of the failure
• errorMessage (String) – (required) The (human readable) error message of the failure

Update Payment Method

POST subscription/updatePaymentMethod.json

Change the guest’s current 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:

• B2B authentication
• OAuth authentication

JSON Parameters:  

• merchantId (Integer) – (required) Paytronix-assigned merchant ID in which to perform the operation in.
• printedCardNumber (String) – (required) The card of the user.
• paymentMethod (Object) – (required) See PaymentMethod (Subscription) for format of the object.

"result": "success"

Indicates that the operation succeeded.

JSON Parameters:  

• result (String) – (required) success
• accountSubscriptionInfo (Object) – (required) Present if result=success. See AccountSubscriptionInfo for format of the object.

"result": "failure"

Indicates that the operation did not complete successfully, and any adjustments were rolled back as best as possible (if necessary).

JSON Parameters:  

• result (String) – (required) failure
• errorCode (String) – (required) The error code of the failure
• errorMessage (String) – (required) The (human readable) error message of the failure

Get Account Subscription Info

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:

• B2B authentication
• OAuth authentication

Query Parameters:  

• merchantId (Integer) – (required) Paytronix-assigned merchant ID in which to perform the operation in.
• printedCardNumber (String) – (required) The card of the user.

"result": "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 AccountSubscriptionInfo for format of the object.

"result": "failure"

Indicates that the operation did not complete successfully, and any adjustments were rolled back as best as possible (if necessary).

JSON Parameters:  

• result (String) – (required) failure
• errorCode (String) – (required) The error code of the failure
• errorMessage (String) – (required) The (human readable) error message of the failure

Get Subscription Info

GET subscription/subscriptionInfo.json

Get the current information about a merchant’s subscriptions.

The following authentication methods are allowed for this endpoint:

• Anonymous authentication

Query Parameters:  

• merchantId (Integer) – (required) Paytronix-assigned merchant ID in which to perform the operation in.

"result": "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 AccountSubscriptionInfo for format of the object.

"result": "failure"

Indicates that the operation did not complete successfully, and any adjustments were rolled back as best as possible (if necessary).

JSON Parameters:  

• result (String) – (required) failure
• errorCode (String) – (required) The error code of the failure
• errorMessage (String) – (required) The (human readable) error message of the failure

Unsubscribe

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:

• B2B authentication
• OAuth authentication

JSON Parameters:  

• merchantId (Integer) – (required) Paytronix-assigned merchant ID in which to perform the operation in.
• printedCardNumber (String) – (required) The card of the user.
• storeCode (String) – (optional) Unique code associated with store that a subscription was set-up at.

"result": "success"

Indicates that the operation succeeded.

jsonparam String result:  (required) success

"result": "failure"

Indicates that the operation did not complete successfully, and any adjustments were rolled back as best as possible (if necessary).

JSON Parameters:  

• result (String) – (required) failure
• errorCode (String) – (required) The error code of the failure
• errorMessage (String) – (required) The (human readable) error message of the failure

Change Plan

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:

• B2B authentication
• OAuth authentication

JSON Parameters:  

• merchantId (Integer) – (required) Paytronix-assigned merchant ID in which to perform the operation in.
• printedCardNumber (String) – (required) The card of the user.
• subscriptionCode (String) – (required) Code used to identify a specific subscription and its associated information.
• storeCode (String) – (optional) Unique code associated with store that a subscription was set-up at.

"result": "success"

Indicates that the operation succeeded.

JSON Parameters:  

• result (String) – (required) success
• accountSubscriptionInfo (Object) – (required) See AccountSubscriptionInfo for format of the object.

"result": "failure"

Indicates that the operation did not complete successfully, and any adjustments were rolled back as best as possible (if necessary).

JSON Parameters:  

• result (String) – (required) failure
• errorCode (String) – (required) The error code of the failure
• errorMessage (String) – (required) The (human readable) error message of the failure

Reply Objects

Account Subscription Info

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`.

JSON Parameters:  

• subscription (Object) – (required) Present if result=success. See SubscriptionInfo for format of the object.
• subscriptionStatus (String) – (required) One of SUBSCRIBED, SUBSCRIPTION_RENEW_FAILED, or UNSUBSCRIBE .
• subscribeDatetime (LocalDateTime) – (optional) Date and time the guest subscribed, in the format yyyy-MM-ddT00::00:00 (e.g. 2021-01-01T10:15:30).
• expirationDate (LocalDate) – (optional) Date the subscription ends, in the format: yyyy-MM-dd (e.g. 2021-12-31).
• paymentInfo (Object) – (optional) See PaymentInfo for format of the object.

Subscription Info

SubscriptionInfo

More detailed information about a subscription that the guest is subscribed to.

Note

This response object contained in AccountSubscriptionInfo. and lists information about the specific subscription.

JSON Parameters:  

• code (String) – (required) Code used to identify a specific subscription and its associated information.
• label (String) – (required) String shorthand to refer to the subscription.
• description (String) – (optional) A description of the subscription.
• price (Decimal) – (required) Cost to enroll in the subscription.
• periodicType (String) – (required) Period on which subscription becomes available, one of DAY or MONTH .
• numberOfPeriod (Integer) – (required) The length of the subscription period i.e. for a monthly subscription, periodicType is MONTH and numberOfPeriod might be 1.
• minRedemptionInterval (Integer) – (required) Minutes between redemption of subscriptions.
• acceptEnrollees (Boolean) – (required) Allow unsubscribed guests to enroll in the subscription, true or false.

Payment Info

PaymentInfo

Information about the PaymentMethod (Subscription) a guest is using.

Note

This response object contained in AccountSubscriptionInfo. and lists information about the guest’s payment method.

JSON Parameters:  

• paymentMethodType (String) – (required) One of SPREEDLY_TOKEN or SAVED_SPREEDLY_TOKEN.
• paymentTokenType (String) – (optional) One of CREDIT_CARD, APPLE_PAY, ANDROID_PAY, or GOOGLE_PAY .
• creditCardType (String) – (optional) Choose one of Credit Card Type Values
• ccLastFour (String) – (optional) Last four digits of the credit card used to make Payment.
• ccExpirationMonth (Integer) – (optional) Expiration month of the credit card used to make Payment.
• ccExpirationYear (Integer) – (optional) Expiration year of the credit card used to make Payment.
• nickname (String) – (optional) Nickname the guest sets for the Payment Method.
• tokenLastFour (String) – (required) Last four digits of the payment token.
• savedCardCode (String) – (required) This code was returned by the Payment Service endpoint savedPaymentMethod or savedPaymentMethods

Request Objects

Payment Method

PaymentMethod (Subscription)

Data about the guest’s PaymentMethod used to pay for subscription

Note

Currently, PaymentMethod is only configured with SpreedlyTokenPaymentMethod and SavedSpreedlyTokenPaymentMethod, see object for more details.

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
<any_prefix>.update_payment_method_usage_failed	Update payment method usage failed
<any_prefix>.invalid_saved_payment_method	Invalid saved payment method
<any_prefix>.payment_auth_denied	Payment authorization denied
<any_prefix>.payment_auth_failed	Payment authorization failed