SolidTrust Pay Integration Guide - Payment Button For PENDING TRANSACTION Items

An Intro | 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 items. Using this IPN will allow you to receive member to member payments automatically. These payments are set to PENDING and are of particular use to Exchangers - where all payments are reviewed prior to approval.

This IPN is recommended if you expect to receive very high volumes of payments which could result in a delayed response to your CONFIRM_URL. As each payment is confirmed in our system, the availability of the confirm_url is checked prior to the details being POSTed back. In the even of a server lag or delay, the payment is simply attempted again every 5 seconds until completed.

A Quick Start

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

For the payment button to work, you must create a form using the POST method and all the parameters you send should use hidden fields. Here is an example:
  <form action="https://solidtrustpay.com/handle_accver.php" method="post">
    <input type=hidden name="merchantAccount" value="your_stp_username" />
    
<input type=hidden name="amount" value="899.99" />
    <input type=hidden name="currency" value="USD" />

    <input type=hidden name="item_id" value="My Best Seller" />

    <input type=hidden name="confirm_url" value="http://www.yoursite.com/stpconfirm.php" />
    <input type=image name="cartImage" src="https://solidtrustpay.com/ImgDir/buttons/buynow1.gif" />
  </form>

The example above is the shortest version of the payment button that you may use. The item name is "My Best Seller" and its price is $899.99. The payment will go to your account if you replace your_stp_username above with your SolidTrust Pay username. The payment will show as pending.

Parameters List

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

Valid Currencies: USD,EUR,GBP,ZAR,AUD,CAD,JPY,NZD,RUB

Parameter Name Required Details
merchantAccount YES The receiver of the payment. Your SolidTrust Pay username.
item_id YES The item ID or name that you are selling.
Example: My First Book On Sale This item cannot be edited by the payor.
We strongly recommend this item be a unique identifier, as this field is also POSTed back to your confirm_url and can be used to identify the payment.
amount YES The price of the item in USD. Do not add any currency signs - use only a number.
Example 1: 9.99
Example 2: 4
currency YES The currency you would like to trade in.
Example 1: USD
Example 2: EUR
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
confirm_url YES

The URL where the updated transaction result status details will be POSTed back.
** Please note: refer to confirm url result parameters sent back table below, as this differs from the notify_url result parameters. http://www.yoursite.com/stp_confirm.php

return_url NO The URL where the user will be redirected to after he completes the payment. On the last step of the payment there is a button labeled "Return" and when the user clicks this button he is redirected to this URL. Use this parameter to redirect the user back to your site.
Example: http://www.yoursite.com
return_method NO The HTTP method for return. 'GET' or 'POST'. Default is 'POST';
cancel_url NO The URL where the user will be redirected to if he/she 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. You can use this test mode to check your IPN script and see what parameters are sent back to your site when payment is made or canceled. NOTE: 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 when a payment is completed or canceled, result parameters will be sent back to this url using POST method. Below are all the parameters explained:

Parameter Name Sent Back Details
merchantAccount Always The receiver of the payment. Your SolidTrust Pay username (as you have set it in your payment button).
item_id Always The item ID or name that you are selling (as you have set it in your payment button).
amount Always The price of the item in your choice of currency (as you have set it in your payment button). This is the actual amount transferred to your account when the payment is successful.
notify_url When Set In Payment Button Code Notify URL (as you have set it in your payment button).
return_url When Set In Payment Button Code Return URL (as you have set it in your payment button).
cancel_url When Set In Payment Button Code Cancel URL (as you have set it in your payment button).
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.
memo Always A comment from the payer. This can be empty if the user did not enter any comments.
payerAccount When Payment Is Successful The SolidTrust Pay username of the payer.
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

** Note: Status will always come back as pending on initial accepted completion of the transaction. Once the transaction has been confirmed then you will get a further POST result to your confirm_url.

Always

The status of the payment. Three available values:


COMPLETE - when the payment is successful;
PENDING - transaction still has to be cleared;
CANCELED - when the payment is canceled;



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

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

Confirm URL Result Parameters Sent Back

The confirm_url is required for this IPN.

Below are all the parameters explained:

Parameter Name Sent Back Details

stp_transact_status

** Note: This will tie up to the status in the initial parameters sent back above. Once the transaction has been confirmed then you will get a further POST result to your NOTIFY url.

Always

The status of the payment request in your Solidtrustpay Account.
Valid field values are;

PENDING - transaction still has to be cleared

COMPLETE - transaction cleared and funds available in your account (this status is only sent to notify url once transaction is cleared by our payments/investigations staff)

date Always Date and time of transaction
tr_id Always SolidTrustPay Transaction ID
amount Always The price of the item. This is the actual amount transferred to your account when the payment is successful, less processing fees.
member Always SolidTrust Pay username
item_id Always Your item id of the product purchased
email Always Member's email address
memo Always A comment from the purchaser. This can be empty if the user did not include any comments.

 

Examples


The Most Simple Form, including only the required fields:
  <form action="https://solidtrustpay.com/handle_accver.php" method="post">
    <input type=hidden name="merchantAccount" value="your_stp_username" />
    <input type=hidden name="amount" value="899.99" />

    <input type=hidden name="currency" value="USD" />

    <input type=hidden name="item_id" value="My Best Seller" />

    <input type=hidden name="confirm_url" value="http://www.yoursite.com/stp_confirm.php" />
    <input type=image name="cartImage" src="https://solidtrustpay.com/ImgDir/buttons/buynow1.gif" />
  </form>


Form with custom fields, notify and return URLs:
  <form action="https://solidtrustpay.com/handle_accver.php" method="post">
    <input type=hidden name="merchantAccount" value="your_stp_username" />
    <input type=hidden name="amount" value="899.99" />

    <input type=hidden name="currency" value="USD" />

    <input type=hidden name="item_id" value="My Best Seller" />
    <input type=hidden name="notify_url" value="http://www.yoursite.com/stp_notify.php" />
    <input type=hidden name="confirm_url" value="http://www.yoursite.com/stp_confirm.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/ImgDir/buttons/buynow1.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="amount" value="899.99" />
    <input type=hidden name="currency" value="USD" />

    <input type=hidden name="item_id" value="My Best Seller" />
    <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/ImgDir/buttons/buynow1.gif" />
  </form>

Button Images

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

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