Introduction
Advanced Integration is for 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.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 theap_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 AlertPay 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://www.alertpay.com/PayProcess.aspx" > <input type="hidden" name="ap_merchant" value="apdevforum@gmail.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.alertpay.com//PayNow/4F59239578EA46C1AD168BA6E9BD2067g.gif"/> </form>The sample code above transmits the parameters (shown in boldface) and their value to our checkout page using the POST method:
https://www.alertpay.com/PayProcess.aspx.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 AlertPay account and where the payment will be sent to. The email address must be in the proper format and must be registered in the AlertPay network or an error message will be returned. AlertPay 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 AlertPay.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://www.alertpay.com/PayProcess.aspx" > <input type="hidden" name="ap_merchant" value="apdevforum@gmail.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="Lorem ipsum dolor sit amet. Proin eleifend congue congue."/> <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.alertpay.com//PayNow/4F59239578EA46C1AD168BA6E9BD2067g.gif"/> </form>The following image shows the effect that these additional parameters have on the "Buy Now" button once a buyer clicks on it. AlertPay’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.
Using Form Pre-Filling
Since you can accept payments from people who do not have an AlertPay account, you can easily send information related to a buyer to the form on our checkout page. If you have already captured the necessary information before the customer clicks on the payment button, such as their name and address, you can pre-fill the fields on the checkout page by adding the following optional parameters to your Standard or Advanced buttons:ap_fname ap_lname ap_contactemail ap_contactphone ap_addressline1 ap_addressline2 ap_city ap_stateprovince ap_zippostalcode ap_countryFrom the information you capture when directing a customer to the checkout page, your website must dynamically generate the values for each field listed above when a customer clicks on a payment button.
Here is an example of an Advanced “Buy Now” button’s HTML code with optional form pre-filling parameters:
<form method="post" action="https://www.alertpay.com/PayProcess.aspx" > <input type="hidden" name="ap_merchant" value="apdevforum@gmail.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="10"/> <input type="hidden" name="ap_currency" value="USD"/> <input type="hidden" name="ap_fname" value="John" /> <input type="hidden" name="ap_lname" value="Doe" /> <input type="hidden" name="ap_contactemail" value="email@domain.com" /> <input type="hidden" name="ap_contactphone" value="5555555555" /> <input type="hidden" name="ap_addressline1" value="123 Test Street" /> <input type="hidden" name="ap_addressline2" value="Apt #101" /> <input type="hidden" name="ap_city" value="Montreal" /> <input type="hidden" name="ap_stateprovince" value="QC" /> <input type="hidden" name="ap_zippostalcode" value="H0H0H0" /> <input type="hidden" name="ap_country" value="CAN" /> <input type="image" name="ap_image" src="https://www.alertpay.com//PayNow/
4F59239578EA46C1AD168BA6E9BD2067g.gif"/> </form>The previous code will generate the following on our checkout page:
Please refer to the Form Pre-Fill parameters table for a complete description of each variable.
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 AlertPay 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_xThe 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 AlertPay 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 theap_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 AlertPay
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://www.alertpay.com/PayProcess.aspx" > <input type="hidden" name="ap_purchasetype" value="item"/> <input type="hidden" name="ap_merchant" value="forum@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.alertpay.com"/> <input type="hidden" name="ap_cancelurl" value="https://www.alertpay.com"/> <input type="image" name="ap_image" src="https://www.alertpay.com//PayNow/
4F59239578EA46C1AD168BA6E9BD2067g.gif"/> </form>The HTML code above will generate the following output on the AlertPay 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 AlertPay 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.
AlertPay 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 AlertPay’s MassPay API.
To learn more about using our Instant Payment Notification, please refer to our IPN Guide.
No comments:
Post a Comment