What is Payza Advanced Integration Guide

Advanced Integration is for online sellers who want more flexibility when creating payment buttons. Advanced Integration facilitates the creation of dynamic "Buy Now" buttons found in many shopping cart and e-commerce solutions, though some knowledge of HTML coding is required. It's highly recommended to read Payza's Integration Best Practices Guide before using advanced integration.

Advanced Button Creation

When creating an Advanced Button, you must use the proper parameters in the HTML form of your payment button. Contrary to the Standard Button, which only contains the ap_productid and ap_quantity variables, the Advanced Button requires the use of additional parameters so your checkout page more precisely describes the item you are selling. Depending on the values and parameters sent to the Payza checkout page, each buyer will see different information.

Anatomy of an Advanced Button code

To understand how an Advanced Button is processed during checkout, we will use the following "Buy Now" button code as an example:

<form method="post" action="https://secure.payza.com/checkout"> <input type="hidden" name="ap_merchant" value="payza_merchant@test.com"/> <input type="hidden" name="ap_purchasetype" value="item"/> <input type="hidden" name="ap_itemname" value="MP3 Player"/> <input type="hidden" name="ap_amount" value="50"/>  <input type="hidden" name="ap_currency" value="USD"/> <input type="image" src="https://www.payza.com/images/payza-buy-now.png"/> </form>

The sample code above transmits the parameters (shown in boldface) and their value to our checkout page using the POST method: https://secure.payza.com/checkout.

The five parameters that are present in the code are the minimum required parameters for the Advanced payment button to function properly. If any of those variables are missing, an error message will be displayed rather than a regular checkout page.

Clicking on the "Buy Now" button will bring the customer to the following page:

The five parameters that are sent to our checkout page influences what is displayed to the buyer on the same page:

ap_merchant
The value, apdevforum@gmail.com, represents the seller’s Payza account and where the payment will be sent to. The email address must be in the proper format and must be registered in the Payza network or an error message will be returned. Payza will capture and display the business name associated with the email address.
ap_purchasetype
The value can be item, service, item-goods or item-auction since you are only selling a single item at a time to the customer. However, if the item’s value were to be changed to subscription, the necessary parameters to create a proper "Subscribe Now" button must be included. Please refer to the Subscription Button section for more information. The ap_purchasetype is not displayed on the checkout page, but its value will be returned in the IPN messages for you to capture and process.
ap_itemname
The names of all items or services sold must be displayed on the checkout page so the buyer knows what they are purchasing. In our case, "MP3 Player" is the value that is provided and shown on the checkout page.
ap_amount
The value provided for this parameter is the price of the item or service. The amount must be greater or equal to the minimum amount allowed by Payza.
ap_currency
The value of this parameter is a three-letter ISO-4217 code for a given currency (For example, Canadian currency is represented as CAD). The value will specify the currency in which the payment will be made through the button.

Other button parameters

The five aforementioned variables are the basic parameters that must be present in an Advanced button. Payment buttons can be further customized to include extra parameters in the HTML form. For example, the bold elements in the following HTML form code are all optional parameters that may affect the behavior of the button on the checkout page:

<form method="post" action="https://secure.payza.com/checkout" >
<input type="hidden" name="ap_merchant" value="payza_merchant@test.com"/>
<input type="hidden" name="ap_purchasetype" value="item-goods"/>
<input type="hidden" name="ap_itemname" value="MP3 Player"/>
<input type="hidden" name="ap_amount" value="50"/>
<input type="hidden" name="ap_currency" value="USD"/>

<input type="hidden" name="ap_quantity" value="2"/>
<input type="hidden" name="ap_itemcode" value="XYZ123"/>
<input type="hidden" name="ap_description" value="Audio equipment"/>
<input type="hidden" name="ap_returnurl" value="http://www.example.com/thankyou.html"/>
<input type="hidden" name="ap_cancelurl" value="http://www.example.com/cancel.html"/>

<input type="hidden" name="ap_taxamount" value="2.49"/>
<input type="hidden" name="ap_additionalcharges" value="1.19"/>
<input type="hidden" name="ap_shippingcharges" value="7.99"/>

<input type="hidden" name="ap_discountamount" value="4.99"/>
<input type="hidden" name="apc_1" value="Blue"/>


<input type="image" src="https://www.payza.com/images/payza-buy-now.png"/>
</form>

The following image shows the effect that these additional parameters have on the "Buy Now" button once a buyer clicks on it.

Payza’s checkout page will display the details that correspond to the additional values:

You may include other variables to further customize your button so that it does what you want it to. For a complete listing of these parameters and their expected values, please refer to the Button Parameters Table.

