SolidTrust Pay Integration Guide - Credit Card API 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 via your own Credit Card interface. This page gives an explanation on how to create a Transparent Credit Card Payment and the parameters that the API system supplies back to your script.

A Quick Start

* NOTE: To use the Transparent Credit Card API System, your STP Account must have Corporate Status.

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

For the credit card payment to work, you must create a script that captures your buyer's credit card and personal details and sends to our CC API handle URL using the CURL POST method. Please note that MD5 Encryption with a given SALT must be used for your STP Merchant's API password entry.

Here is an example:

//build url
$urladdress = "https://solidtrustpay.com/ccapi/process.php"
$transaction_type = "sale";
//optional - if not set will default to 'sale' transaction
$api_pwd = md5($api_pwd.'s+E_a*');
$data = "transaction_type=".$transaction_type."&MerchantName=".$MerchantName."&Merchant_IP=".$Merchant_IP.
"&password=".$api_pwd."&card=".$card."&exp=".$exp."&amount=".$amount."&currency=".$currency.
"&first_name=".$first_name."&last_name=".$last_name."&addr=".$address."&city=".$city."&state=".$state.
"&zip=".$zip."&country=".$country."&cardip=".$cardip."&email=".$email."&cvv=".$cvv."&phone=".$phone.
"&item_id=".$item_id."&memo=".$memo."&udf1=".$udf1."&udf2=".$udf2."&notify_url=".$notify_url.
"&confirm_url=".$confirm_url."&testmode=".$testmode;

//send messages
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,"$urladdress");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); //use this to suppress output
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER,false);// tell cURL to graciously accept an SSL certificate
$result = curl_exec ($ch);
curl_close ($ch);

//results separator is a ":", so here we create an array of vars as per result parameters below

$result = explode(":", $result);

//** here is some code for checking purposes - this will display the results to your screen **

$j = count($result);
for($i = 0; $i < $j ; $i++) {
echo "Result String Part ".$i." = ".$result[$i]."<br>";
}


In the example above, the $result captures the result fields that are returned from the API.

Parameters List

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

 

Parameter Name Required Details
MerchantName YES The receiver of the payment. Your SolidTrust Pay username or email.
password YES Your API password
Merchant_IP YES Your Server's IP where the script request is being made from
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 NO Currency of the transaction. Standard 3-letter ISO currency. If this is not set, it will default to your merchant account currency.
Example : USD
card YES The buyer's card number (16 digits). ONLY VISA and MASTERCARD numbers are accepted.
exp YES

Card expiry date. Set in format "MMYY".eg: 0612

cvv YES

Card CVV number. Last 3 digits on back of card

first_name YES Cardholder's first name. First name
last_name YES Cardholder's last name. Last name
addr YES Cardholder's street address (no PO Box numbers)
city YES Cardholder's city
state YES Cardholder's state. If not available put "NA"
zip YES Cardholder's zip
country YES Cardholder's country
cardip YES Cardholder's IP address. Collect IP from cardholder's requesting computer
email YES Cardholder's email address.
phone YES Cardholder's phone number. Include country code if not USA or Canada
item_id YES Item ID of the product being purchased. ie: your reference
memo YES Cardholder's memo to you. (Have a memo field on your capture form)
testmode NO Add this parameter and set it to "1" 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. NOTE: If you do not send this parameter then the button will be live and real transactions will be made.
Example: 1
udf1 .. udf2 NO You can add 2 custom parameters to the form. These parameters will be sent back in the result to your purchase url unchanged. You can use these parameters to track your site members, for example.
notify_url YES Notify URL where all the result parameters are sent back to, using POST variables.
confirm_url YES Confirm URL - an update url for the Credit Card transaction status - all the result parameters are sent back, using POST variables.
transaction_type YES

Used to set the transaction type. This will default to "sale" if not set.

Options:

sale - normal transaction sale - authorize and capture

authorize - authorize a transaction

capture - on successful authorization, this will complete the transaction - the 3 variables which were returned to you on the authorize will be needed to use this (details below)

void - this will refund any successful transaction back to the credit card account if done within 24 hours of the original transaction - for this you will need to supply the SolidTrustPay Transaction Number

refund - this will refund any successful transaction back to the credit card account if done more than 24 hours from the time of the original transaction - for this you will need to supply the SolidTrustPay Transaction Number

credit - this will process a credit to the credit card account - if this is related to a SolidTrustPay transaction, you will need to supply the SolidTrustPay Transaction Number

