Integrating OAuth 1.0a Authentication
Priority Payment Systems API uses OAuth 1.0a as its authentication mechanism. This allows developers to take advantage of several open-source client libraries. Utilizing one of these libraries can reduce time spent with API integration. To demonstrate how to successfully authenticate using OAuth, review the example(s) associated with each workflow of authentication.
OAuth 1.0a Authentication
For more information about OAuth, please visit the OAuth website.
OAuth 1.0a RFC (5489)
In order for an application to make API requests, the user must be authenticated. To properly authenticate a request token must be obtained. This token is then exchanged for an access token. This token is used for all subsequent calls to API resources.
Consumer Keys and secrets are required for OAuth Authentication and API interaction. They are generated by this developer portal during the registration process. These two pieces of information are necessary for every API call. OAuth requests cannot be completed with a username and password.
The following section demonstrates the construction of a properly authenticated API request.
OAuth Parameters
Every request sent to the API will be accompanied with the proper authentication. This is done so by adding a custom header to each request authorization. This header is comprised of several pieces as shown below.
| Parameter | Example Value |
|---|---|
| oauth_callback | path/to/local/script/file.php |
| oauth_consumer_key | testConsumerKey |
| oauth_nonce | 7e80267a3449434009d450b50d6a14c3 |
| oauth_signature | I6kDP8R7lZ7PH2i2SFbpq6bFZqc= |
| oauth_signature_method | HMAC-SHA1 |
| oauth_timestamp | 1380138173684 |
| oauth_token | AUOgOlCHHH5x3iqWKgVF7BSA |
| oauth_version | 1.0 |
Important
Note the ordering of these parameters! They are lexicographically ordered per the OAuth specification. This is a requirement and, if not followed, the request will not be successful.
Authentication
Generate a request token
- Navigate to
POST https://api.mxmerchant.com/checkout/v3/oauth/1a/requesttoken - Select OAuth 1.0 as the authorization type
- Fill in the following fields:
-- Consumer Key
-- Consumer Secret
-- Timestamp (any 10 digits)
-- Nonce (any string)
-- Version: 1.0 - You will receive an OAuth token and secret to use for your access token.
Generate an access token
- Navigate to
POST https://api.mxmerchant.com/checkout/v3/oauth/1a/accesstoken - Repeat steps 2-3 on the directions to generate a request token, except this time fill in the Access Token and Token Secret fields with the response you received when generating a request token
- You will receive the access token once you send the request.
The list below outlines the minimum requirements for a successful API call. The ability to generate these correctly, utilizing the consumer key and consumer secret, are your keys to successfully transacting with the API.
oauth_callback
oauth_consumer_key
oauth_nonce
oauth_signature_method
oauth_timestamp
oauth_version
2-Legged authentication is best supported when an API integration will be used by the merchant or working with only 1 merchant. This method of authentication provides an access token that has a 24-hour lifespan. This can be helpful to assist the client with tracking calls made for a merchant on a daily basis. This can also help bolster security as the merchant will not have an available token that could potentially be used to transact with their information outside of that time frame.
POST https://sandbox.api.mxmerchant.com/checkout/v3/oauth/1a/requesttoken
Authorization: OAuth oauth_callback='scriptToCaptureTokens.php',
oauth_consumer_key='00000000-0000-0000-0000-000000000000',
oauth_nonce='f5eba5867064d4e227f7872e77203716f6b9467a',
oauth_signature_method='HMAC-SHA1',
oauth_signature='Oa260bPDifvy2R2wL%7EeIajYdFY%3D',
oauth_version='1.0',
oauth_timestamp='1361295973'
Accept: application/x-www-form-urlencoded
200 OK
Content-Type: application/x-www-form-urlencoded
oauth_token=AUt1Jymdbt89SyPDK8zlajsA&oauth_token_secret=dea7c4de-f346-403f-962c-181ae8338800&oauth_callback=true
POST https://sandbox.api.mxmerchant.com/checkout/v3/oauth/1a/accessToken
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_token='dea7c4de-f346-403f-962c-181ae8338800'
Accept: application/x-www-form-urlencoded
200 OK
Content-Type: application/x-www-form-urlencoded
oauth_token=AUtweZLmsdIpqS6BuK6S6hrQ&oauth_token_secret=STxHsU3bNDNXvrvCCAdVvEA