Getting Started

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:

1. 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.
2. 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.

Shell

curl --location --request GET 'https://api.pairly.me/v1/ping/' \
--header 'X-API-Key: <YOUR_SECRET_KEY>'

PHP

<?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;

JavaScript

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.