SolidTrust SolidTrustPay...ID in your transaction history list. To view, go to M y Account > T...

SolidTrust

SolidTrustPay

API & IPN Integration Manual - Version 1.4

Manual History

Date Authour Version Notes

07/21/17 J. Nickerson 1.1 - API & IPN Integration Manual created.

12/19/17 J. Nickerson 1.2 - New logo inserted.

- Changes to credit card parameters & 3-D secure.

01/23/18 J. Nickerson 1.3 - Updated banners & buttons.

02/06/18 J. Nickerson 1.4 - Final consultation with SME. Changes to testmode and minor content changes.

1


Table of Contents

Introduction . . . 4

Integration Support . . . 4

Popular Shopping Cart Integrations . . . 4

Payment Buttons . . . 5

Button Creation Wizard for Payment Buttons . . . 5

A Quick Start - Payment Buttons . . . 5

Payment Buttons - Table of Parameters . . . 6

Payment Buttons - Table for Result Parameters (Sent Back) . . . 9

Credit Card Merchants . . . 12

Credit Card Merchants - Confirm URL Table of Result Parameters (Sent Back) . . . 12

Bitcoin Processing . . . 15

Bitcoin Processing - Table of Parameters . . . 15

Subscriptions . . . 17

Button Creation Wizard for Subscriptions . . . 17

A Quick Start - Subscriptions . . . 18

Subscriptions - Table of Parameters . . . 19

Subscriptions - Table of Result Parameters (Sent Back) . . . 21

Button Images . . . 27

Banners . . . 29

Pending Transaction Items . . . 31

A Quick Start - Pending Transaction Items . . . 31

Pending Transaction Items - Table of Parameters . . . 32

Pending Transaction Items - Table of Result Parameters (Sent Back) . . . 35

Pending Transaction Items - Confirm URL Result Parameters (Sent Back) . . . 37

Transparent APIs for Instant Payouts . . . 40

A Quick Start - Transparent APIs . . . 40

Transparent APIs - Table of Parameters . . . 43

Transparent APIs - Table of Result Parameters (Sent Back) . . . 45

Credit Card APIs for Single Item Selling . . . 46

A Quick Start - Credit Card API for Single Item Selling . . . 46

Credit Card APIs for Single Item Selling - Table of Parameters . . . 49

Credit Card APIs for Single Item Selling - Table of Result Parameters (Sent Back) . . . 52

2


3-D Secure . . . 55

Gateway Error Messages . . . 55

Create Payment Button API . . . 57

A Quick Start - Create Payment Button API . . . 57

Create Payment Button API - Table of Parameters . . . 57

Create Payment Button API - Table of Result Parameters (Sent Back) . . . 59

Create Payment Button API - Error Messages . . . 59

3


Introduction

Welcome to SolidTrust Pay’s IPN & API Integration Manual! This manual offers an

explanation of how to create payment buttons and the parameters that the IPN

(Instant Payment Notification) system posts back to your server. You can use your

SolidTrust Pay account to receive payments for single and subscription items.

Integration Support

If you are experiencing issues with your integration, please contact

[email protected]. Please allow 1 business day for a reply.

Popular Shopping Cart Integrations

If you wish to integrate a known shopping cart (ZenCart, WooCommerce, etc.),

please visit our Shopping Carts download page:

https://www.solidtrustpay.com/shopping-carts

4


Payment Buttons

Button Creation Wizard for Payment Buttons

If you are not a developer or do not feel comfortable reading this manual, 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. Go to Merchant Zone

2. Click on Merchant Tools

3. Select Create Payment Buttons

4. Fill in all the fields you need. The required fields for the payment button to work

are Create Button Name and Notify URL.

5. Select Add Button at the bottom of the page.

6. The code of your payment button will then be generated. Click Return to

Buttons then the Get Code link next to your button. Your code will be

displayed. You can then copy and paste the code to your site.

A Quick Start for Payment Buttons

The following information is an overview of a basic payment button code. For

the payment button to work, you must create a form using the POST method;

all the parameters you send should use hidden fields.

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

<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" />

5


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

<input type=image name="cartImage"

src="https://solidtrustpay.com/ImgDir/buttons/buynow1.gif" />

</form>

Payment Buttons - Table of Parameters

This table offers a list of all the possible parameters you can use for a payment button.

Included is an explanation of each parameter. The six currencies available for your

payments are:

● US Dollars (USD)

● European Euros (EUR)

