This manual will guide you through the integration process that makes your website and Allied Wallet function as one. Integration involves implementing our APIs. APIs, application programming interfaces, are source code-based specifications that are intended to be used by software components that enable the components to communicate.
Implementing Allied Wallet’s Payment API will enable you to process your online transactions without as much tedious legwork. After our API codes are inserted you’ll be able to submit and process shopping cart and subscription transactions.
Our Payment API invokes an HTTP POST that initiates requests to Allied Wallet. Allied Wallet’s POST can be implemented into any web-programming language or even a simple web page.
Allied Wallet makes it easy. But if you find the API process a little overwhelming, don’t worry. Contact a representative and we will perform the integration for you at NO ADDITIONAL CHARGE.
1. Required Information
Before you will be able to submit live transactions to Allied Wallet, you will need an Allied Wallet merchant account for your website. Upon establishing an Allied Wallet merchant account, you will be provided a Merchant ID and a Site ID. These IDs uniquely identify your websites, customers, and payments. If you haven’t applied for a merchant account you can do so at:
https://sale.alliedwallet.com/index.aspx
2. Subscriptions
If you wish to offer subscriptions on your website, you will also need Allied Wallet to configure your subscription groups. The group configuration will set the levels, pricing, and terms for your subscriptions.
For example, you may have a standard subscription that costs $19.95 per month and a premium subscription that costs $99.99 per quarter. Allied Wallet will configure the two different groups so that your customers will be automatically rebilled at the end of each term period.
After Allied Wallet configures your subscription groups, you will need the URL to which your transactions will POST. The URL for HTML form posts is:
https://sale.alliedwallet.com/index.aspx
In order to POST your customers’ payments to Allied Wallet, you must include these fields. Please note the required fields and the optional fields and add accordingly:
| Field | Description | Type | Required/Optional |
|---|---|---|---|
| MerchantID | Merchant Reference ID supplied by Allied Wallet. | String | Required |
| SiteID | A Site Reference ID supplied by Allied Wallet for each site. | Sting | Required |
| AmountShipping | Total amount for shipping. This amount must be added to the item purchase price in the AmountTotal field. This field must be completed and will be “0” for subscription purchases. |
Decimal | Required |
| AmountTotal | Total amount of shopping cart or subscription items in transaction.
This number will be verified by Allied Wallet before the transaction can be completed. |
Decimal | Required |
| CurrencyID | Standard ID for the currency type you are collecting.
Common types accepted by Allied Wallet are: |
String | Required |
| ReturnURL | The URL you want your customers to return to after they have completed their purchase. | String | Required |
| CurrencyID | Standard ID for the currency type you are collecting.
Common types |
String | Required |
3. Configuring Your Site – Example Forms
To process payments, you’ll need to add two web pages to your site.
First, you’ll need to add the purchase form page. This page will initiate the Allied Wallet payment process.
Next, you’ll need to add a purchase complete page. Your customers will be returned to this page after successfully completing a purchase.
3.1. Purchase Form
You can include the purchase form on any page(s) on your site that is/are capable of posting information to Allied Wallet. You’re welcome to use any standard web-programming language, even HTML. You can construct the purchase forms to allowing recurring subscriptions and products.
Here are examples of a subscription and shopping cart form:
3.2. HTML Subscription Form
The following form includes all of the necessary information you’ll need to include for a subscription form. This will allow your customers to purchase subscriptions on your site:
<html> <head> </head> <body> <h1>Subscribe to Our Website</h1> Buy a subscription to our site. <form name="test" method="post" action="https://sale.alliedwallet.com/quickpay.aspx"> <input name="MerchantID" type="hidden" value="0000000-0000-0000-0000-00000000000"/> <input name="SiteId" type="hidden" value="0000000-0000-0000-0000-00000000000"/> <input name="AmountTotal" type="hidden" value="0.00" /> <input name="Address" type="hidden" value="8100 E Indian School" /> <input name="CurrencyID" type="hidden" value="USD"/> <input name="AmountShipping" type="hidden" value="0"/> <input name="NoMembership" type="hidden" value="0"/> <input name="GroupID" type="hidden" value="107"/> <input name="ReturnURL" type="hidden" value="http://www.yoursite.com/success.html" /> <input name="MerchantReference" type="hidden" value="PBI"/> <input type="hidden" name="ShowUserNamePassword" value="0" /> <input type="hidden" name="MemberUserName" value="UniqueName123456489" /> <input type="hidden" name="MemberPassword" value="UniquePassword123456789" /> <input type="submit" value="Buy Now - Subscription"/> </form> </body>
The HTML form above includes the “MerchantReference” field which is optional. This field can be used to correlate the Allied Wallet purchase transaction data with data from your website application.
After including the proper forms, your website and/or programmer will need to furnish your site with a front-end purchase form that matches your site.
You can include additional fields in the form to provide membership subscription Group IDs and Pricing IDs. See the field reference in the last section.
3.3. HTML Shopping Cart Form
Your shopping cart form can be included in simple HTML for single-item purchases on your website. The following form includes the script necessary for single-item purchases:
<html> <head> </head> <body> <h1>Buy Our T-Shirt</h1> Single item purchase form. <form method="post" action="https://sale.alliedwallet.com/quickpay.aspx"> <!-- *** Required fields for AlliedWallet --> <input name="MerchantID" type="hidden" value="0000000-0000-0000-0000-00000000000" /> <input name="SiteID" type="hidden" value="0000000-0000-0000-0000-00000000000" /> <input name="AmountTotal" type="hidden" value="17.99" /> <input name="CurrencyID" type="hidden" value="USD" /> <input name="AmountShipping" type="hidden" value="7.99" /> <input name="ShippingRequired" type="hidden" value="1" /> <input name="ItemName[0]" type="hidden" value="T-Shirt" /> <input name="ItemQuantity[0]" type="hidden" value="1" /> <input name="ItemAmount[0]" type="hidden" value="10.00" /> <input name="ItemDesc[0]" type="hidden" value="Our T-Shirt" /> <input name="NoMembership" type="hidden" value="1" /> <input name="ReturnURL" type="hidden" value="http://oursite.com/complete.htm" /> <input name="ConfirmURL" type="hidden" value="http://oursite.com/confirm.htm" /> <!-- *** Optional fields for AlliedWallet --> <input name="MerchantReference" type="hidden" value="abc123" /> <input name="submit" type="submit" /> </form> </body>
The form above will submit a transaction to purchase a single item for $10.00 plus $7.99 for shipping. See how the AmountTotal is equal to the ItemAmount + AmountShipping.
3.4. HTTP Post Form
If you would like more control over the subscription or shopping cart process, you will need to write a purchase form in any programming language that is capable of performing an HTTP POST. Common webpage programming languages that support this include: ASP.Net, Classic ASP, and PHP.
The HTTP POST is comprised of name-value pairs (NVP) concatenated into a
single string.
For example:
NAME1=value1&NAME2=value2&NAME3=value3&…
An NVP request string to Allied Wallet containing base information would be
similar to the following:
MerchantID=01234567-abcd-0000-0000-000000000000&SiteID=67890123-cdef-0000-0000-000000000000
&AmountTotal=0&CurrencyID=USD&AmountShipping=0&ReturnURL=http://oursite.com/complete.htm
The NVP request string must be URL-encoded prior to submitting to Allied Wallet. URL-encoding ensures that you can transmit special characters, characters that are not allowed in a URL, and characters that have special meaning in a URL such as the equal sign and ampersand. URL-encoding can be accomplished with the following methods, based on programming language:
3.5. Programing Language Method
| Programming Language | Method |
|---|---|
| ASP.Net | System.Web.HttpUtility.UrlEncode(buffer,Encoding.Default); |
| Classic ASP | Server.URLEncode |
| PHP | Urlencode() |
The above NVP string URL encoded would be:
MerchantID=01234567-abcd-0000-0000-000000000000&SiteID=67890123-cdef-0000-0000-000000000000
&AmountTotal=0&CurrencyID=USD&AmountShipping=0&ReturnURL=http%3a%2f%2foursite.com
%2fcomplete.htm
Once you have compiled the purchase request, your application must post it to
Allied Wallet in the following sequence:
- Post the request to Allied Wallet using HTTP.
- Receive the response string from Allied Wallet.
- Redirect the client to Allied Wallet.
The response string received from your post to Allied Wallet will have an NVP string similar to the post. The response will contain the following fields:
| Field | Description | Required/Optional |
|---|---|---|
| refID | Reference ID for completing the transaction. The customer must be redirected to the Allied Wallet site with the refID appended to the query string of the URL. | Required |
| Error | Numeric indication of the status of your request. If this value is ‘O,’ the request was completed successfully. | Required |
| Message | Text message containing a description of any error that occurred. | Required |
4. Complete Page
The ‘Complete Page’ can be any page on your website. The page will welcome the customer back after they complete their purchase. Here, you can provide any additional information regarding their product or subscription purchase (i.e. shipping information, subscription activation, etc.).
The URL of the ‘Complete Page’ is supplied by your page or application in the ReturnURL field.
After a customer has completed their purchase, Allied Wallet will load the designated ‘Complete Page’ which will contain a transaction ID and merchant reference. For example, if you provided the following ReturnURL in your purchase form:
http://oursite.com/complete.html
Allied Wallet would complete the transaction and return the customer to the following URL:
http://oursite.com/complete.html?TransactionID=67890123-cdef&MerchantReference=abc123
5. Confirm Page
After a customer has successfully completed a transaction, Allied Wallet will post the transaction details onto a page that you designate on your site. This page should validate and store the transaction information in your database. The ‘Confirm Page’ should provide communication between Allied Wallet and your application. The page does not need to provide user functionality.
Allied Wallet 7 Rev. 1.14
The URL of the ‘Confirm Page’ must be a valid page on your website or application, then placed in the ConfirmURL field. If a URL is not supplied or does not point to a valid page on your site, the transaction will not be completed successfully. If you do not wish to save transaction details and information, the page can be a blank HTML page.
Information posted to the ‘Confirm Page’ is posted as standard HTTP Post name-value pairs (NVP) separated by ampersands (&). An example of a confirm post reads:
Amount=17.99&MerchantReference=abc123&PayReferenceID=b9ab260b-d690-4507-8d56-8bd92c4c132a&
ampTransactionID=4cfdefc3-6ad2-49de-a25b-5d0f41e8cd1a
6. Membership Postback
If your website is a subscription or membership site, you can elect to have Allied Wallet post subscriber/membership event information to a designated page on your website. If you wish to receive membership postback events, you must provide Allied Wallet merchant support with a postback URL. After receiving the postback URL, Allied Wallet will provide you with a postback key for validating Allied Wallet postback events.
Subscriber events posted to your website can include:
Add
- A new customer has completed a subscription purchase
- An account is created for your website
Cancel
- A customer has cancelled their subscription to your site
Deactivate
- You have deactivated a customer’s subscription via merchant terminal
Password
- A customer’s subscription account password has changed
The following fields are transmitted by Allied Wallet in a membership postback event.
| Field | Description | Type | Postback Events |
|---|---|---|---|
| Username | Subscriber Username | Sting | Add, Cancel, Deactivate, Password |
| Subscriber Email Address | String | Add, Cancel, Deactivate, Password | |
| FirstName | Subscriber First Name | String | Add, Cancel, Deactivate |
| LastName | Subscriber Last Name | String | Add, Cancel, Deactivate |
| MemberID | Subscriber unique ID assigned by Allied Wallet | String | Add, Cancel, Deactivate, Password |
| TransactionID | Transaction that prompted the subscriber change | String | Add, Cancel |
| Password | Subscriber password | String | Add, Cancel |
| GroupID | ID for the payment group assigned to the site | Integer | Add |
| PriceID | ID for the payment assigned to the site | Integer | Add |
| Action | Type of request post. Values are: – Add – Cancel – Deactivate – Password |
String | Add, Cancel, Deactivate, Password |
| Key | Encryption key assigned by Allied Wallet. | String | Add, Cancel, Deactivate, Password |
Fields are transmitted in name-value pairs (NVP).
After your membership page receives a post from Allied Wallet, your page must transmit an acknowledgement response. The response is a colon-delimited string containing status and a message. The status must be “0” if the post failed and “1” if it was successful. If it failed, the message must contain a description of the error. An example of a successful acknowledgement string reads:
1:success
An example of an unsuccessful acknowledgement string reads:
0:user does not exist
7. Confirm Postback Fields
Upon successful completion of a transaction and if the ConfirmURL is supplied, an HTTP POST is performed to the page.
| Field | Description | Type |
|---|---|---|
| Amount | Total amount of shopping cart or subscription items in transaction | Decimal |
| MerchantReference | Reference generated by the merchant to correlate the purchase to the Allied Wallet transaction. | String |
| PayReferenceID | The ID of the transaction in the Allied Wallet merchant system. | String |
| TransactionID | The ID of the transaction in the Allied Wallet sale application. | String |
7.1. Custom Images
The CustomPay API allows you to edit and customize your payment page. To edit, login to the gateway with the credentials given, navigate to “Merch Setup/Site Management/Configure Site.” Find “Payment Style Settings.” Here, you can change the page color, form color, and font colors. To upload logos, simply choose your top and side logo, then click “save.”
8. Congratulations
After you have completed the process as detailed in this manual, please contact your Allied Wallet agent or representative.
