Learn how to integrate our APIs into your application.
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.
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
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.
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.
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:
grant_type: Set this to
username: The provided api username
password: The provided api password
client_id: Set this to
scope: Set this to
curl -X POST "https://sandbox.dev.profituity.com/connect/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
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 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 "https://sandbox.dev.profituity.com/api/merchant-portal/payments/payments" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Security: Always ensure that your client application communicates over HTTPS to keep user credentials and tokens secure.
Expiry: Tokens are not valid indefinitely. Monitor the
expires_infield 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.
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.