● Great British Pounds (GBP)

● Australian Dollars (AUD)

● Canadian Dollars (CAD)

● New Zealand Dollars (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 name or ID of the item you are selling.

● Example 1 - My first book on sale

6


amount

Yes

The price of the item in USD. Do not add any currency

signs ($, €, £), only a number.

● Example 1 - 9.99

● Example 2 - 4

Currency

Optional

(default - USD)

The currency you would like to trade in.

● Example - USD, GBP, EUR, AUD, CAD and NZD.

logo

No

The URL of your logo that you wish to appear when

clients make a payment via credit card.

● Example -

http://www.yoursite.com/yourlogo.gif

notify_url

Yes

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 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.

7


return_url

No

The URL where the user will be redirected to after the

payment has been completed. On the last step of the

payment, there is a button labeled Return, and when

the user clicks this button, they will be 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. If you are

accepting payments, you are required to show terms

to your customers. 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 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 customer will be redirected 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 - Please contact Merchant Support.

user1 .. user10

No

You can add up to 10 (user1, user2, user3...) custom

parameters. These parameters will be sent back to

your notify_url unchanged. You can use these

parameters to track your site members.

8

http://www.yoursite.com/stp_canceled.php


Payment Buttons - Table of 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. This

table offers a list of all the possible parameters you can use for a result parameter.

Included is an explanation of each parameter.

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 of the item you are selling (as

you have set it in your payment button).

amount

Always

The price of the item (as you have set it in your

payment button). This will be the amount that is

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

The notify URL (as you have set it in your payment

button).

return_url

When set in

payment button

code

The return URL (as you have set it in your payment

button).

cancel_url

When set in

payment button

code

The cancel URL (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 left from the payer. This can be empty if the

user didn’t fill it in.

9


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

The unique ID for every transaction. You will see this

ID in your transaction history list. To view, go to My

Account > Transaction History.

status

Always

The status of the payment. There are three available

values:

● COMPLETE - The payment is successful.

● PENDING - The transaction still has to be

cleared.

● CANCELLED - The payment is cancelled.

When a payment is successful, you can receive a security hash which is generated

using the following formula:

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. You can check if the payment is valid via the following PHP:

10


$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

}

11


Credit Card Merchants

Confirm URL Table of Result Parameters (Sent Back)

If you require an updated credit card transaction status (stp_transact_status) to be

sent back to you, then you must use a confirm_url. The status will be sent back to the

selected URL once received (i.e. complete or failed). In the case of a declined

transaction, you will get an error message in your gateway result field. This table offers

a list of all the possible parameters you can use for a result parameter. Included is an

explanation of each parameter.


card_transact_status

Never

The status of the payment request from the credit

card gateway. Valid field values are:

Accepted - Successful transaction.

Declined - Transaction declined. The reason will be

shown in the ERROR field.

Contact Merchant Support if you require credit card

testing.

gateway_result

Always Error message description (always preceded by

!ERROR!)

● IP not on allowed list - You must provide

SolidTrust Pay with your server IP address.

SolidTrust Pay requires where your purchase

script will address our server from before

using the API; we will add it to our allowed IP

list.

● Server IP doesn't 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 SolidTrust Pay

password field, which must be sent

MD5-encrypted as explained above.

12


● Your SolidTrust Pay account must have

corporate status. Please contact support - You have to apply for corporate status.

● Application to become credit card

merchant not yet completed - You have to

apply to SolidTrust Pay to become a credit

card merchant.

● Your SolidTrust Pay account must be set to

accept this interface. Please contact

support - SolidTrust Pay will set this up for

you.

stp_transact_status

Always The status of the payment request in your SolidTrust

Pay account.

Valid field values are:

● PENDING - Transaction still has to be

cleared.

● COMPLETE - Transaction has cleared and

funds will be available in your account.

● FAILED - Transaction was declined.

date Always Date and time of the transaction.

tr_id Always SolidTrust Pay transaction ID (3000...).

amount Always The price of the item. This value is the amount


successful.

member Always The full name of the cardholder.

13


item_id Always The 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 left from the purchaser. This will be empty if

the user does not enter anything.

udfl .. udf2

Always

If you have sent any custom parameters in the

purchase code, they will be sent back unchanged.

14


Bitcoin Processing

Bitcoin Processing - Table of Parameters

You can accept Bitcoin payments directly to your SolidTrust Pay account. Bitcoin

payments will automatically be converted and then credited to your SolidTrust

Pay balance. SolidTrust Pay does not hold a Bitcoin balance. This table offers a

list of all the possible parameters. Included is an explanation of each parameter.


merchantAccount Always The receiver of the payment. Your SolidTrust Pay

username or email (as you have set it in your payment

button).

item_id Never 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 amount


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

Will return 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.

15


memo

When

payment is

successful

A note left from the purchaser. This will be empty if

the user does not enter anything.

payerAccount When

payment is

successful

Bitcoin payment.

txid

When

payment is

successful

The transaction ID on the blockchain. You can use this

ID to check the to and from wallets, or to check on

confirmations.

extra_check

When

payment is

successful

Values are yes or no. If yes, then it means there is

something different about the payment.

tr_id

When

payment is

successful

Unique ID for every transaction. You will see this ID in

your transaction history list. To view the history list, go

to My Account > Transactions History when you

login to SolidTrust Pay.

status

When

payment is

successful

Complete when the payment is successful.

16


Subscriptions

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

You can use your SolidTrust Pay account to receive payments for single and

subscription items. Below is an explanation of how to create payment buttons

for your subscription items.

Button Creation Wizard for Subscriptions

If you are not a developer, or do not feel comfortable reading all of this

documentation, there is a quick way to create your payment button. You will

find a button generator 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 Zone.

3. Proceed to Subscriptions.

4. Click on MERCHANTS - create and/or edit Your MERCHANT SUBSCRIPTIONS.

5. Fill in the details for the subscription. All fields are required, except for Return

Url, Notify Url and Cancel Url.

6. Click on the Add Subscription button. The subscription item will be added. You

will see the addition in the list of your subscriptions.

7. In this newly created list, click 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.

17

https://solidtrustpay.com/handle.php


A Quick Start - Subscriptions

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:


<input type=hidden name="merchantAccount"

value="[your_stp_username]" />

<input type=hidden name="subscription" value="on" />

<input type=hidden name="item_id" value="[SubscriptionID]" />


src="https://solidtrustpay.com/images/buttons/subscribebutton1.gif" />

</form>

The above is the shortest version of a subscription payment button. Do not put any

currency amount details into the form. Currency information is pulled from SolidTrust

Pay’s 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).

