Hosted Payment Advanced Integration Manual

Hosted Payments Introduction

Hosted Payments allows web site developers to provide their customers with a secure and convenient way to submit payments or purchase products. This document describes the functionality that's included with Hosted Payments and how to link that functionality into your website.

To start using Hosted Payments, all you need is an account with PayJunction and a web page. Your web page does not need any scripting capability such as PHP, ASP or Python although you can certainly merge such dynamic scripting with this solution.

How does the Hosted Payments work?

Hosted Payments works by directing your customer to our secure checkout. Simply embed some HTML on your web pages to enable this functionality.

There are two different techniques that can be used...

One technique is to sprinkle your website with payment buttons (i.e. HTML) that allows your customers to add individual items to their cart. Once they’re done picking out items, they can click on a checkout button (i.e. HTML) to pay for the items they’ve chosen.

The second technique immediately sends your customers to your shop’s checkout screen with an amount to charge them already specified. This essentially collapses all the different steps of the first technique into one click. Instead of adding an item and then clicking to checkout at a later point, the customer adds an item and checks out immediately. This second technique is useful for sites that have their own shopping carts or that only have a single item to offer (like a payment or donation).

Demo account for development and testing

PayJunction provides a demo/sandbox account. You can track test transactions by logging into http://www.PayJunctionLabs.com.

  Username Password

Sandbox (Demo Virtual Terminal) access via http://www.PayJunctionLabs.com

payjunctiondemo demo123

Submitting Test Transactions

Transactions that are submitted via the test URL while using the test Store ID will be sent to the PayJunction sandbox (Demo Virtual Terminal) which can be accessed via http://www.PayJunctionLabs.com (see above section)

Post URL for testing purposes:

https://www.payjunctionLABS.com/trinity/quickshop/add_to_cart.action

Store ID for testing purposes:

pj-qs-01

Example HTML for Test Button:

 <form action="https://www.payjunctionlabs.com/trinity/quickshop/add_to_cart.action" method="POST">
  <input type="hidden" name="store" value="pj-qs-01">
  <input type="hidden" name="need_to_ship" value="yes">
  <input type="hidden" name="need_to_tax" value="yes">
  <input type="hidden" name="quantity" value="1">
  <input type="hidden" name="identifier" value="Online Order">
  <input type="hidden" name="description" value="A very nice widget.">
  <input type="hidden" name="price" value="50.00">
  <input type="submit" value="Add to Cart">
</form>

Test card information

Transactions ran on the sandbox account go through a test processor, so there is no need to void or otherwise cancel transactions.

However, to avoid using a live card, please use the following test card processing data:

Test Credit Card Numbers:

 
Visa:
4444 3333 2222 1111
4111 1111 1111 1111
4242 4242 4242 4242
Mastercard:
5105 1051 0510 5100
5555 5555 5555 4444
2223 0000 4840 0011
Amex:
3714 496353 98431
3434 343434 34343
3782 822463 10005
Discover:
6011 1111 1111 1117
6011 0004 0000 0000
6011 0009 9013 9424
Diner Club:
3614 890064 7913
3670 010200 0000
3056 930902 5904
JCB:
3566 1111 1111 1113
3528 0007 0000 0000
3530 1113 3330 0000

Test Expiration Date:
Any Expiration Month and Year in the Future. For example:

01/25

Test Address:

1903 Test St 

Test Zip Code:

93101

Test CVV:

999

Test Amount:

$2.00 or more

Transactions ran for an amount between $0.00 and $1.99 will result in a decline.

Submitting Live Transactions

Transactions that are submitted via the live URL will be sent to your Live PayJunction account which can be accessed via http://www.PayJunction.com

Post URL for testing purposes:

https://www.payjunction.com/trinity/quickshop/add_to_cart.action

Store ID (i.e. Shop):

  1. Go to More, then select Hosted Payments.
    More_HostedPayments.png
  2. Copy the Shop Name (i.e. Store ID) that you would like to use.
  3. If you do not have any existing Shops, or you would like to create a new one, click New Shop on the top-right of the screen.
    newShop.png

Example HTML for Live Button:

 <form action="https://www.payjunction.com/trinity/quickshop/add_to_cart.action" method="POST">
  <input type="hidden" name="store" value="YOUR-STORE-ID">
  <input type="hidden" name="need_to_ship" value="yes">
  <input type="hidden" name="need_to_tax" value="yes">
  <input type="hidden" name="quantity" value="1">
  <input type="hidden" name="identifier" value="Online Order">
  <input type="hidden" name="description" value="A very nice widget.">
  <input type="hidden" name="price" value="50.00">
  <input type="submit" value="Add to Cart">
</form>

How do customers add products to the cart?

You need to include an HTML button on your web page.

Here is a full HTML example; this example will add one Widget that costs $50.00 to the customer's shopping cart:

<form action="https://www.payjunctionlabs.com/trinity/quickshop/add_to_cart.action" method="POST">
  <input type="hidden" name="store" value="pj-qs-01">
  <input type="hidden" name="need_to_ship" value="yes">
  <input type="hidden" name="need_to_tax" value="yes">
  <input type="hidden" name="quantity" value="1">
  <input type="hidden" name="identifier" value="Online Order">
  <input type="hidden" name="description" value="A very nice widget.">
  <input type="hidden" name="price" value="50.00">
  <input type="submit" value="Add to Cart">
</form>

Notice that there's several fields that describe the product, supply the price, give the quantity to add, etc.

The above HTML will result in an Add To Cart button that will look like this:

paymentButtonExample.png

When the button is clicked, the item will be added to the Cart:

payjunctionCart.png

At this point, the customer can click Checkout to pay, or they can return to your website to continue shopping. If the customer is ready to pay, PayJunction will also handle the collection of payment.

How can customer's see the items in their shopping cart?

Simply create a View Cart HTML button on your web page that points to PayJunction’s secure shopping cart site.

The URL to show the shopping cart screen is:

https://www.payjunction.com/trinity/quickshop/view_cart_init.action

The only requirement for these pages is that you supply the Store ID.

HTML form example for the view-shopping-cart page:

<form method="POST"action="https://www.payjunction.com/trinity/quickshop/view_cart_init.action">
   <input type="hidden" name="store" value="YOUR-STORE-ID">
   <input type="submit" name="" value="Show Shopping Cart">
</form>

HTML link example:

<a href="https://www.payjunction.com/trinity/quickshop/view_cart_init.action?store=YOUR-STORE-ID">Show Shopping Cart</a>

How can customers get to the check-out screen?

Simply create a Checkout HTML button on your web page that points to PayJunction’s secure shopping cart site.

The URL to show the checkout screen is:

https://www.payjunction.com/trinity/quickshop/check_out_init.action

The only requirement for these pages is that you supply the Store ID.

HTML form example for the checkout page:

<form method="POST"action="https://www.payjunction.com/trinity/quickshop/check_out_init.action">
   <input type="hidden" name="store" value="YOUR-STORE-ID">
   <input type="submit" name="" value="Checkout">
</form>

HTML link example:

<a href="https://www.payjunction.com/trinity/quickshop/check_out_init.action?store=YOUR-STORE-ID">Checkout</a>

How to checkout immediately with an amount included

If you only have a single product to offer or already have an aggregate amount ready, you may want to let the customer check out without having to add a product to their shopping cart separately. To do this, you need to create a Snap Checkout HTML button.

URL for Snap Checkout:

https://www.payjunction.com/trinity/quickshop/add_to_cart_snap.action

Here is a HTML example:

<form action="https://www.payjunctionlabs.com/trinity/quickshop/add_to_cart_snap.action" method="POST">
  <input type="hidden" name="store" value="pj-qs-01">
  <input type="hidden" name="need_to_ship" value="yes">
  <input type="hidden" name="need_to_tax" value="yes">
  <input type="hidden" name="quantity" value="1">
  <input type="hidden" name="identifier" value="Online Payment">
  <input type="hidden" name="description" value="Balance Owed">
  <input type="hidden" name="price" value="50.00">
  <!—See below for additional fields you can include here --> 
  <input type="submit" value="Submit Payment">
</form>

Supported Fields for Hosted Payments

Below is a table with a full description of each of fields, what their purpose is, whether they are mandatory or not, and what format is appropriate for their values.

If you do not want to craft your buttons by hand or need help, there is an interactive button generator is available for you to use. Access the button generator by logging into PayJunction. Click on More, then Hosted Payments. Then select "Generate Hosted Payment" on the top-right of the screen. 

 Parameter Mandatory Format Description

identifier

No

Alpha-Numeric

Short product description such as an SKU.

description

Yes

Alpha-Numeric

Brief description of the product or service being purchased.

quantity

Yes

Integer

Quantity of product to store in the cart

need_to_ship

Yes

"Yes" or "No"

Price of the product or service

s_h_amount

No

Numeric

Alternative method of tacking on shipping costs to the product. If this field is defined, it overrides the shipping calculator and adds the value give to the order’s final shipping cost.

need_to_tax

Yes

"Yes" or "No"

Indicator of whether the product needs to be taxed. If it does need to be taxed, then the check-out screen will determine how much to tax by using the shop’s tax calculator.

tax_amount

No

Numeric

Alternative method of tacking on a tax amount to the purchase. If this field is defined, it overrides the tax calculator and adds the value given to the order’s final tax amount.

store

Yes

Your PayJunction account Login.

This is your store identifier, which is the Login for your PayJunction /Hosted Payment account

How can I send customer information to the checkout form?

