Allied Wallet China UnionPay API (Ver 1.15 Updated 2/20/2011)

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.

Covered in this API

  1. Required Information
  2. Subscriptions
  3. Item 3
    1. Configuring Your Site – Example Forms
    2. Purchase Form
    3. HTML Subscription Form
  4. Complete Page
  5. Confirm Page
    1. Decline Page
  6. POST Field Reference
  7. Congratulations

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://portal.alliedwallet.com/application/default.aspx

Top

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 POST transactions to. 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:

Top

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.

Top

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:

Top

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 Code is here

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.

Top

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

Top

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&TransactionID=4cfdefc3-6ad2-49de-a25b-
5d0f41e8cd1a

5.1 Decline Page

After a customer has completed a transaction through the ChinaPay/UnionPay system and their purchase has been declined, Allied Wallet will redirect the customer to this page. This page is similar to the ReturnURL, but additionally, it alerts the customer that their purchase was not successful.

The URL of the decline page is supplied by your domain and/or application in the DeclineReturnURL field. The URL is optional. If this value is not passed with the purchase information, they will be redirected to the ReturnURL instead.

Top

6. POST Field Reference

Field Description Type Postback Events

Address

Billing address of
customer

String

Optional

Address2

Billing address 2 of
customer

String

Optional

AmountTotal

The 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

City

Billing city of customer.

String

Optional

ConfirmURL

Upon successful
completion of a
transaction, the details of the transaction will be posted to this URL.

String

Required

Country

Billing 2-character country code of customer.

Examples:
• MX — Mexico
• CD — Canada

String

Option

CurrencyID

Standard ID for the
currency type you are collecting.

Common types
accepted by ChinaPay through Allied Wallet include:
• USD – US Dollars
• JPY – Japanese
Yen

String

Required

DeclineReturnURL

Upon a decline of a credit card, the customer will be redirected here.

String

Optional

Email

Billing email of customer.

String

Optional

FirstName

Billing first name of customer.

String

Optional

ItemAmount[n]

The TOTAL amount of the n-th product in the purchase, where “n” represents the number of items, starting with ‘0’
(zero).

This amount
Decimal Required
should be the unit cost for the product multiplied by the quantity.

Example:
If a product costs $5.00 and 3 are being ordered, 15.00 should be the value in this field.

Decimal

Required

ItemName[n]

The quantity of the nth product in the shopping cart, n represents the number of items in the shopping cart starting with ‘0’ (zero).

The quantity must be at least 1 (one) or an error will be returned.

String

Required

ItemQuantity[n]

The quantity of the nth product of the purchase.

“n” represents the
number of the item,
starting with ‘0’ (zero). The quantity must be at least ‘1’ or an error will be returned.

Integer

Required

ItemDesc[n]

The description of the nth product in the shopping cart, n represents the number of items in the shopping cart starting with 0.

String

Required

LastName

Billing last name of
customer.

 

Optional

MerchantID

Merchant Reference ID supplied by Allied Wallet.

String

Required

MerchantReference

Reference generated by the merchant to correlate the purchase to the Allied Wallet transaction.
This value is returned to the merchant complete page query string (URL).

String

Optional

PostalCode

Billing postal code of customer.

String

Optional

ReturnURL

The URL you want your customers to return to after they have completed their purchase.

String

Required

SiteID

A Site Reference ID supplied by Allied Wallet for each site.

String

Required

State

Billing state of your customer.

String

Optional

Top

7. Congratulations

After you have completed the process as detailed in this manual, your integration is ready for review and you are one step closer to processing payments with Allied Wallet. Fill out the form bellow to allert Allied Wallet compliance that you have completed the integration of your Allied Wallet China UnionPay APIs.

[contact-form-7 id="578" title="Integration Status"]

Top