18


Subscriptions - Table of Parameters

This table offers a list of all the possible parameters for subscriptions. Included is an

explanation of each parameter.

Parameter Name Required Details

merchantAccount

Yes

The receiver of the payment. Your

SolidTrust Pay username or email.

subscription

Yes

This parameter lets SolidTrust Pay’s

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.

logo

No

The URL of the logo that you wish to

use.

● Example -

http://www.yoursite.com/yourl

ogo.gif

notify_url

No

The URL where the result details will be

posted back. Send this parameter in

case you have an IPN script that can

capture and manage the payment

result.

● Example-

http://www.yoursite.com/stp_c

apture.php

return_url

No

The URL where the user will be

redirected after they complete a

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 the

return URL. You can use this parameter

to return the user to your site.

19


● Example -

http://www.yoursite.com

cancel_url

No

The URL where the user will be

redirected if they cancel the payment,

or if the payment is not successful.

● Example -

http://www.yoursite.com/stp_c

anceled.php

testmode

-

Test code button is within

Subscriptions. Use the test integration

button provided.

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.

20


Subscriptions - Table of 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. Included is an explanation of each parameter.


merchantAccount

Always


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.

21


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 it set in your

payment button code

Cancel URL as you have set it in

your payment button code. Sent

only when the user is first



automatic payments, this parameter

is not sent back.

testmode When set in payment button

code

Returned unchanged as you have

set 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. These parameters are

sent only when the user is



automatic payments, these

parameters are not sent back.

Subscriber

Always

The SolidTrust Pay username of the

subscriber.

subscriber_id

Always

The subscriber ID from SolidTrust

Pay.

tr_id

When payments is successful

Unique ID for every transaction. You

will see this ID in your transaction

history list. To view the history list,

go to My Account > Transactions

History when you log into

SolidTrust Pay.

22


status

Always

The status of the payment. There

are three available values:

● COMPLETE - The payment is

successful.

● CANCELED - The payment is

canceled;

● FAILED - The automatic

monthly payment fails, e.g.

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.

date If payment is created Date and time of when the payment

was created.

unsubscribe_url

Always

The unique URL that your subscriber

can click on to unsubscribe. You can

