Documentation
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
| Parameter | Required | Possible values | Description |
|---|---|---|---|
| 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* |
|
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 |
|
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 |
|
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 |
|
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.
