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.

IMPORTANT: To use this 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.

Contact your Segpay Account manager or techsupport@segpay.com to get started!

The document explains 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.

IMPORTANT: Contact techsupport@segpay.com to get your username and password set up 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

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

Defining the 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.

"OK:0"

Examples

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

JSON

Request:

Copy

POST https://api.segpay.com/purchases/12345678/upgrade
Content-Type: application/json
Accept: application/json

Body:

Copy

{

  "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:

Copy

POST https://api.segpay.com/purchases/12345678/upgrade
Content-Type: application/xml
Accept: application/xml

Body:

Copy

<Parameters> 
  <NewRecurringAmount>34.56</NewRecurringAmount>
  <NewRecurringDurationInDays>12</NewRecurringDurationInDays>

</Parameters>

Response:

Copy

<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&TESTRESPONSE=YesTrans2&eticketid=125696%3a3097&stage=Conversion&approved=Yes&transactiontype=Sale&subscriptionid=800005681&transaction=968955698&price=23.07&currencycode=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.