use this in your correspondence

with your subscriber, or store it in

their account. The unsubscribe link

is also emailed to the subscriber

when they create the subscription.

With a successful payment, you can receive a security hash which is generated using

the following formula:

MD5([tr_id].":".MD5([payment_button_password]).

":".[amount].":".[merchantAccount].":".[payerAccount])

23


In your notify script, you can generate the following hash and check if the payment is

valid/not altered. Here is how to do that using PHP:

$payment_button_password = 'put your payment button password here';

$payment_button_password =

md5($payment_button_password.'s+E_a*'); //encryption for db

$hash_received =

MD5($_POST['tr_id'].":".MD5($payment_button_password).":".$_POST['amount']."



// valid payment

}

else {


}

24


Below is a simple form of a subscription button, which includes the required fields:








</form>

Form with custom fields, logo, notify and return URLs:






<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]" />



</form>

Payment button in test mode:


<input type=hidden name="testmode" value="on" />


25













</form>

26


Button Images

In the table below, you will find professional-looking button images and banners,

along with their location (the image URL). If you prefer to use your own button or

banner image, put your image URL in the src attribute of the script field.

Image Image URL

https://solidtrustpay.com/assets/button1.png






27






https://www.solidtrustpay.com/assets/logos/c

ur_stp.png

https://solidtrustpay.com/assets/logos/stsecur

elogo.jpg

28


Banners

URL- https://solidtrustpay.com/assets/banner1.png

URL - https://www.solidtrustpay.com/assets/banner2.png

URL - https://solidtrustpay.com/assets/banner3.png

29


URL - https://solidtrustpay.co/assets/banner4.png

30


Pending Transaction Items

You can use your SolidTrust Pay account to receive payments for single items. These

payments are set to PENDING, and are of particular use to exchangers since all

payments are reviewed prior to approval. This IPN is recommended if you expect to

receive high volumes of payments, which otherwise 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 event of a

server lag or delay, the payment is attempted every 5 seconds until it is completed.

A Quick Start for Pending Transaction Items

Payments should go to: 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">


value="your_stp_username" />

<input type=hidden name="amount" value="899.99" />



<input type=hidden name="confirm_url"

value="http://www.yoursite.com/stpconfirm.php" />



</form>

31


Pending Transaction Items - Table of Parameters

The six currencies available for your payments are:

● US Dollars (USD)

● European Euros (EUR)

● Great British Pounds (GBP)

● Australian Dollars (AUD)

● Canadian Dollars (CAD)

● New Zealand Dollars (NZD)

Below, you will see an explanation of all the parameters that can be used for payment

buttons.


merchantAccount

Yes


SolidTrust Pay username.

item_id

Yes

The item ID or name of the item 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

32


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 script that can capture

and manage the payment result.

● Example -

http://www.yoursite.com/stp_capt

ure.php

confirm_url

Yes

The URL where the updated transaction

result status details will be POSTed back.

● Example -

http://www.yoursite.com/stp_con

firm.php

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, and when the user

clicks this button, they are 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.

33


cancel_url

No

The URL where the user will be redirected

to if they cancel the payment or if the

payment is not successful.

● Example -

http://www.yoursite.com/stp_can

celed.php

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.

34


Pending Transaction Items - Table of 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.


merchantAccount

Always


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


This is 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


cancel_url When set in payment button

code

