Introducing our REST API

Getting Started

Learn how to integrate our APIs into your application.

API Basics

You will need to have access to our Sandbox account for you to test the API against. We will provide you with credentials that you can use to make API calls.

The Profituity API gives you access to pretty much all the features you can use on our website and lets you extend them for use in your application.

Endpoints

An endpoint is where an API connects with another application, usually in the form of a specific URL or web address. Endpoints serve as the location for where requests are received and responses to those requests are sent. They're a clear and standardized way for users to work with APIs.

Request Methods

When editing a record, use PUT when you want to replace the entire entity. Use PATCH when you just want to make small changes or updates to the existing entity without replacing it entirely.

API Calls

An API call is the process of making a request, the API retrieving the data you requested, and then getting a response from the API. The only thing you have to do is make the request using one of the above HTTP methods.

Status Codes

With every request you make, you'll receive a status code. This three-digit number tells you whether or not your request was successful. The first number in the code represents the category of the status. If the code starts with a 2, your request was successfully processed. If the code starts with a 4, something went wrong. Status codes allow you to understand the outcome of your request and figure out your next move based on the response.

Requests and Response

Unless otherwise noted, both request body data and response data are formatted as JSON.

Authentication

In this section, we will guide you through the process of authenticating with our API using the OAuth 2.0 Password Credentials Grant. This method allows you to obtain a bearer token which will be required for making authorized API requests.

Overview

The OAuth 2.0 Password Credentials Grant is a method where the user provides their username and password directly to the client application, which then exchanges these credentials for an access token. This access token is then used to make authenticated API requests.

Important: This method should only be used by client applications that are absolutely trusted with the user's credentials, such as the user's device.

Steps to Authenticate:

1. Obtain Access Token

To obtain an access token, you will need to make a POST request to our token endpoint:

Endpoint: https://sandbox.dev.profituity.com/connect/token

HTTP Method: POST

Headers:

• Content-Type: application/x-www-form-urlencoded

Body Parameters:

• grant_type: Set this to password

• username: The provided api username

• password: The provided api password

• client_id: Set this to PlatformNext_App

• scope: Set this to PlatformNext

Example Request:

curl -X POST "https://sandbox.dev.profituity.com/connect/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=password&username=YOUR_USERNAME&password=YOUR_PASSWORD&client_id=YOUR_CLIENT_ID"

2. Extract Bearer Token

Upon successful authentication, you will receive a JSON response containing your access token. The response will look something like this:

{
    "access_token": "YOUR_ACCESS_TOKEN",
    "token_type": "Bearer",
    "expires_in": 3600
}

Extract the access_token value. This is your bearer token.

3. Making Authenticated Requests

With your bearer token in hand, you can now make authenticated requests to our API. Simply include the bearer token in the Authorization header of your requests.

Example:

curl -X GET "https://sandbox.dev.profituity.com/api/merchant-portal/payments/payments" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Important Considerations:

1. Security: Always ensure that your client application communicates over HTTPS to keep user credentials and tokens secure.

2. Expiry: Tokens are not valid indefinitely. Monitor the expires_in field and be prepared to refresh or re-authenticate as necessary.

With these steps, you should be well on your way to securely authenticating with our API. If you have any questions or encounter any issues, please contact our support team.

Errors

Profituity's API is RESTful and as such, uses conventional HTTP response codes to indicate the success or failure of requests.

HTTP Codes