transaction_id NO SolidTrustPay Transaction ID received back - tr_id as below - this is required for refund, void, and credit transaction types
gateway_tr_id NO Gateway Transaction ID needed to capture an authorized transaction - using 'capture' transaction type
gateway_req_id NO Required ID needed to capture an authorized transaction - using 'capture' transaction type
gateway_auth_id NO Authorisation ID needed to capture an authorized transaction - using 'capture' transaction type

Result Parameters Sent Back

The result parameters are sent back immediately to your requesting URL via your CURL result. In addition, if you have specified a notify_url, then these parameters will be posted to that address using POST method. 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.

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

* In the case of a Card being enrolled in Visa/Mastercard 3-D Secure please follow the intructions below.

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

Only 3 transaction attempts from the same IP address are permitted per day! - This is the cardholder's IP address - fraud protection and VISA/MC gateway requirements

Only 3 transaction attempts are allowed from the same card per day! You are welcome to use a different card if you require further transactions during this time period - fraud protection and VISA/MC gateway requirements

and other Gateway Error messages as below

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

FAILED - card payment was declined

date Always Date and time of transaction
tr_id Always SolidTrustPay Transaction ID
This needs to be sent back if requesting a 'refund' transaction
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 from the purchaser. This can be empty if the user didn't fill it.
udf1 .. udf2 Always If you have sent any custom parameters in the purchase code they will be sent back unchanged.
currency Always Transaction currency
gateway_tr_id Only on 'authorize' Gateway Transaction ID needed to capture an authorized transaction - using 'capture' transaction type
gateway_req_id Only on 'authorize' Required ID needed to capture an authorized transaction - using 'capture' transaction type
gateway_auth_id Only on 'authorize' Authorisation ID needed to capture an authorized transaction - using 'capture' transaction type

 

3-D Secure

* In the case of a Card being enrolled in Visa/Mastercard 3-D Secure, you will get the following parameters returned to you;

Parameter Name Sent back Details
card_transact_status YES

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

3DSECURE-ENROLLED - card enrolled in 3-D Secure

acs_url YES URL to post the required 3D Secure parameters to
PaReq YES 3D Secure Detail Parameter to post back
MD YES 3D Secure Authenticity Parameter to post back
TermUrl NO Your required URL that the results of the post get sent back to

On receiving a card_transact_status of 3DSECURE-ENROLLED above, you will have to post the parameters to the supplied URL, 'acs_url'

as per example;

<!DOCTYPE html>
<html>
<head>
<title>3D Secure Verification</title>
<script language="Javascript">
function OnLoadEvent() { document.form.submit(); }
</script>
</head>
<body OnLoad="OnLoadEvent();">
Invoking 3-D secure form, please wait ...
<form name="form" action="ACS-URL " method="post">
<input type="hidden" name="PaReq" value="PAREQ ;">
<input type="hidden" name="TermUrl" value="TERM-URL ">
<input type="hidden" name="MD" value="AUTHENTICITY-TOKEN ">
<noscript>
<p>Please click</p><input id="to-asc-button" type="submit">
</noscript>
</form>
</body>
</html>

* You will get the following parameters returned to you;

Parameter Name Sent back Details
PaRes YES 3D Secure Detail Parameter to post back
MD YES 3D Secure Authenticity Parameter to post back

All the above parameters should get posted to the following url:
https://solidtrustpay.com/ccapi/3d_secure.php

You will receive the normal result parameters back as per a normal credit card POST

Here is an example:

$PaRes = $_POST['PaRes'];
$MD = $_POST['MD'];

//build url
$urladdress = "https://solidtrustpay.com/ccapi/3d_secure.php"

$data = "PaRes=".$PaRes."&MD=".$MD;

//send messages
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,"$urladdress");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); //use this to suppress output
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER,false);// tell cURL to graciously accept an SSL certificate
$result = curl_exec ($ch);
curl_close ($ch);

//results separator is a ":", so here we create an array of vars as per result parameters below

$result = explode(":", $result);

Gateway Error Messages

There are two types of errors that a transaction request may encounter, a processing error, or a system/network error. Processing errors are generally transmitted from the card-issuing bank. These types of errors will be available from the API response.  The transaction request may also encounter local network and system errors. If these types of errors are encountered, an error event is triggered within the API. The error message itself will begin with !ERROR!. Therefore, if the API cannot determine the cause of the local or system error, it may just send a !ERROR!. Many of these errors may contain additional information such as a phone number to call to correct the issue or may change in content frequently. To manage errors efficiently, the application logic on the merchant’s system should trigger an event when it receives an !ERROR! and log the subsequent error reason message for manual review and management.