Cancel URL (as you have set it in


testmode


code

Returned unchanged (as you have


user1 .. user10


code

If you have set any custom

parameters to the payment button

code, they will be sent back

unchanged.

35


memo

Always

A comment from the payer. This

will 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. To view

the history list, go to My Account

> Transactions History when you

log into SolidTrust Pay.

status

Always

The status of the payment. There

are three available values:

● COMPLETE - The payment

is successful.

● PENDING - The transaction

still has to be cleared.

● CANCELLED - The

payment is cancelled.

When a payment is successful, you will receive a security hash which is generated

using the following formula:

MD5([tr_id].":".MD5([payment_button_password]).

":".[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:

$payment_button_password = 'put your secondary password here';

$payment_button_password =

md5($payment_button_password.'s+E_a*'); //encryption for db

36


$hash_received =

MD5($_POST['tr_id'].":".MD5($payment_button_password).":".$_POST['amount']."



// valid payment

}

else {


}

Pending Transaction Items - Confirm URL Result

Parameters Sent Back

The confirm_url is required for this IPN. Below are all of the parameters explained.


stp_transact_status

Always

The status of the payment request in your SolidTrust Pay

account. Valid field values are:


cleared.

● COMPLETE - The transaction has cleared and

funds should be available in your account.

date Always Date and time of transaction.

tr_id Always SolidTrust Pay transaction ID.

amount

Always

The price of the item. This is the amount transferred to

your account when the payment is successful.

37


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 will be empty if the

user did not include comments.

Here is the most simple form, including only the required fields:








value="http://www.yoursite.com/stp_confirm.php" />



</form>

Form with custom fields, notify and return URL:










value="http://www.yoursite.com/stp_confirm.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

38


member ID here to recognize him/her when the payment is completed]" />



</form>

39


Transparent APIs for Instant Payouts

You can use your SolidTrust Pay account to make payments to other members directly

from your website without having to login. This page gives an explanation of how to

create an instant transparent payment and the parameters that the API system will

post back to your server.

A Quick Start for Transparent APIs

The table below explains the API fields.

Field Required? Details

API name Yes You can choose this.

API password Yes You can choose this.

Set enabled status Yes Select either yes or no.

Daily payout volume limit Yes You can limit the total volume

your account can payout daily.

Notify URL

Yes

The URL where payment details

are POSTED back so that your

script can update your site.

Server IP(s) Yes Payments will only be

accepted from this IP.

You may edit your API as often as you want. For example, set the API to Set Enabled

Status > No when you are not making any payments. All payments must go to the

following URL: https://solidtrustpay.com/accapi/process.php

40


Your script will capture the details of the username, amount and any memos. The

following example uses two files on your site to make the payment:

1. prepare_stp_pay.php

2. makepayment.php

The following is how to create prepare_stp_pay.php:

<form method="post" action="yoursite/makepayment.php"> Pay To<input type=text

name="user" />

<input type = hidden name = testmode value = 0>

Amount<input type=text name="amount" />

Currency<input type=text name="currency" value="USD" />

Memo<input type=text name="item_id" />


src="https://solidtrustpay.com/images/buttons/buynow1.gif">

<input type=hidden name="udf1" value="Any note that you will receive back as a result

parameter" />

<input type=hidden name="udf2" value="[You can put your site member ID here to recognize

him/her when the payment is completed]" />

<input type="submit" name="submit" value="Send">

</form>

The following is what yoursite/makepayment.php looks like:

<?

foreach($_POST as $k=>$v) $$k=urldecode($v);

$urladdress = "https://solidtrustpay.com/accapi/test.php";

$api_id = "Your API name";

$api_pwd = "Your API password";

$api_pwd = md5($api_pwd.'s+E_a*');

$data = "user=".$user. "&testmode=".$testmode."&api_id=".$api_id.

"&api_pwd=".$api_pwd.

"&amount=".$amount."&paycurrency=".$currency."&comments=".$comments."&fee=".$fee."

&udf1=".$udf1."&udf2=".$udf2;

// Call STP API

$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);

41


curl_setopt($ch, CURLOPT_HEADER, 0); //use this to suppress output

//curl_setopt($ch, CURLOPT_SSL_VERIFYPEER,false);// tell cURL to graciously accept an

SSL certificate

$result = curl_exec ($ch) or die(curl_error($ch));

echo $result;

echo curl_error($ch);

curl_close ($ch);

?> Next Payment click <a href = "prepare_stp_pay.php"> HERE</a>

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

API. You will see the transaction status and the transaction ID. If successful, the

variables detailed below will be POSTed to the notify URL contained in your API. This

POST allows your site to update the details.

42


Transparent APIs - Table of Parameters

From the table below, you will see an explanation of all the parameters that can be

used for payment buttons.


api_id Yes The name you created for your API.

api_pwd

Yes

The password for your API. For additional password

security, use a site such as

http://www.md5hashgenerator.com to create an

md5 password hash.

● For example, If your password is

mypassword, you would hash

mypasswords+E_a* and enter the returned

hash as the variable value. Doing the above

prevents the password from being stored in

plain text on your server.

user Yes The SolidTrust Pay username of your payee.

amount

Yes

The amount you are paying. Do not add any currency

signs. Use only a number value.

● Example 1 - 9.99

● Example 2 - 4

43


currency

Yes

The currency of the transaction.

item_id

Yes

The item ID. Can also be the service or product name.

● Example - My First Book On Sale

udf1 .. udf2

No

You may add up to 2 (udf1, udf2) custom parameters.

These parameters are sent back to your notify_url

unchanged.

● For example, you can use these parameters to

track your members.

44


Transparent APIs - Table of Result Parameters (Sent Back)

When a payment is successful, the result parameters are sent to your notify_url as

specified in your API. Below are all the parameters explained.


status

Always

The status of the payment, which has one value:

● ACCEPTED - The payment was successful.


tr_id

When

payment is

successful.

Unique ID for every transaction. You will see this ID in the

details link and in your transaction history (My Account >

Transactions History).

amount

Always

The price of the item in your choice of currency (as you

have set it in your payment button). This is the amount

that is transferred to your account when the payment is

successful.

member

Always

The SolidTrust Pay username of the person who you sent

funds to.

item_id Always The item ID, service or product name of what you are

selling (as you have set in your POST variables).

email Always The email address of the payer.

udf1 .. udf2

When set

If you have any custom parameters to the POST code,

they will be sent back unchanged.

45


Credit Card APIs for Single Item Selling

You can use your SolidTrust Pay account to receive payments via your credit card

interface. The following gives an explanation on how to create a transparent credit card

payment and the parameters that the API system sends back to your script.

A Quick Start - Credit Card APIs for Single Item Selling

All payments 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, which then sends to our credit card API handle

URL using the CURL POST method.

//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 =

"&notify_url=".$notify_url."&currency=".$currency."&testmode=".$testmode."&MerchantNam

e=".$MerchantName."&Merchant_IP=".$Merchant_IP."&password=".$password."&card=".$ca

rd."&exp=".$exp."&amount=".$amount."&first_name=".$first_name."&last_name=".$last_na

me."&address=".$address."&city=".$city."&state=".$state."&zip=".$zip."&country=".$country."

&cardip=".$cardip."&email=".$email."&cvv=".$cvv."&phone=".$phone."&item_id=".$item_id."

&memo=".$memo."&user1=".$user1."&user2=".$user2."&user3=".$user3."&user4=".$user4."&

user5=".$user5."&user6=".$user6."&user7=".$user7."&user8=".$user8."&user9=".$user9."&us

er10=".$user10."&return_url=".$return_url."&transaction_type=".$transaction_type;

> //send messages

46


$ch = curl_init();

curl_setopt($ch, CURLOPT_URL,"$urladdress");



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

The parameters are delivered as follows:

$status = $result[0];

$gateway_result = $result[1];

$stp_transact_status = $result[2];

$transaction_status = $result[3];

$today = $result[4];

$tr_id = $result[5];

$amount = $result[6];

$member = $result[7]

$item_id = $result[8];

$addr = $result[9];

$city = $result[10];

$state = $result[11];

$zip = $result[12];

$country = $result[13];

$email = $result[14];

47


$phone = $result[15];

$memo = $result[16];

$user1 = $result[17];










$currency = $result[27];

$paid_by = $result[28];

$hash = $result[29];

$merchantAccount = $result[30];

The following code is 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.

48


Credit Card APIs for Single Item Selling - Table of

Parameters

In the table below, you can see an explanation of all the parameters that can be used

for payments.


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. Please use standard 3-letter

ISO currency (see example below). If this is not set, it

will default to your merchant account currency.

● Example - USD

card

Yes

The buyer's card number (16 digits).

exp

Yes

Card expiry date. Set in format MMYY.

● Example - June 2017 would appear as 0617.

cvv Yes Card CVV number. 3 digits that are on the back of a card.

49


first_name Yes Cardholder’s first name.

last_name Yes Cardholder’s last name.

addr

Yes

Cardholder’s street address.

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. Collects IP from cardholder’s

requesting computer.

email Yes Cardholder’s email address.

phone

Yes

Cardholder’s phone number. Includes country code if

not in the US or Canada.

item_id Yes Item ID of the product being purchased.

memo Yes Cardholder’s note to you.


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.

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 of the result parameters are sent

back using POST variables.

50


transaction_id No SolidTrust Pay transaction ID received back. This is

required for refunds, voids and credit transaction types.

gateway_tr_id

No

Gateway transaction ID that is needed to capture an

authorized transaction, which uses capture transaction

type.

gateway_req_id

No

Required ID that is needed to capture an authorized

transaction, which uses capture transaction type.

gateway_auth_id

No

Authorisation ID that is needed to capture an authorized


transaction_type

Yes

Used to set the transaction type. This will default to sale

if not set.

Options are as follows:

● sale = Normal transaction.

● sale = Authorize and capture.

● authorize = Authorize a transaction.

● capture = On successful authorization, this will

complete the transaction. The three 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 to

happen, you will need to supply the SolidTrust

Pay transaction number (3000…).

● 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 to happen, you will

need to supply the SolidTrust Pay transaction

number (3000…).

51


● credit = This will process a credit to the credit

card account. If this is related to a SolidTrust Pay

transaction, you will need to supply the

SolidTrust Pay transaction number (3000…).

Credit Card APIs for Single Item Selling - Table of 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) 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. Below are all the parameters explained.