If you have additional information that you would like to pass to the checkout page, you can forward the information on using the following parameters.

Example HTML button sending customer name to the checkout page

<form action="https://www.payjunctionlabs.com/trinity/quickshop/add_to_cart.action" method="POST">
  <input type="hidden" name="store" value="pj-qs-01">
  <input type="hidden" name="need_to_ship" value="yes">
  <input type="hidden" name="need_to_tax" value="yes">
  <input type="hidden" name="quantity" value="1">
  <input type="hidden" name="identifier" value="Online Payment">
  <input type="hidden" name="description" value="Balance Owed">
  <input type="hidden" name="price" value="50.00">
  <!—Customer First Name --> 
  <input type="hidden" name="billingFirstName" value="John">
  <!—Customer Last Name --> 
  <input type="hidden" name="billingLastName" value="Doe">
  <input type="submit" value="Submit Payment">
</form>
Parameter Format Description

billingFirstName

Alpha-Numeric

First Name of the person.

billingMiddleName

Alpha-Numeric

Middle Name of the person.

billingLastName

Alpha-Numeric

Last Name of the person.

billingPhone

5 or 9 digit number.

The daytime phone contact for the customer.

billingFax

5 or 9 digit number.

The fax number for the customer.

billingEmail

Alpha-Numeric

Contact e-mail for the customer making the purchase. This is the e-mail that the customer’s receipt is mailed to.

billingCustomerId

Alpha-Numeric

Customer ID for the person that placed the order.

billingCompany

Alpha-Numeric

Name of the Company that placed the order

billingDepartment

Alpha-Numeric

Name of the Department that placed the order

billingOccupation

Alpha-Numeric

Occupation of the person that placed the order

billingTitle

Alpha-Numeric

Name Title (Mr., Mrs., etc.)

notes

Text

Space for any extra notes relevant to the order.

If your merchant account is set up to perform address verification (AVS), which is recommended, then the card holder’s billing address needs to be supplied as well. This is the address that the card holder’s billing statement is mailed to. To include the billing address, supply the following fields. 

Parameter Format Description

billingStreetAddress

Alpha-Numeric

The street that the billing address is mailed to.

billingCity

Alpha-Numeric

The city that the billing address is mailed to.

billingTerritory

Two letter state abbreviation.

The state for the credit card’s billing address.

billingZip

5 or 9 digit number.

Five or nine digit zip code.

billingCountry

"United States" or "Other"

The county the credit card was issued from.

If the order requires shipping, then shipping address information can also be supplied.

Parameter Format Description

shippingFirstName

Alpha-Numeric

First Name of the person to ship to.

shippingMiddleName

Alpha-Numeric

Middle Name of the person to ship to.

shippingLastName

Alpha-Numeric

Last Name of the person to ship to.

shippingStreetAddress

Alpha-Numeric

The street the order is to be shipped to.

shippingCity

Alpha-Numeric

The city the order is to be shipped to.

shippingTerritory

Two letter state abbreviation.

The state the order is to be shipped to.

shippingCountry

Alpha-Numeric

The country the order is to be shipped to.

shippingZip

5 or 9 digit number.

The zip that the order is to be shipped to.

You can also supply the customer’s contact information and a notes field for special order requirements.

Parameter Format 

Description

shippingCustomerId

Alpha-Numeric

Customer ID for the person that placed the order.

shippingCompany

 

Alpha-Numeric

Name of the Company that placed the order

shippingDepartment

Alpha-Numeric

 

Name of the Department that placed the order

shippingOccupation

 

Alpha-Numeric

Occupation of the person that placed the order

shippingTitle

 

Alpha-Numeric

Name Title (Mr., Mrs., etc.)

shippingEmail

A valid e-mail address.

Contact e-mail for the customer making the purchase. This is the e-mail that the customer’s receipt is mailed to.

shippingPhone

A 10-digit phone number, by itself or with dashes and parentheses.

The daytime phone contact for the customer.

shippingFax

A 10-digit fax number, by itself or with dashes and parentheses.

 

The fax number for the customer.

notes

Text

Space for any extra notes relevant to the order.

How can I have the payment button direct my customers to my custom receipt page on my server?

If you want the customer to be redirected to your checkout page after the order has been processed and approved, you will need to supply a relay field.

Parameter Format Description

relay

Alpha-Numeric

The server and script you want to redirect to after an order has been processed.

 Here is a HTML example for sending information to your custom receipt page:

<form method="POST" action="https://www.payjunctionlabs.com/trinity/quickshop/add_to_cart_snap.action"> 
  <input type="hidden" name="store" value="pj-qs-01">
  <input type="hidden" name="need_to_ship" value="yes">
  <input type="hidden" name="need_to_tax" value="yes">
  <input type="hidden" name="quantity" value="1">
  <input type="hidden" name="identifier" value="Online Order">
  <input type="hidden" name="description" value="A very nice widget.">
  <input type="hidden" name="price" value="50.00">

  <!— relay --> 
    <input type="hidden" name="relay"value="http://www.yourwebsite.com/script_name"> 
  <!— end_relay >

  <input type="submit" name="" value="Submit Payment">
