1932
Introduction
Segpay’s Membership Upgrade API allows merchants to send an upgrade request for an active recurring subscription. This will allow you to offer your consumers a way to upgrade from a lower tier subscription to a higher tier subscription, ability to charge them a prorated amount for the new tier all while keeping their original Segpay purchase ID.
To use this new feature, you will need to be approved by compliance and configured in our system, including the whitelisting of your IP’s sending the request to Segpay. Please contact your Segpay Account manager or [email protected] to get started!
The following document will explain how to construct the API call to our system, the data returned and the additional postback information Segpay will send.
Constructing the HTTP request
To construct the HTTP POST request to Segpay, you will need to use either JSON or XML posts as well as Base Authentication.
To get your username and password for your basic authentication, please contact [email protected] and they will set one up for you if you don’t already have it.
NOTE: GET requests will NOT be supported with this product functionality nor will a regular FORM POST.
HTTP Request
|
URL |
https://api.segpay.com/purchases/{purchaseId}/upgrade |
|
Method |
POST |
|
Content-Type |
application/json, application/xml, application/x-www-form-urlencoded, multipart/form-data |
|
Accept |
application/json, application/xml |
Definition of Parameters
The following list details all the parameters that are part of the request. The only variables that are REQUIRED for the URL submission request are denoted by * in the list below.
|
Name |
Type |
Description |
Value Examples |
|
purchaseId |
Number |
An identifier of existing purchase to be upgraded. |
12345678 |
|
NewRecurringAmount |
Decimal Number |
An amount to next recurring transactions. Must be positive value in allowed range. |
10 12.67 |
|
NewRecurringDurationInDays |
String |
A number of days between recurring transactions. Must be positive value in allowed range. |
5 30 |
Definition of Results
|
Name |
Type |
Description |
Value Examples |
||
|
IsSuccess |
Boolean (true/false) |
True if membership upgrade was successful |
true false |
||
|
Message |
String |
A reason of success or failure. |
"Purchase has been upgraded successfully." |
||
|
TransactionId |
Integer Number |
This will be populated for both an approved or declined upgrade transaction. However, if the upgraded failed due to another reason such subscription is not active, it will return blank. |
12341234 |
||
|
TransactionAmount |
Decimal Number |
This is the amount of the prorated upgrade transaction. If the upgrade was not successful, this value will be blank. |
12.45 |
||
|
Purchase ID |
Integer Number |
This is the purchase ID that was sent in with the upgrade request |
23568974 |
||
|
TransactionAuthCode |
String |
This will either be OK:0 for an approved transaction or the decline reason for the prorated upgrade transaction. |
|
Examples
The following sections provides both a JSON and XML request and response to help you integrate this new feature.
JSON
Request
POST https://api.segpay.com/purchases/12345678/upgrade
Content-Type: application/json
Accept: application/json
Body:
{
"NewRecurringAmount": 34.56
"NewRecurringDurationInDays": 12
}
Response
{
"IsSuccess": true,
"Message": "Purchase has been upgraded successfully.",
“purchaseid”: 123456896
"TransactionId": 12341234,
"TransactionAmount": 15.56
"newrecurringamount": "2021-07-15"
"transactionAuthCode": "OK:0"
}
XML
Request
POST https://api.segpay.com/purchases/12345678/upgrade
Content-Type: application/xml
Accept: application/xml
Body:
<Parameters>
<NewRecurringAmount>34.56</NewRecurringAmount>
<NewRecurringDurationInDays>12</NewRecurringDurationInDays>
</Parameters>
Response
<Result>
<IsSuccess>true</IsSuccess>
<Message>Purchase has been upgraded successfully.</Message>
<Purchaseid>125996323</Purchaseid>
<TransactionId>12341234</TransactionId>
<TransactionAmount>23.07</TransactionAmount>
<newRecurringAmount>25</newRecurringAmount>
<nextTransactionDate>2021-07-15</nextTransactionDate>
<transactionAuthCode>OK:0</transactionAuthCode>
</Result>
You can mix different request and response formats using HTTP headers Content-Type and Accept.
Postbacks
For all membership upgrades, a transaction postback will be sent out if your account is configured for them. The Segpay system will automatically append the following variable to indicate that the transaction was a membership upgrade transaction.
membershipupgrade=true
Example:
https://www.yoursite.com/postbackapi/api/postbacktest/get?action=Auth&TESTRESPONSE=YesTrans2&eticketid=125696%3a3097&stage=Conversion&approved=Yes&transactiontype=Sale&subscriptionid=800005681&transaction=968955698&price=23.07¤cycode=USD&ip=1.1.1.1&initialvalue=2.00&initialperiod=30&recurringvalue=3.00&recurringperiod=30&desc=test+days&username=&password=&name=Brenda+Mathias&firstname=Jane&lastname=Segblue&email=upgrade%40segpay.com&phone=&address=&city=&state=FL&zipcode=33442&country=US&merchantpartnerid=&standin=0&xsellnum=0&time=4%2f16%2f2021+3%3a13%3a54+PM+(GMT+STANDARD+TIME)&CCLast4=8190&relatedtranid=0&CCFirst6=486895&urlid=10593&IsMobileDevice=&BrowserType=&Platform=&memberid=&session=&memberid2=&orderid=&scarequired=No&is3dsauthenticated=No&3dsauthenticationtype=&threedsversion=&membershipupgrade=true
Consumer Email notification
Each time a consumer upgrades and is approved, they will receive an email notification informing them of the prorated charge that their card on file was charged as well as information about their new recurring amount and next rebill date after the upgrade. An example of that email is shown below.