card_transact_status

Always

The status of the payment request from the credit card

gateway.


● ACCEPTED - The transaction was successful.

● DECLINED - The transaction was declined. The

reason will be shown in ERROR field.

Error message description below:

● IP not on allowed list - You must give

SolidTrust Pay your server IP address. The

address must be where your purchase script will

address our server from, before using the API.

SolidTrust Pay support will add the IP to the

allowed IP list.

● Server IP does not match posted IP - You must

define your Merchant_IP field, which must be the

52


gateway_result

Always

same as your requesting server IP.

● Incorrect merchant password supplied - You

must define your SolidTrust Pay password field

above, which must be sent as MD5-encrypted.

● Your SolidTrust Pay account must have

corporate status. Please contact support - You

must apply for corporate status

● Application to become credit card merchant

not yet done - You must apply to SolidTrust Pay

to become a credit card merchant.

● Your SolidTrust Pay account must be set to

accept this interface. Please contact support - SolidTrust Pay will set this up for you on your

successful application to become a credit card

merchant.

● Only three transaction attempts from the

same IP address are permitted per day - This is

the cardholder's IP address. Fraud protection

and set by Visa/MasterCard (gateway

requirements). Allow 24 hours before attempting

again.

● 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 as set by Visa/MasterCard (gateway

requirements). Allow 24 hours before attempting

