SolidTrust Pay Integration Guide - Payment Button For Single Item Selling via ACH/EFT Payments

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

An Intro - this documentation is for

Use your SolidTrust Pay account to receive direct bank payments. Once your Payment Button is approved, you can accept payments via ACH (in USD from USA customers) and EFT (in CAD from Canadian customers). The integration of the process happens seamlessly. Your customers from the USA or Canada will see the option to pay from a USA Bank or a Canadian Bank.

Remember that your customers can only pay in USD from a USA bank account or in CAD from a Canadian bank account; adjust your prices accordingly.

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 allowable. 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 actual SolidTrust Pay username. You also need to place your button name in the field labelled "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 or CAD only

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 transact in.
Example 1: USD
Example 2: CAD
logo NO The URL of your logo that you wish to appear when your clients make a payment via ACH/EFT.
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 ACH/EFT transaction result status details will be POSTed back. This parameter is sourced from the values you enter when you set up your Payment Button.

return_url NO The URL where the user will be redirected to after they complete the payment. On the last step of the payment there is a button labeled "Return". When the user clicks this button, they are 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/return
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 clients. 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/refund
return_method NO The HTTP method for return. 'GET' or 'POST'. Default is 'POST';
cancel_url NO The URL where the customer will be redirected to if they cancel 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 Not Applicable to ACH/EFT payments - a real transaction has to be made.
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 as an example.

Result Parameters Sent Back

If you have set a notify_url in your Payment Button code when a payment is completed or canceled, result parameters will be sent back to this url using the POST method.

In the case of a DECLINED transaction, you will not get any postback.

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. If the transaction is cancelled, this amount becomes 0.00 so remember this when constructing your hash below.
currency Always USD or CAD
user1 .. user10 Always If you have set any custom parameters to the Payment Button code they will be sent back unchanged. They can be blank.
payerAccount Always Bank.
tr_id Always Unique ID for every transaction. You will see this ID in your transaction history list (in your member's area of SolidTrust Pay).

status

Status will always come back as Pending on the initial accepted completion of the transaction. Once the transaction has been confirmed, you will get a further POST result to your NOTIFY/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 cancelled;



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 in the Merchant Zone area. 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.

MD5([tr_id].":".MD5([sci_pwd]). ":".[amount].":".[merchantAccount].":".[payerAccount])

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.

Additional Parameters Sent Back

Below are all the parameters explained:

Parameter Name Sent Back Details
date Always Date and time of transaction
Name Always Full name of Customer
item_id Always Your item id of the product purchased
addr Always Customer's street address
city Always Customer's city
state Always Customer's state.
zip Always Customer's zip
country Always Customer's country
email Always Customer's email address
phone Always Customer's phone number