You are using an unsupported browser. Please update your browser to the latest version on or before July 31, 2020.
close
announcement close button
Home > Set up and Manage your Account > Membership Upgrade API
Membership Upgrade API
print icon

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.

 

"OK:0"

 


 

 

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

 

Feedback
0 out of 0 found this helpful

Attachments

SegPayMembershipUpgradeAPI_Integration_Guide.pdf
scroll to top icon