Skip to main content
Skip table of contents

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.


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


This is used to retrieve specific data from the API.


This tells the API you want to add, or post, new data to the server.


This is used to update existing resources on the API.


This is used to modify a resource by providing only information about the changes to make. PATCH requests should be formatted with a Content-Type of application/json-patch+json in compliance with RFC 6902.


This is used to—you guessed it—delete existing data from the server.

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.


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.


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:




  • 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 "" \
     -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.


curl -X GET "" \
     -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.


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

HTTP Codes


Request was successful and intended action was carried out. Note that we will always send a 200 if a charge or verify request was made. Do check the data object to know how the charge went (i.e. successful or failed).


A resource has successfully been created.


Indicates that the server has successfully processed the request, but there's no content to send in the response body


A validation or client side error occurred and the request was not fulfilled.


The request was not authorized. This can be triggered by passing an invalid secret key in the authorization header or the lack of one.


Access to the requested resource was forbidden due to insufficient permissions or authentication.


Request could not be fulfilled as the request resource does not exist.


Request could not be fulfilled due to an error on Profituity’s end. This shouldn't happen so please report as soon as you encounter any instance of this.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.