How Do I Get Started?

Starting out using any API can be a daunting task where you don't know where to begin. We recommend checking out the following items before getting into the nitty gritty of coding your amazing applications!

• - Create an account on our test site(sandbox.prioritypaymentsystems.com)
• - Decide on and read about the API package that meets your needs
• - Read about OAuth Authentication(OAuth.net)
• - Browse the available documentation, FAQ section( you are already there! ) and blogs and comments and even code examples.

OAuth Authentication & Lingo

What is OAuth? What is a consumer_key/consumer_secret? How do I obtain these things??

Please visit the section we have created regarding OAuth Authentication, but also the OAuth website for a more expansive, in-depth explanation of this form of authentication. Different APIs use different terminology in regards to a 'consumer key' and 'consumer secret'. Others use the terms API KEY, API SECRET, Developer Key/Secret, Developer Code/Password. We use the terminology 'consumer key' and 'consumer secret' to stay consistent with the necessary parameters 'oauth_consumer_key' and 'consumer secret'. This way there is little guessing as to the meaning and use of these values.

When registering for any package, you will be given an api_key and secret for each selected. The package key will be used as you 'oauth_consumer_key' when making calls to the API. If omitted, the developer portal will return an error stating Developer Inactive. These calls will not even make it to our API and will not have any API-produced validation. To obtain your API_key please register with us for your key and we will promptly supply them to you.

Payment Tokenization

Can you store a payment method (i.e. a credit card) when you create a customer. So that you may later charge the customer using a token rather than having to pass the credit card information in the future?

Yes! Our API fully supports storing card information in a more secure form such tokenized data. This feature has has PCI-compliance benefits for anyone choosing to use this method.

Shopping Carts

What Shopping Carts does Priority Payment Systems plan on certifying with and when can these dates expect to be annouced?

Currently, this is a tentative list of shopping carts but, unfortunately, dates have not been announced.

• Open-Cart
• X-Cart
• Zen-Cart
• Ubercart
• Miva Merchant
• OsCommerce
• Magento
• Volusion
• Shopify

Data Importing

If we have a merchant using the API, can they customize the data that they pull out of MX to import into their accounting software?

On the ever-growing MX Merchant™, most pages have an 'export' button. This button will export the data on the currently selected page as a .CSV file. These types of files can be directly imported to spreadsheet and accounting software such as Excel an Quickbooks.

Shipping costs

Does MX Merchant or the API have the ability to calculate and apply shipping charges?

At the moment feature is not supported.

Discounts

Does MX Merchant or the API have the ability to calculate and apply discounts if the customers order exceeds a certain dollar figure or limitation?

Yes! MX Merchant allows the creation of discounts which can be applied on a per order or per item basis.

iOS sdk

I'm not seeing/able to locate the iOS library on the website. Am I missing it or is there a tentative time frame for the release of it?

The iOS SDK is currently not listed on the website/available for use. At this time there is no available time frame for its release.

Card Present transactions

We are very excited to use the API. We would like to be able to qualify for "Card-Present" rates. How does the API determine if a card was present during the transaction?

Good question! When making a call to either of our two payment routes:

• /Payment
• /Order/{id}/payment

You are accessing the payment model. An sub-model of this is the cardAccount model that has an optional attribute called "magStripe". When you use an encrypted magStripe to capture the card information, if passed through in this attribute (rather than manually entering the card number etc) this signifies the card presence during the transaction.

Receipts

How does the text receipt work? If we want to develop an android app can we push out the text receipt thru the MX servers or does the device have to do it?

There are many ways to generate a receipt. For API use regarding mobile development, I would recommend taking a looking at our mobile package. This is a listing of resources/routes that we believe will be frequently used in this type of development.

Methods of accessing receipts:

• POST payment{id}/receipt
• GET payment{id}/receipt
• POST order/{id}/receipt

In MX Merchant, under the settings tab you can manage your receipt options. Per Merchant, you have the ability to save important information such as a merchant logo, address, contact information etc.. When you generate API-offered receipts this is where some of your information will be pulled from. Of course you are free to create/design your own receipt using this data.

Order

How can I create an order that is directly associated to a customer via the API?

There are 2 methods that can be used to create an order while associating it to a specific customer. The following are 2 routes that are able to accomplish this task.

• POST /order
• POST customer/id/order

When creating an order, the customer attribute can be filled in with the customer id and name. Doing this creates an order associated with that customer. A secondary method is to associate an order with a customer by going through the customer resource (e.g POST customer/id/order). Once an order has been created it can be associated with a customer using the secondary method, however, adding items/discounts to an order can not be accomplished using the following routes.

• customer/id/order/id/purchase
• customer/id/order/id/payment
• customer/id/order/id/discount

The above resources do not exist. Editing/maintaining orders should be completed via the order resource itself. ( /order/id/purchase..etc)

Discounts

What is the difference between an order-level, and item-level discount. Do I apply them in the same way or differently?

• Order level - A discount that apply to the order and an aggregate of its items, accessed via order/id/discounts
• Item level - discounts that exist on a per-item basis and are independent of other items on the order, accessed via order/id/purchases/subId

As an example, an order-level discount may take 10% off of an entire order. An item-level discount will assess the purchases on an order an it will be appended to those purchases that have the same tags.

• POST /order
• POST customer/id/order

When creating an order, the customer attribute can be filled in with the customer id and name. Doing this creates an order associated with that customer. A secondary method is to associate an order with a customer by going through the customer resource (e.g POST customer/id/order). Once an order has been created it can be associated with a customer using the secondary method, however, adding items/discounts to an order can not be accomplished using the following routes.

• customer/id/order/id/purchase
• customer/id/order/id/payment
• customer/id/order/id/discount

The above resources do not exist. Editing/maintaining orders should be completed via the order resource itself. ( /order/id/purchase..etc)

Recurring Transactions

I have a customer who wants to use our API to sell Spa memberships online and through an email blast. Hence recurring monthly transactions. Is there a way that we can retrieve and send information to the API for these kind of transactions? If this component is still under development what time frame are we looking at to get this component up and running?

The API does support recurring transactions. Below is a link with the current information we have made available about recurring transactions. Our API refers to recurring transactions as plans. Customers subscribe to a plan. The plan holds the details regarding the frequency and amount of the charges. This feature should be available when the API is released.

Accounting Integration

If we have a merchant using the API, can they customize the data that they pull out of MX to import into their accounting software?

Our API has the ability to export .csv files about many types of data. By appending 'ext=csv' in the the query parameters of a call to the API, you can grab the requested data as a csv file.

Android

Does the MXiPOS support the Samsung Galaxy Note?

Currently the iPos is not available on Android-based devices. Though, as Android is Java-based, applications can be easily writte that interact with our API!

User Authorization Limit

Does the new API support the User Authorization Limit? If so, is it implemented yet?

The User Authorization Limit is a security feature of MX Merchant™. Each merchant can set up users that have sale and refund limits. Merchants can restrict their user to dollar figure limits. For example, if a merchant does not want a newly-hired employee to be able to run sale or refund transactions greater than 25$, this is made available by setting that users limits to the necessary figures.

Yes! As sales and refunds still operate through the MX Merchant™ database on a per merchant level, user authorization limit configurations still apply when payments or refunds are submitted using the API.

Purchases and Products

• - What is a purchase? And how does it differ from a product?
• - How does a purchase relate to an order?
• - Do purchases ever exist independent of an order

A purchase is an instance of a product that a user is planning on buying(purchasing). Products continue to sit on a merchants shelf regardless of whether someone buys them. So, products are what the merchant offers. Some items may/may not be in stock. Purchases are what the customer/user selects as items they would like to buy. Purchases do not exist outside of an order, but products may.

Customer Order Association

Is there a route to associate a Customer with an Order?

The order model contains the customer attribute. When populated with a customer id and name, the order will then be associated with that customer.

Required Loyalty

Is Loyalty functionality required to be a part of a regular transaction flow?

The loyalty program is available to merchants who subscribe to the Premium plan or higher. If enabled and configured, customers who have signed up for the loyalty program are able to reap the benefits of the program at that point. Although a great additive to any business model, the loyalty functionality is not required during the traditional transaction flow.

MID vs. XMID

Merchants, via our new merchant interface, have a MID(merchantId) in addition to the XMID. What is the difference?

The XMID is more often used as merchant identifier in MX Merchants sister application MXA(MX IsoAgent). Similar to live, Test merchants have an available XMID and MID. However, non-live merchants aren't viewable within MXA. Because of this, and to create a more simple number to remember, the MID is used during transactions requiring a merchantId.

Token Expiration

I ran into the following validation:
{"errorCode":"InvalidToken","message":"Invalid_token_","responseCode":"d999b730a2a5407cbbc741cc22709d21"}
What does this mean?

OAuth 2-Leg authentication can be accomplished using either a consumer key and secret created within a merchants account. These keys can also be substituted for the username and password of user set up for that merchant. A valid access token is the key to API interaction. By nature, our sandbox environment is meant for testing, so it does not have the logic inplace to invalidate your token. An InvalidToken response certainly means you are unable to transact with a merchant data via the API using that token , but expiring of the token can occur for different reasons:

• - Too many consecutive failing calls to the API(commonly due to signature)
• - The obtained token is being used outside of its lifespan(E.g tokens granted via 2-Leg authentication are available for use for 24 hours)
• - The token you are using is valid, but is being used against a merchant that it was not authorized for
• - The API was unable to grant an access token based on a locked consumer key

For live merchants, currently, consumer keys and secrets can be added and deleted from a list of applications that can currently access the merchants data. Removing the consumer key and secret will disable API connectivity using that key/secret. Consumer keys and secrets currently do not have a locking mechanism with the Production API.