Membership Upgrade API

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.

The document explains how to construct the API call to our system, the data returned, and the additional postback information Segpay will send.

To use this feature, you must be approved by compliance and configured in our system, including whitelisting the IPs sending requests to Segpay. Contact your Segpay Account Manager or techsupport@segpay.com to get started.

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.

If you don't have a username and password, contact techsupport@segpay.com to get set up.

GET requests and a regular FORM POST are not supported with this product fuctionality.

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

Defining the Parameters

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

Name	Type	Description	Value Examples
`purchaseId`	Number	Identifier of existing purchase to be upgraded.	12345678
`NewRecurringAmount`	Decimal Number	Amount for next recurring transaction.	10 12.67
`NewRecurringDurationInDays`	String	Number of days between recurring transactions.	5 30

Defining the Results

Name	Type	Description	Value Examples
`IsSuccess`	Boolean	True if membership was successful.	True / False
`Message`	String	Shows success or failure message.	"Purchase has been upgraded successfully."
`TransactionId`	Integer Number	ID number for approved or declined transactions. If no ID numbers present (blank), transaction failed for other reason such as inactive subscription.	12341234
`TransactionAmount`	Decimal Number	The amount of the prorated transaction upgrade. Value is blank if unsuccessful.	12.45
`PurchaseID`	Integer Number	The purchase ID that was sent with the upgrade request.	234568974
`TransactionAuthCode`	String	This will either be OK:0 for an approved transaction or the decline reason for the prorated upgrade transaction.	"OK:0"

Examples

To help you integrate this feature, the next sections provide a JSON and an XML request and response.

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>

TIPS: 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&amp;TESTRESPONSE=YesTrans2&amp;eticketid=xxxxxx%3a3097&amp;stage=Conversion&amp;approved=Yes&amp;transactiontype=Sale&amp;subscriptionid=800005681&amp;transaction=968955698&amp;price=23.07&amp;currencycode=USD&amp;ip=1.1.1.1&amp;initialvalue=2.00&amp;initialperiod=30&amp;recurringvalue=3.00&amp;recurringperiod=30&amp;desc=test+days&amp;username=&amp;name=Brenda+Mathias&amp;firstname=Jane&amp;lastname=Segblue&amp;email=upgrade%40segpay.com&amp;phone=&amp;address=&amp;city=&amp;state=FL&amp;zipcode=33442&amp;country=US&amp;merchantpartnerid=&amp;standin=0&amp;xsellnum=0&amp;time=4%2f16%2f2021+3%3a13%3a54+PM+(GMT+STANDARD+TIME)&amp;CCLast4=8190&amp;relatedtranid=0&amp;CCFirst6=486895&amp;urlid=10593&amp;IsMobileDevice=&amp;BrowserType=&amp;Platform=&amp;memberid=&amp;session=&amp;memberid2=&amp;orderid=&amp;scarequired=No&amp;is3dsauthenticated=No&amp;3dsauthenticationtype=&amp;threedsversion=&amp;<span style="background-color: #ffff00;">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.