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.

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:

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:

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.
  • 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:

JSON 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 associate 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

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:

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.

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

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_card Invalid card number
unsubscribe.not_subscribed Not subscribed
unsubscribe.update_account_failed Update account 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