</form>

Passing Custom Data To Your (i.e. Relay) custom landing page receipt

Any fields that you would like passed to your receipt page put in the echo variable. The receipt page will be passed all variables in the echo variable, along with the variables transaction_code and tracking_code.

Parameter Format Description

echo

Alpha-Numeric

Only used when using the check_out script, put all variables that you would want to be passed to relay here. Note all variables should be HTML Encoded
Example: name="echo" value="id=5&name=Joe%20Smith"

<form method="POST" action="https://www.payjunction.com/trinity/quickshop/add_to_cart_snap.action"> 
  <input type="hidden" name="store" value="pj-qs-01">
  <input type="hidden" name="need_to_ship" value="yes">
  <input type="hidden" name="need_to_tax" value="yes">
  <input type="hidden" name="quantity" value="1">
  <input type="hidden" name="identifier" value="Online Order">
  <input type="hidden" name="description" value="A very nice widget.">
  <input type="hidden" name="price" value="50.00">
 
 <!— relay --> 
   <input type="hidden" name="relay"value="http://www.yourwebsite.com/script_name"> 
 <!— end_relay >

 <!— check_out -->
   
  <input type="hidden" name="echo"value="id=20&CompanyName=PayJunction"> 
 <!— end_check_out >
 
 <!— snap_check_out -->
   <input type="hidden" name="id" value="20">
   <input type="hidden" name="CompanyName" value="PayJunction"> 
 <!— end_snap_check_out>


 <input type="submit" name="" value="Donate">
</form>
Here is an example for sending information to your custom receipt page using the "echo" field:
<input type="hidden" name="relay" value="http://www.yourwebsite.com/yourreceiptpage.cgi">
<input type="hidden" name="echo"value="order_number=20&coupon=Free+frisbee+with+order."> 

On the other hand, you can just supply the extra fields (they will be passed through to your custom receipt page automatically):

<input type="hidden" name="order_number" value="20">

<input type="hidden" name="coupon" value="Free frisbee with order."> 

Response Fields that are sent to your custom receipt page (relay)

Parameter Description

transaction_code

"00" & "85" are Approved values

tracking_code

PayJunction generated tracking_code for this order.

fingerprint

The fingerprint code that was generated for payment button

store

The store id for the payment button

qs_total

The total dollar amount charged to the customer's card.

qs_total_shipping

The total shipping amount for the order

qs_total_tax

The total tax amount for the order

qs_number_last_four_digits

The last four digits of the credit card the customer used to make a purchase.

qs_cc_name

The name on the credit card.

qs_cc_city

The credit card billing statement city.

qs_cc_state

The credit card billing statement state.

qs_cc_street

The credit card billing statement street.

qs_cc_zip

The credit card billing statement zip code.

qs_cc_country

The credit card billing statement country.

qs_o_name

The name of the person to ship this order to.

qs_o_street

The street of the shipping address.

qs_o_city

The city of the shipping address.

qs_o_state

The state of the shipping address.

qs_o_zip

The zip of the shipping address.

qs_o_e_mail

The e-mail address of the customer.

qs_o_day_phone

A daytime phone number for the customer.

qs_o_day_phone_extension

The daytime phone number extension.

qs_o_night_phone

A nighttime phone number for the customer.

qs_o_night_phone_extension

The nighttime phone number extension.

invoice

The invoice number that was entered for the transaction

qs_o_notes

Any special notes relevant to the order.

qs_identifier

The short product description.

qs_description

A brief description of the product.

qs_quantity

The quantity to add to the cart.

qs_price

Cost for each item.

qs_need_to_ship

A value of "Yes" means that this item needs to be shipped.

qs_s_h_amount

The shipping & handling cost for each item.

qs_need_to_tax

A value of "Yes" means that this item was taxed.

qs_tax_amount

The amount to tax for each item.

Support

Please contact our support department if you require further assistance with Hosted Payment.

We can be reached at 800-601-0230 x 3, M-F, 8-5 PST

Submit a Request

Submit your support questions here.
We'll be in touch as soon as possible

SUBMIT REQUEST

Got Questions?

We’re here to help. Call us and speak
with a Customer Support Representative.

CALL US

TOLL FREE(800) 601-0230 x3

TOLL(805) 563-1520

BACKUP(805) 426-0404


FAX FREE(800) 771-3821

FAX TOLL(805) 569-3821

Send your Feedback

Let us know how we can improve.
We’re always happy to hear from you!

SEND FEEDBACK