SolidTrust Pay Integration Guide - Subscriptions

An Intro | The Wizard | A Quick Start | Parameters List | Result Parameters | Examples | Button Images

An Intro - What is this documentation for?

You can use your SolidTrust Pay account to receive payments for single and subscription items. This page gives an explanation on how to create payment buttons for your subscription items.

Using The Button Creation Wizard

If you are not a developer and do not feel comfortable reading all this documentation there is a quick way to create your payment button. You will find a button generation system after you login to your SolidTrust Pay account. Here are the steps you need to follow:
  1. Login to your SolidTrust Pay account.
  2. Click on "Subscriptions" in the members menu on the left.
  3. Click on "Manage Your Own Subscriptions".
  4. Click on "Add Subscription"
  5. Fill in the details for the subscription. All the fields are required, except "Return Url", "Notify Url" and "Cancel Url".
  6. Click on the "Add Subscription" button. The subscription item will be added and you will see it in the list of your added Subscriptions.
  7. In this newly created list,click on "Generate Form" next to the subscription item you need. The code for your subscription payment button will be generated. You can copy this code and paste it into the required pages of your website.

A Quick Start

All the payments should go to the following url:
https://solidtrustpay.com/handle.php

For the payment button to work, you must create a form using the POST method and all the parameters must be sent using the hidden fields in this form. For the button to be recognized as a subscription (and not a single-item purchase) the parameter "subscription" must be set with the value "on". Here is an example:

  <form action="https://solidtrustpay.com/handle.php" method="post">
    <input type=hidden name="merchantAccount" value="[your_stp_username]" />
    <input type=hidden name="subscription" value="on" />
    <input type=hidden name="item_id" value="[SubscriptionID]" />
    <input type=image name="cartImage" src="https://solidtrustpay.com/images/buttons/subscribebutton1.gif" />
  </form>

The example above is the shortest version of a subscription payment button that you can use. You do not put any $$ amount details into the form. This information is pulled from our database as you have already set all the parameters for your subscription item (the item is specified with its ID - set in the "item_id" field).

Parameters List

Below you can see an explanation of all the parameters that can be used for payment buttons:

Parameter Name Required Details
merchantAccount YES The receiver of the payment. Your SolidTrust Pay username or email.
subscription YES This parameter lets our system know that it is a subscription payment. Set this to "on"
item_id YES The subscription item ID. You can find this ID when you use the form generator for the subscription (in your SolidTrust Pay members area - Subscriptions List)
logo NO The URL of your logo that you wish to appear when your clients make payment via Credit Card.
Example: http://www.yoursite.com/yourlogo.gif
notify_url NO The URL where the result details will be POSTed back. Send this parameter in case you have an IPN (Instant Payment Notification) script that can capture and manage the payment result.
Example: http://www.yoursite.com/stp_capture.php
return_url NO The URL where the user will be redirected to after he or she completes the payment. On the last step of the payment there is a button labeled "Return" and when the user clicks this button, they are redirected to this URL. Use this parameter to return the user to your site.
Example: http://www.yoursite.com
cancel_url NO The URL where the user will be redirected if he cancels the payment or if the payment is not successful.
Example: http://www.yoursite.com/stp_canceled.php
testmode NO Add this parameter and set it to "ON" if you need the payment button to work in test mode. The button works like the live one, but no actual transactions will be made and the payer will not be subscribed. You can use this test mode to check your IPN script and see what parameters are sent back to your site after a payment has been made or canceled. If you do not send this parameter or if you set it to "OFF" then the button will be live and real transactions will be made.
Example: ON
user1 .. user10 NO You can add up to 10 (user1, user2, user3...) custom parameters to the form. These parameters will be sent back to your notify_url unchanged. You can use these parameters to track your site members, for example.

Result Parameters Sent Back

If you have set notify_url in your payment button code, then when a payment is complete or canceled, result parameters will be sent back to this url using the POST method. Below are all the parameters explained:

Parameter Name Sent Back Details
merchantAccount Always The receiver of the payment. Your SolidTrust Pay username or email (as you have set it in your payment button).
subscription Always This parameter lets you know that it is a subscription payment. Its value is always "on"
item_id Always The subscription ID (as assigned when you created your subscription item in your SolidTrust Pay account).
amount Always The amount paid. This is the monthly fee for the subscription (as you have set it in your members area).
fee Always The fee paid to SolidTrust Pay for the payment.
notify_url as created in the Payment Button Code Notify URL as you have set it in your Payment Button Code.
return_url as created in the Payment Button Code Return URL as you have set it in your Payment Button Code. Sent only when the user is first subscribed (the first subscription payment). On the next monthly automatic payments this parameter is not sent back.
cancel_url as you have set it in your Payment Button Code Cancel URL as you have set it in your Payment Button Code. Sent only when the user is first subscribed (the first subscription payment). On the next monthly automatic payments this parameter is not sent back.
testmode When Set In Payment Button Code Returned unchanged as you have set it in your payment button
user1 .. user10 When Set In Payment Button Code If you have set any custom parameters to the payment button code they will be sent back unchanged - sent only when the user is subscribed (the first subscription payment). On the next monthly automatic payments these parameters are not sent back.
Subscriber Always The SolidTrust Pay username of the subscriber.
subscriber_id Always The SolidTrust Pay subscriber id of the subscriber.
tr_id When Payment Is Successful Unique ID for every transaction. You will see this ID in your transaction history list (in the members area of SolidTrust Pay).
status Always The status of the payment. Three available values:
COMPLETE - when the payment is successful;
CANCELED - when the payment is canceled;
FAILED - when the automatic monthly payment fails (for example when there are not enough funds in user's balance to cover the monthly subscription fee);
subscription_status Always The status of the subscription. If the subscription is running the value is CURRENT. If the subscriber or the merchant cancels the subscription the value is CANCELLED.
unsubscribe_url Always The unique URL that your subscriber can click on to unsubscribe. You can use this in your correspondence with them - or store it in their account with you. This link is also emailed to the client when they create the subscription. .


Additionally on a successful payment you can receive a security hash, generated using the following formula:
MD5([tr_id].":".MD5([secondary_password]). ":".[amount].":".[merchantAccount].":".[payerAccount])

Use password to be used with your payment buttons. This can be found in your account under Merchant Zone => Create Payment Button Password. You can update your Payment Button Password at any time - just ensure you update the script of your site to take account of any changes you make.

So in your notify script you can generate this hash and check if the payment is valid and not altered. Here is how to do that, using PHP:
$secondary_password = 'put your payment button password here';
$secondary_password = md5($secondary_password.'s+E_a*');  //encryption for db
$hash_received = MD5($_POST['tr_id'].":".MD5($secondary_password).":".$_POST['amount']."

:".$_POST['merchantAccount'].":".$_POST['payerAccount']);

if ($hash_received == $_POST['hash']) {
    // valid payment
}
else {
    // invalid payment; the payment has been altered
}

IMPORTANT : The above php code must be on ONE line for your hash calculation. If you copy and paste the code it may go to two lines in your editor, and will be invalidated.

Examples


The Most Simple Form, including only the required fields:
  <form action="https://solidtrustpay.com/handle.php" method="post">
    <input type=hidden name="merchantAccount" value="[your_stp_username]" />
    <input type=hidden name="subscription" value="on" />
    <input type=hidden name="item_id" value="[SubscriptionID]" />
    <input type=image name="cartImage" src="https://solidtrustpay.com/images/buttons/subscribebutton1.gif" />
  </form>


Form with custom fields, your logo, notify and return URLs:
  <form action="https://solidtrustpay.com/handle.php" method="post">
    <input type=hidden name="merchantAccount" value="[your_stp_username]" />
    <input type=hidden name="subscription" value="on" />
    <input type=hidden name="item_id" value="[SubscriptionID]" />
    <input type=hidden name="logo" value="http://www.yoursite.com/yourlogo.gif" />
    <input type=hidden name="notify_url" value="http://www.yoursite.com/stp_notify.php" />
    <input type=hidden name="return_url" value="http://www.yoursite.com" />
    <input type=hidden name="cancel_url" value="http://www.yoursite.com/stp_canceled.php" />
    <input type=hidden name="user1" value="Any note that you will receive back as result parameter" />
    <input type=hidden name="user2" value="[You can put your site member ID here to recognize him/her when the payment is completed]" />
    <input type=image name="cartImage" src="https://solidtrustpay.com/images/buttons/subscribebutton1.gif" />
  </form>


Payment Button In Test Mode:
  <form action="https://solidtrustpay.com/handle.php" method="post">
    <input type=hidden name="testmode" value="on" />
    <input type=hidden name="merchantAccount" value="[your_stp_username]" />
    <input type=hidden name="subscription" value="on" />
    <input type=hidden name="item_id" value="[SubscriptionID]" />
    <input type=hidden name="notify_url" value="http://www.yoursite.com/stp_notify.php" />
    <input type=hidden name="return_url" value="http://www.yoursite.com" />
    <input type=hidden name="cancel_url" value="http://www.yoursite.com/stp_canceled.php" />
    <input type=image name="cartImage" src="https://solidtrustpay.com/images/buttons/subscribebutton1.gif" />
  </form>

Button Images

You can use our ready made images for the payment buttons. If you prefer to use your own, simply add the form field of type "image" (similar to the examples above) and put the image URL in the "src" attribute of the field. Below are all the available images, and the appropriate URLs that you can use:

Image URL
https://solidtrustpay.com/ImgDir/buttons/buynow1.gif
https://solidtrustpay.com/ImgDir/buttons/buttonSM2.gif
https://solidtrustpay.com/ImgDir/buttons/buttontinySTP.gif
https://solidtrustpay.com/ImgDir/buttons/purchase1.gif
https://solidtrustpay.com/ImgDir/buttons/subscribebutton1.gif