again.

53


stp_transact_status

Always

The status of the payment request in your SolidTrust Pay

account.



cleared.

● COMPLETE - The transaction cleared and funds

should be available in your account. This status

is only sent to notify URL once transaction is

cleared by our fraud department.

● FAILED - The card payment was declined.


tr_id

Always

SolidTrust Pay transaction ID. The transaction ID needs

to be sent back if requesting a refund transaction.

amount

Always

The price of the item. This is the amount transferred to

your account when the payment is successful.

member Always Full name of cardholder.

item_id Always The 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.

54


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 will be empty if the user

does not enter anything.

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

Required ID needed to capture an authorized


gateway_auth_id Only on

authorize

Authorisation ID needed to capture an authorized

transaction, which uses 'capture' transaction.

3-D Secure

In the case of a card being enrolled in Visa/Mastercard 3-D Secure, we will handle the

redirection. All you need to do is pick up the end results as above.

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 via 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 send !ERROR! Many of these errors may contain additional information, such as

a phone number to call to correct the issue. Errors may change in content frequently.

To manage errors efficiently, the application logic on the merchant’s system should

55


trigger an event when it receives an !ERROR!, and will log the subsequent error reason

message for manual review and management.

56


Create Payment Button API

Members wanting to accept payments on their site are required to create a payment

button within their SolidTrust Pay account. This API is used by script developers who

wish to automate the process of adding the payment button for clients. As the details

of the button are required in most scripts to automate payments, the data can be sent

to the SolidTrust Pay site to create the button instantly for a client.

A Quick Start - Create Payment Button API A data string should be constructed and sent to:

https://www.solidtrustpay.com/accapi/createsci

Create Payment Button API - Parameters List

In the table below, you will find an explanation of all the parameters that can be used

for payment button creation.

Parameter Sent Required Details

user

Yes

The SolidTrust Pay username of the account that is

requesting a button.

sci_name

Yes

The name of the payment button. This is how it will be

identified.

sci_password

Yes

The password that is used to validate payments on

return to the merchant’s website. This is set in the

merchant’s SolidTrust Pay account (Merchant Zone >

Create Payment Button Password).

notify_url

Yes

The URL where the result details will be POSTed back.

57


● Example -

http://www.yoursite.com/stp_capture.php

confirm_url

Yes

The URL where the updated transaction result status

details will be POSTed back.

● Example -

http://www.yoursite.com/stp_confirm.php

cancel_url

Yes