Multi-Item Button

The Multi-Item Button’s main functionality is to further enhance your shopping cart integration by listing the details of individual items on the Payza checkout page. Alternatively, you can easily build product packages with a Multi-Item Button and sell your goods or services as bundles.

When using the Multi-Item Button, all five required HTML variables are the same as the ones used for the single-item button. From those five parameters, the only variable that will differ is ap_itemname, which will have a _x added to it. The following variables will also have a _x added to the end of their respective names:

ap_itemname_x
ap_description_x
ap_itemcode_x
ap_amount_x
ap_quantity_x

The appended _x is the item number. The first element will keep its original name and will not have number appended to it. The second element will start with 1 and increasing by one for each additional item.

The item number specified by _x value ties the optional variables, such as the ap_description, to the corresponding ap_itemname variable, which is required.

To ensure that your items will be recognized, the _x values must continuously increase by increments of one. Skipping an item number will result in an error on the Payza checkout page. For example, if you skip from item #1 to item #3, an error will occur.

Currency of the Multi-Item Button

The currency of the Multi-Item Button is not item-specific and is defined for the entire set of items by the ap_currency variable. It will keep its original name, so there is no need to add _x to the ap_currency variable. The currency is applied to all the monetary variables in the payment button: ap_amount, ap_taxamount, ap_discountamount, ap_additionalcharges, ap_shippingcharges, ap_setupamount and ap_trialamount.

Passing multiple items to Payza

The following HTML code for a Multi-Item Button will pass three different items to the checkout page. Information on each item will be displayed on a different line on the checkout page:

<form method="post" action="https://secure.payza.com/checkout" >

<input type="hidden" name="ap_purchasetype" value="item"/>
<input type="hidden" name="ap_merchant" value="apdevforum@gmail.com"/>
<input type="hidden" name="ap_currency" value="USD"/>

<input type="hidden" name="ap_itemname_1" value="Item 01"/>
<input type="hidden" name="ap_itemname_2" value="Item 02"/>
<input type="hidden" name="ap_itemname_3" value="Item 03"/>

<input type="hidden" name="ap_description_1" value="Lorem ipsum"/>
<input type="hidden" name="ap_description_2" value="Na misnet par"/>
<input type="hidden" name="ap_description_3" value="Lun der ter"/>

<input type="hidden" name="ap_itemcode_1" value="7462"/>
<input type="hidden" name="ap_itemcode_2" value="5955"/>
<input type="hidden" name="ap_itemcode_3" value="8943"/>

<input type="hidden" name="ap_quantity_1" value="1"/>
<input type="hidden" name="ap_quantity_2" value="4"/>
<input type="hidden" name="ap_quantity_3" value="2"/>

<input type="hidden" name="ap_amount_1" value="35.00"/>
<input type="hidden" name="ap_amount_2" value="24.00"/>
<input type="hidden" name="ap_amount_3" value="67.00"/>

<input type="hidden" name="ap_returnurl" value="https://www.payza.com"/>
<input type="hidden" name="ap_cancelurl" value="https://www.payza.com"/>
<input type="image" name="ap_image" src="https://www.payza.com/images/payza-buy-now.png"/>

</form>

The HTML code above will generate the following output on the Payza checkout page:

Please see the Multi-Item Button document for a description of its parameters and for further information on this feature.

Advanced Button Security & IPN

Anyone can see the HTML code for your "Buy Now" buttons, which means that a third-party can tamper with the item variables and make fraudulent payments if they so choose.

If you are using an Advanced button on your website or have integrated Payza with your shopping cart application, we highly recommended that you use our Instant Payment Notification (IPN) feature to verify the payments made to your account.

An IPN is a notification that contains details on the payment and the customer. You can use this information for any post-payment tasks, such as updating your inventory or database, issuing receipts and fulfilling orders.

Payza notifies you as soon as a transaction has been successfully made and posts all the payment details at a URL (in your website) that you have provided. IPN messages are sent when payments are made on your website through our checkout page or when you have successfully paid someone through Payza’s MassPay API.

To learn more about using our Instant Payment Notification, please refer to our IPN Guide.

Don't forget to complete your website review!

You will also need to complete a website review for your buttons to be operational in your website.

Submitting your website/business for review is simple and fast. Just follow these instructions:

  1. Login to your Payza account.
  2. Click on "Business".
  3. Under “Business”, click on “Websites”.
  4. Click on the button “Add a Website”on the upper right side of the page
  5. Fill in the questionnaire’s required fields and click on “Send”.