MX™Merchant API

Integrate payment processing into your website, custom application or mobile app using MX Merchant API. Create seamless integration with online account management for fast and accurate transactions, access to customer data and more.

VAR/POS

Use MX Merchant API to integrate your POS solutions with online account management tools for fast access to sales data.

MOBILE APPS

Add payment processing to your mobile apps with MX Merchant API.

WEBSITES

MX Merchant API makes it easy to integrate your shopping cart solution.

SOCIAL/GAMING

MX Merchant API lets you collect recurring payments, track customer transactions and more.

Getting started

Not sure how a user gets started???

REST services

The MX™Merchant API is implemented as a full featrued REST service. Every request is a standard HTTP request and result in an HTTP status code.

Http Requests

Data Formats

Developers can request control the format of the response data by setting the Accept request header to any of the following values.

application/json
application/xml
application/x-www-form-urlencoded
application/octet-stream
application/x-protobuf

Similarly, developers can request a specific response format by including an extension in the URL. Here are the supported extensions.

.json
.xml
.proto

Accept-Encoding:

The API provides developers with the option of compressing the responses. This can be done by setting the Accept-Encoding request header to gzip.

Example

Here is an example of a request that expects a gzip compressed JSON response:

GET https://api.pps.io/v1/customer HTTP/1.1
Authorization: OAuth oauth_consumer_key="00000000-0000-0000-0000-000000000000",
                     oauth_nonce="0YhM7uEp",
                     oauth_signature_method="HMAC-SHA1",
                     oauth_signature="N3245RcYzkY01yQsgB1fqIlF4cY%3D",
                     oauth_version="1.0",
                     oauth_timestamp="1344019030"
Accept: application/json
Accept-Encoding: gzip

Http Responses

Developers will use this status code to insure that the application is performing as expected.

HTTP Status Codes

All success status codes will be between 200 - 299

200 OK
The request was successful.
201 Created
The resource was successfully created.
204 No Content
The request was successful and there is no response. This is the response to all delete requests.

Error status codes will be between 400 - 499

400 Bad Request
The request was failed validation or could not be understood by the server.
401 Unauthorized
Your API key is missing or invalid.
403 Forbidden
The request is attempting to access a resource it does not have privileges to access.
404 Not Found
The requested resource could not be found.
406 Not Acceptable
The request's Accept header is invalid.

Pagination

Paged responses allow developers to request targetted data without getting results that they might not need.

All GET requests support an offset and limit parameter that can be used for paging. The pagination defaults are offset = 0 and limit = 10.

Security

Using OAuth

Authorization is handled via OAuth 1A (RFC 5849) standards. The authorization process consists of 2 requests. First you must get a request token and then an access token. The access token can be used for all subsequent calls to the services.

Priority Payments chose to utilize OAuth because it is an open standard. This allows developers to take advantage of several open-source client libraries. Utilizing one of these libraries will reduce the time spent implementing authorization. These libraries have been implemented in many of the most popular programming languages and you can review many of them on the OAuth site: http://oauth.net/code.

For more information about OAuth, please visit the OAuth website

Direct access

This authentication flow is designed for developers that are are attempting to access data associated to their account using the API. Developers commonly refer to this as 2-legged OAuth authentication. There are 3 steps authenticating:

Get Request Token

Request

POST https://api.pps.io/v1/OAuth/1A/RequestToken HTTP/1.1
Authorization: OAuth oauth_consumer_key="00000000-0000-0000-0000-000000000000",
                     oauth_nonce="0YhM7uEp",
                     oauth_signature_method="HMAC-SHA1",
                     oauth_signature="N3245RcYzkY01yQsgB1fqIlF4cY%3D",
                     oauth_version="1.0",
                     oauth_timestamp="1344019030"
Accept: application/x-www-form-urlencoded

Response

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded

oauth_token=660b21b4-d3ee-4ce1-84f5-a3ec8c52ea42&oauth_token_secret=dea7c4de-f346-403f-962c-181ae8338800

Get Access Token

Request

POST https://api.pps.io/v1/OAuth/1A/AccessToken HTTP/1.1
Authorization: OAuth oauth_token="4499eddf-2633-415a-b221-90cbf7823dce",
                     oauth_consumer_key="00000000-0000-0000-0000-000000000000",
                     oauth_nonce="vYXqb3Jq",
                     oauth_signature_method="HMAC-SHA1",
                     oauth_signature="%2FUeW4NTL4NV88XOYPAKr3ANGn7A%3D",
                     oauth_version="1.0",
                     oauth_timestamp="1344019030"
Accept: application/x-www-form-urlencoded

Response

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded

oauth_token=d7874463-b31b-4851-be5f-bcea985f895d&oauth_token_secret=19142a9a-f2fb-4c72-8238-80b63645aba5

Api Request Auth

Every request that is sent to the API will be accompanied with the proper auth. This will consist of several parameters added to the querystring.

oauth_token: the previously acquired token
oauth_consumer_key: this is the public key for the consumer account being used for the request
oauth_nonce: a unique string that can only be used once per request
oauth_signature_method: this should be set to: HMAC-SHA1
oauth_signature: the signature is a hash of the entire request and consumer secret
oauth_version: this should be set to: 1.0
oauth_timestamp: the unix timestamp defining when the request was sent

Accessing via applications

Developers that are writing applications for users are going to use to access their data should use this authetication method. Developers refer to this flow as 3-legged OAuth Authentication.

Get Request Token

This request is similar to the first example except that it includes an oauth_callback parameter which will be used to notify the client that the user completed the authorization process.

Request

POST https://api.pps.io/v1/OAuth/1A/AccessToken HTTP/1.1ß
Authorization: OAuth oauth_token="4499eddf-2633-415a-b221-90cbf7823dce",
                   oauth_consumer_key="00000000-0000-0000-0000-000000000000",
                   oauth_nonce="vYXqb3Jq",
                   oauth_signature_method="HMAC-SHA1",
                   oauth_signature="%2FUeW4NTL4NV88XOYPAKr3ANGn7A%3D",
                   oauth_version="1.0",
                   oauth_timestamp="1344019030"
                   oauth_callback ="http://your.callback.url"
Accept: application/x-www-form-urlencoded

Response

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded

oauth_token=d7874463-b31b-4851-be5f-bcea985f895d&oauth_token_secret=19142a9a-f2fb-4c72-8238-80b63645aba5&oauth_callback_confirmed=true

Redirect to Login

The developer should redirect the user to the Priority Payments login so the user can authenticate and connect the application to their merchant account. After the user authenticates with Priority, we will make a callback to the oauth_callback URL that was included in the request token request. This callback will include two important parameters. These are oauth_token and oauth_verifier.

GET /cb?oauth_token=d7874463-b31b-4851-be5f-bcea985f895d&oauth_verifier=4732f82d3  HTTP/1.1
Host: http://your.callback.url

Get Access Token

Similar to the previous example except this request includes the oauth_verifier from the earlier response.

Request

POST https://api.pps.io/v1/OAuth/1A/AccessToken HTTP/1.1
Authorization: OAuth oauth_token="4499eddf-2633-415a-b221-90cbf7823dce",
                     oauth_consumer_key="00000000-0000-0000-0000-000000000000",
                     oauth_nonce="vYXqb3Jq",
                     oauth_signature_method="HMAC-SHA1",
                     oauth_signature="%2FUeW4NTL4NV88XOYPAKr3ANGn7A%3D",
                     oauth_version="1.0",
                     oauth_timestamp="1344019030",
                     oauth_verifier=4732f82d3
Accept: application/x-www-form-urlencoded

Response

HTTP/1.1 200 OK
Content-Type: application/x-www-form-urlencoded

oauth_token=d7874463-b31b-4851-be5f-bcea985f895d&oauth_token_secret=19142a9a-f2fb-4c72-8238-80b63645aba5

Api Request Auth

Every request that is sent to the API will be accompanied with the proper auth. This will consist of several parameters added to the querystring.

oauth_token: the previously acquired token
oauth_consumer_key: this is the public key for the consumer account being used for the request
oauth_nonce: a unique string that can only be used once per request
oauth_signature_method: this should be set to: HMAC-SHA1
oauth_signature: the signature is a hash of the entire request and consumer secret
oauth_version: this should be set to: 1.0
oauth_timestamp: the unix timestamp defining when the request was sent

MX™Merchant API

Getting started

REST services

Http Requests

Data Formats

Accept-Encoding:

Example

Http Responses

HTTP Status Codes

Security

Using OAuth

Direct access

Get Request Token

Request

Response

Get Access Token

Request

Response

Api Request Auth

Accessing via applications

Get Request Token

Request

Response

Redirect to Login

Get Access Token

Request

Response

Api Request Auth

» Extras

I want to:

Plans/Products

Industry Solutions

Quicklinks