The URL the payer is directed to if the payment is

cancelled.

● Example -

http://www.yoursite.com/stp_confirm.php

return_url

Yes

The URL where the payer will be redirected to after

they complete the payment. On the last step of the

payment, there is a button labeled Return. When the

payer clicks this button, they will be redirected to the

inserted URL. Use this parameter to redirect the payer

back to the merchant’s site.

● Example - http://www.yoursite.com/return_url

terms_url

No

The URL containing the merchant website’s Terms and

Conditions.

● Example - http://www.yoursite.com/terms.php

refund_url

No

The URL showing the merchant website’s Refund

Policy. This can be the same as the terms_url.

● Example -

http://www.yoursite.com/refund_policy.php

ref

No

The SolidTrust Pay username of the developer. If your

client has no referrer, and there is a valid username in

this parameter, that username will be set as your

client’s referrer.

58


Create Payment Button API - Table of Result Parameters

(Sent Back)

Results are provided in JSON by default. Should you wish to receive XML, send your

data string to: https://www.solidtrustpay.com/accapi/createsci?type=xml

Parameter Name Details

status Either OK or fail.

message If OK, the message is success.

Create Payment Button API - Error Messages If the status is FAIL, one of the following errors will be noted in the message values.

Message Reason

There is already a button created Users are only allowed one button per site.

No account by that name

No account for the given username has been

created or exists.

No notify URL No notify URL provided.

No return URL No return URL provided.

No cancel URL No cancel URL provided.

59

https://www.solidtrustpay.com/accapi/createsci?type=xml


No confirm URL No confirm URL provided.

No password entered No payment button password provided.

No button name entered No button name provided.

Cannot set up in suspended account User is suspended.

Account must be standard verified to create

button

User is not verified.

A simple example of the API is below in PHP. This sample will return XML, rather than

JSON:

<? $urladdress = "https://solidtrustpay.com/accapi/createsci?type=xml";

if (isset($_POST['submit']))

{

foreach($_POST as $k=>$v) $$k=urldecode($v);

$data = "user=".$user. "&sci_name=".$sci_name."¬ify_url=".$notify_url.

"&return_url=".$return_url. "&cancel_url=".$cancel_url."&confirm_url=".$confirm_url.

"&terms_url=".$terms_url."&refund_url=".$refund_url."&ref=".$ref."&sci_password=".$sci_pa

ssword;

// Call STP API

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL,"$urladdress");



curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

curl_setopt($ch, CURLOPT_HEADER, 0); //use this to suppress output

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER,false);// tell cURL to graciously accept an SSL

certificate

$result = curl_exec ($ch) or die(curl_error($ch));

if(curl_exec($ch) === false)

{

$result = curl_error($ch);

}

else

{

curl_close ($ch);

//if json required

//$data = json_decode($result, true);

60


//$result = $data[status];

//$message = $data[message];

//if xml required - with some error handling

libxml_use_internal_errors(true);

$data = simplexml_load_string($result);

if ($data === false) {

echo "Failed loading XML: ";

foreach(libxml_get_errors() as $error) {

echo "

", $error->message;

}

} else {

$result = $data->status;

$message = $data->message;

}

}

if ($result == 'OK'){

//do your thing - save data etc

}

else{

//present a message to the client to tell them what went wrong

}

} else{

?>

<form method="post">

Client SCI Name <input type = text name = "sci_name" /><br>

Client SCI Password<input type = text name = "sci_password" /><br>

Client SolidTrust Pay username<input type = text name = "user" /><br>

<input type=hidden name = "notify_url" value = "https://yoursite.com/notify_url" />

<input type=hidden name = "cancel_url" value = "https://yoursite.com/cancel_url">

<input type=hidden name = "return_url" value = "https://yoursite.com/return_url" />

<input type=hidden name = "confirm_url" value ="https://yoursite.com/confirm_url" />

<input type=hidden name = "terms_url" value = "https://yoursite.com/terms_url" />

<input type=hidden name = "refund_url" value = "https://yoursite.com/refund_url" />

<input type=hidden name = "ref" value = “developer’s SolidTrust Pay username" />

<input type="submit" name = "submit" value = "Send">

</form>

SolidTrust Pay 2018 - End of manual

61

Date post:	13-Mar-2020
Category:	Documents
Upload:	others
View:	1 times
Download:	0 times

SolidTrust SolidTrustPay...ID in your transaction history list. To view, go to M y Account > T...

Documents