The Pairly API README
Overview
Welcome to the Pairly API guide! Use this guide to query our offset marketplace, place orders, and estimate carbon footprints. Contact [email protected] to request an API Key and get started.
To integrate with Pairly, two API calls are sent:
- First, your service creates a transaction on our platform. This allows you to estimate your client's footprint and get a quote for the best prices for offsets.
- Then, your service confirms a transaction on our platform. This lets us know if the client decided to offset their footprint.
We built out two types of integrations---one on the client side and one on the server side. The client side integration is done entirely on your frontend, where we collect payment info, the actual payment, and payment confirmation directly from the browser. The server side integration is done entirely on your backend. For this integration, your business collects payments from the client, and Pairly invoices you every billing period for the amount due.
If you need additional custom estimators or would like support integrating, please reach out to [email protected]!
Root URL
Pairly's API root URL is https://api.pairly.me/v1/
. Once you have your API keys from Pairly's dashboard, make your first request using our ping endpoint.
curl --location --request GET 'https://api.pairly.me/v1/ping/' \
--header 'X-API-Key: <YOUR_SECRET_KEY>'
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api.pairly.me/v1/ping/',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'X-API-Key: <YOUR_SECRET_KEY>'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
var request = require('request');
var options = {
'method': 'GET',
'url': 'https://api.pairly.me/v1/ping/',
'headers': {
'X-API-Key': '<YOUR_SECRET_KEY>'
}
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
Authorization
On your Pairly Brands Dashboard, you can find your api keys in the integration section. Some endpoints require <YOUR_SECRET_KEY>
while others require <YOUR_PUBLIC_KEY>
. Secret keys will always be passed through headers, while public keys will be passed as url params. Using keys in test mode will create transactions in a separate test database and will not bill you.
The API secret key needs to be in a header of the form: X-API-Key: <YOUR_SECRET_KEY>
.
Errors
The Pairly API returns standard HTTP error codes.
200 | OK: Your request was successful |
400 | Bad Request -- Your request could not be parsed or is invalid. |
401 | Unauthorized -- Your API key is missing or incorrect. |
403 | Forbidden -- The resource requested is hidden for administrators only or doesn't exist.OK: Your request was successful |
404 | Not Found -- The resource requested does no exist. |
429 | Too Many Requests -- Do some pushups and then try again. |
500 | Internal Server Error -- We had a problem with our server. Try again later or contact support. |
502 | Bad Gateway -- Your request timed out (exceeded 10 seconds). |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |