Authorization

The OnPay API has access limited to approved partners only. To partner, please contact us.

OAuth 2.0

OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for our web application. We will use the domain api.onpay.dev for demonstration purposes. If partnered, you will be provided with a domain to test against.

Steps we will follow:

1. Push User to Authorize OnPay

2. Authorization to access user info

3. Redirect user to partner site with authorization code

4. Trade authorization code for access/refresh token pair

5. Submit requests using access token parameters

6. Exchange refresh tokens for new access/refresh tokens

Authorization Code

Step one allows a user of your application to authorize access to their information in OnPay.
You must create a link to OnPay where your clients use their login information to approve access.
Here's an example of the link:

HTML

<a href=”https://onpay.dev/app/oauth/authorize?client_id=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855&redirect_uri=https%3A%2F%2Fsampleapp.com%2Fcallback&state=foo”>Authorize with OnPay</a>

This authorization code is used to retrieve your access token

Access Token

You will now make a server-side request to OnPay with your authorization code to https://api.onpay.dev/app/oauth/token with the parameters outlined above. Explanation: The client_id, client_secret, and redirect_uri are all used to identify your application. This ensures that there is a valid application requesting this token, and also that it is the same application to which the code was granted. code matches the application to the user and grant_type tells us what type of code is included.
Continuing the example, here's a sample request for an access token:

cURL

curl -X POST -H "Content-Type: Application/x-www-form-urlencoded" https://api.onpay.dev/app/oauth/token -d "client_id=<<your_client_id>>&client_secret=<<your_client_secret>>&redirect_uri=https%3A%2F%2Fsampleapp.com%2Fcallback&code=68ad95d6b19d8y419123c33020e448c39k48752e053cd45s2e66e5bbe5ede0ane3&grant_type=authorization_code"

Upon successful authentication, the response will look like this:

JSON

{ 
    "access_token": "5er0eXAiOiJKV1QiLCJhbG4567OiJIUzI1NiJ9.eithYXQiOjE1MTAxNDQyMjcsImlzcyI6InplbmVmaXRzLXdlYnNlcnZlci1wcm9kdWN0aW9uLTIwMTcuNDQuNy1JbnN0YW5jZTAiLCJuYmYiOjE1MTAxNDQyMjcopejd94cCI6MTUxMDE1MTQ0dcnr87GF0YSI6testbGllbnRfaWQiOjEwLCJ1c2VyX2lkIjoxLCJzdWJfaWQiOm51bGwsImFjY2Vzc190eXBlIjoxLCJjb21wYW55X2lkIjoxMz39Mywic2NvcGVfdG9rZW5fa2V5IjpudWxsfX0.JBhVQZdC8wIYswDYXJLLwrMasGsIiZjiWvRtCNG_i0c",
    "token_type": "bearer",
    "expires_in": "7200",
    "refresh_token": "b1b7a51130ab7632fc16dc560569c2d9a50983982c074b81e663b4caa0475dcc",
    "company_id": 10183,
    "access_type": 1,
    "company_name": "Katie's Wine and Sundries, Inc"
}

The access_token and type "bearer" should be included in the Authorization header record of every call to the API. Failure to include the access_token or using an expired token will result in a 401 response.

Refresh Token

Access tokens are only valid for 2 hours following issuance.
You can exchange your refresh token for a new access token, only once, by making a request very similar to exchanging an authorization code for an access token.
The only difference is that code is set to your refresh token and grant_type is set to "refresh_token".
Here's an example request for a new access token:

cURL

curl -X POST -H "Content-Type: Application/x-www-form-urlencoded" https://api.onpay.dev/app/oauth/token -d "client_id=<<your_client_id>>&client_secret=<<your_client_secret>>&redirect_uri=https%3A%2F%2Fsampleapp.com%2Fcallback&refresh_token=b1b7a51130ab7632fc16dc560569c2d9a50983982c074b81e663b4caa0475dcc&grant_type=refresh_token"

A successful response that includes both a fresh access token, and a new refresh token, will look the same as before:

JSON

{ 
    "access_token": "87pq3XAiOiJKV1QiLCJhbG4567OiJIUzI1NiJ9.eithYXQiOjE1MTAxNDQyMjcsImlzcyI6InplbmVmaXRzLXdlYnNlcnZlci1wcm9kdWN0aW9uLTIwMTcuNDQuNy1JbnN0YW5jZTAiLCJuYmYiOjE1MTAxNDQyMjcopejd94cCI6MTUxMDE1MTQ0dcnr87GF0YSI6testbGllbnRfaWQiOjEwLCJ1c2VyX2lkIjoxLCJzdWJfaWQiOm51toKEnmFjY2Vzc190eXBlIjoxLCJjb21wYW5S4mpL3joxMz39Mywic2NvcGVfdG9rZW5fa2V5IjpudWxsfX0.JBhVQZdC8wIYswDYXJLLwrMasGsIiZjiWvRtCNG_a8c",
    "token_type": "bearer",
    "expires_in": "7200",
    "refresh_token": "86ad26e994e2a7480d679f2f6452209fefa701bf719a1446ad2cc5254f715d02",
    "company_id": 10183,
    "access_type": 1,
    "company_name": "Katie's Wine and Sundries, Inc"
}