Paymentwall website uses cookies to store your browsing preferences on your device. However, cookies do not collect personal information.

For more information about how we use cookies, check our cookie policy

Close

Documentation

New Documentation Getting Started API Libraries APIs Checklists Flows Integrations Mobile SDKs Reference Smart TV SDK SpiderPipe Testing Payments
Contacts
If you still have questions regarding integration, please email us at devsupport@paymentwall.com

Subscription Changes - Upgrade API

Introduction

Upgrade API allows merchants to change existing recurring subscription plans for certain payment methods (credit cards).

This API can be activated by request. Please contact devsupport@paymentwall.com to activate it.


Request

Request URL

https://api.paymentwall.com/api/subscriptions-master/upgrade

Request method

GET

Protocols supported

http, https

Parameters
ParameterRequiredPossible valuesDescription
key yes hexadecimal, 32 characters long Project key, can be found in General Settings of the Project inside of your Merchant Account
ref yes alphanumeric Transaction ID issued by Paymentwall, communicated in pingbacks and associated with the subscription plan that should be altered. Sample ref: b123456789
amount yes numeric, with . as decimal delimiter Value of the recurring transaction, e.g. 10.00
currencyCode yes ISO 4217 Currency of the recurring transaction, e.g. USD, EUR
ag_name yes alphanumeric, up to 256 characters long Product name
ag_external_id yes alphanumeric, up to 256 characters long Alphanumeric ID of the product in your system, which we communicate back to you via the pingback as goodsid parameter.
ag_type yes subscription subscription type is used for time based products, e.g. 3 month membership
ag_period_length yes* numeric Length of product period, e.g. 3. Required when ag_type is subscription.
ag_period_type yes*
  • year
  • month
  • week
  • day
Type of product period. Required when ag_type is subscription.
ag_recurring yes 1 Whether the product is recurring.
Recurring billing is supported only when ag_type is
subscription.
ag_offset_period_length no numeric Length of offset period, e.g. 3. Used to delay the recurring cycle, e.g free trials. Counted from the moment the upgrade happened. If not present, the next transaction will happen as previously scheduled in the subscription being updated.
ag_offset_period_type no
  • year
  • month
  • week
  • day
Type of offset period. Required when ag_offset_period_length is used.
onetime_amount 1 no numeric, with . as decimal delimiter Value of the one time fee. Can be used to charge for changing the subscription plan.
onetime_currencyCode 1 no ISO 4217 Currency of the one time fee, e.g. USD, EUR. Required when ag_trial is 1.
ag_onetime_name 1 no alphanumeric, up to 256 characters long Name of one time fee product.
ag_onetime_external_id 1 no alphanumeric, up to 256 characters long Alphanumeric ID of the one time fee product in your system, which we communicate back to you via the pingback as goodsid parameter.
ag_onetime_type 1 no
  • fixed
  • subscription
Subscription type is used for time based products, e.g. 3 month membership; fixed is used for one time payments, like an upgrade fee.
ag_onetime_period_length 1 no numeric Length of product period, e.g. 3.
ag_onetime_period_type 1 no
  • year
  • month
  • week
  • day
Type of product period.
sign_version yes 3 Version of signature.
sign yes hexadecimal, 32 characters long, lowercase Request signature. All parameters in request need to be signed. Refer to signature calculation section below

1 - Fields for one time fee

Signature

sign – request signature. It is a required parameter. Please refer to Signature Calculation for details.

Response

Sample responses:

{"status":"FAIL","errors_codes":[8],"errors_readable":["Requested subscription plan is disabled"]}

{"status":"OK"}}

Pingback

For every payment, a pingback will be sent as usual according to Digital Goods API.


Use Cases

A user is subscribed to Basic package for 10 USD / month and is billed every month on the 1st. The user wants to upgrade to Pro package for 20 USD / month in the middle of his current subscription period - on the 15th. Here are the possible business scenarios (defined by your business logic):

  • If you would like to charge a fee for immediate transition and keep the recurring billing schedule unchanged, this can be done via one time payment (specified using parameters with onetime in the parameter name).

    In the example listed above:
    Recurring transaction amount will be changed to 20 USD.
    One time payment can be 5 USD (Basic package was used for a half of this month, so the user used 5 USD out of 10 USD he paid this month and still has 5 USD available; to use Pro for the other half of the month he would have to pay 10 USD; thus he needs to pay 5 USD more to use Pro for the rest of this month).

    The following payments should be used:
    Recurring transaction = 20 USD
    One time fee = 5 USD

  • If you would like to change the recurring billing schedule.
    You can avoid using one time payment parameters and instead use the following parameters:

    ag_offset_period_length=1
    ag_offset_period_type=day

    In this case the next recurring charge will happen next day. Subsequent recurring charges will happen based on the schedule specified by parameters ag_period_length and ag_period_type. E.g. if you specify ag_period_type=month, ag_period_length=1, charges will happen monthly after the first new charge happens.

  • Finally, you can switch the user immediately, but neither charge him a transition fee nor adjust his recurring billing schedule, but adjust the recurring billing amount.
    In this case neither offset, nor one time parameters need to be used.
This page needs JavaScript
Your browser is
not supported anymore.
Please update to the more recent one.
This page needs JavaScript
This page needs JavaScript.
Please enable it in your browser settings and try again.
We use cookies on this website to make your browsing experience better. By using the Paymentwall website you agree to our Cookie Policy.