SolidTrust Pay Integration Guide - Payment Button For Single Item Selling

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 and the parameters that the IPN system posts back to your server.

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 "Merchant Tools" in the members menu on the left.
  3. Click on "Selling Single Items" in the middle of the loaded page.
  4. Fill in all the fields you need. The required fields for the payment button to work are "Button Name" and "Notify URL".
  5. Submit the form with your information - "Add Button" at the bottom of the page.
  6. The code of your payment button will be generated. Click Return to buttons then the Get Code link next to your button. Your code will be displayed and you can copy and paste to your site.

A Quick Start

All the payments should go to the following url:
https://www.solidtrustpay.com/handle.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.php" method="post">
    <input type=hidden name="merchantAccount" value="your_stp_username" />
    <input type="hidden" name="sci_name" value="your_sci_name">
    
     Amount: <input type=text name="amount" /> <br >
    <input type=hidden name="currency" value="USD" />

    <input type=hidden name="item_id" value="My Best Seller" />
    <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 can use. The item name is "My Best Seller" and its price is entered by your client. The payment will go to your account if you replace your_stp_username above with your SolidTrust Pay username. You also need to place your button name in the field "your_sci_name"

Parameters List

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

Valid Currencies: USD,EUR,GBP,AUD,CAD,NZD

Parameter Name Required Details
merchantAccount YES The receiver of the payment. Your SolidTrust Pay username
sci_name YES The name you gave to your payment button.
item_id YES The item ID or name that you are selling.
Example: My First Book On Sale
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
(this amount can be completed by your client)
currency YES The currency you would like to trade in.
Example 1: USD
Example 2: EUR
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. This parameter is sourced from the values you enter when you set up your payment button and is used when 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 NO

The URL where the updated credit card transaction result status details will be POSTed back. This parameter is sourced from the values you enter when you set up your payment button.
** Please note: refer to confirm url result parameters sent back table below, as this differs from the notify_url result parameters.

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. This parameter is sourced from the values you enter when you set up your payment button.
Example: http://www.yoursite.com
terms_url NO The URL where your terms are displayed. All sites accepting payments are required to show the terms of their offer to their cleints. This ensures your terms are easily displayed. This parameter is sourced from the values you enter when you set up your payment button.
Example: http://www.yoursite.com/terms
refund_url NO The URL where your refund policy is displayed. All sites accepting payments are required to show a refund policy. this URL could quite possibly be the same as your terms_url (above). This parameter is sourced from the values you enter when you set up your payment button.
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. This parameter is sourced from the values you enter when you set up your payment button
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 or email (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 actually the amount transferred to your account when the payment is successful.
fee Always The fee that is charged for the payment.
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 note let from the payer. This can be empty if the user didn't fill it.
payerAccount When Payment Is Successful The SolidTrust Pay username of the payer.
payerEmail When Payment Is Successful The email address 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: In a Credit Card Transaction, 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;
CANCELLED - when the payment is canceled;



Additionally on a successful payment you can receive a security hash, generated using the following formula:

We have implemented a new password to be used with your payment buttons. This can be found in your account under Merchant Zone. 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.

*** Note that if you are using a script from prior to 16 September 2013 you do not have to update it. Simply update your Payment Button Password on our site and add that value to your existing Script for the value "Secondary Password" ***

MD5([tr_id].":".MD5([sci_pwd]). ":".[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:
$sci_pwd = 'put your Payment Button password here';
$sci_pwd = md5($sci_pwd.'s+E_a*');  //encryption for db
$hash_received = MD5($_POST['tr_id'].":".MD5($sci_pwd).":".$_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.

Confirm URL Result Parameters Sent Back (used for Credit Card Merchants)

If you require an updated credit card transaction status (stp_transact_status), as per below, to be sent back to you, then you must use a confirm_url. This will get sent back to this url only once confirmed status is received on the credit card transaction, approved or declined. ie: COMPLETE or FAILED

In the case of a DECLINED transaction, you will get an error message in your 'gateway result' field.

Below are all the parameters explained:

Parameter Name Sent Back Details
card_transact_status Always

The status of the payment request from the CC Gateway. Valid field values are;

ACCEPTED - successful transaction

DECLINED - transaction declined - reason shown in ERROR field

gateway_result

This will display the gateway result.

If card_transact_status is ACCEPTED, then this should show SUCCESSFUL.

If card_transact_status is DECLINED or it is an error, it will be preceded by !ERROR!

* NOTE: in the case an ERROR status resulting in any of the errors listed here, NOT including the Gateway Error Messages below, then further result parameters are suppressed.

Always

Error message description : (always preceded by "!ERROR! ")

IP not on allowed list - you must supply us your server IP address where your purchase script will address our server from before using the API, and we will add it to our allowed IP list.

Server IP does not match posted IP - you have to define your Merchant_IP field above, which must be the same as your requesting server IP.

Incorrect Merchant Password supplied - you have to define your STP password field above, which must be sent MD5-encrypted as explained above.

Your STP account must have Corporate status - please contact our Helpdesk - you have to apply to us for Corporate Status

Application to become Credit Card Merchant not yet done - you have to apply to us for to become a CC Merchant

Your STP account must be set to accept this interface - please contact our Helpdesk - we will set this up for you on your successful application to become a CC Merchant

and other Gateway Error messages as below

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 CONFIRM 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 fraud department)

FAILED - card payment was declined

date Always Date and time of transaction
tr_id Always SolidTrustPay Transaction ID
amount Always The price of the item. This is actually the amount transferred to your account when the payment is successful, less charges.
member Always Full name of Cardholder
item_id Always Your item id of the product purchased
addr Always Cardholder's street address
city Always Cardholder's city
state Always Cardholder's state.
zip Always Cardholder's zip
country Always Cardholder's country
card Always Card number used .
email Always Cardholder's email address
phone Always Cardholder's phone number
memo Always A note let from the purchaser. This can be empty if the user didn't fill it.

udf1 .. udf2

(same as user1 .. user2 above)

Always If you have sent any custom parameters in the purchase code they will be sent back unchanged.

BITCOIN PROCESSING

You can accept Bitcoin payments directly to your SolidTrust Pay account. These will be automatically converted to your STP balance. We do not hold a bitcoin balance.

Processing is very much like a normal STPay transfer:

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).
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 actually the 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 note let from the payer. This can be empty if the user didn't fill it.
payerAccount When Payment Is Successful Bitcoin Payment.
txid When Payment Is Successful The transaction id on the blockchain. You can use this to check the to and from wallets, or check on confirmations.
extra_check When Payment Is Successful Values are Yesor No. If Yes then it means there is something different about the payment- it may be short paid, over paid, or paid late. It will require manual intervention on our side to go from pending to approved.
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: BTC payments are only posted to you when successful.

When payment is successful


COMPLETE - when the payment is successful