Client-side Integration HTTPS

How it works

Client-side integration allows your brand to easily integrate by pasting code blurbs with us processing the payment. It works in the following steps:

First your customer enters your checkout portal to purchase a flight.
Create an Unconfirmed Transaction: Your client sends the client's flight info to Pairly, and Pairly sends back the transaction id, carbon footprint, and cost of offsetting.
Your custom UI or Pairly's UI displays this information to the customer.
Confirm Transaction with Payment Info: The customer confirms payment and finalizes checkout. The payment method and information is sent to us to process separately.

If you have in house carbon footprint models for your business, we accommodate those in our first API call.

Using Your Public Key

In all client-side endpoints, you will need to provide your public key in the request body. This key is visible to the public and is used to identify your organization to Pairly. The key can be found on the integration tab of your brand dashboard.

Create an Unconfirmed Transaction

Use the transaction API to make an initial unconfirmed transaction, estimate carbon footprint, and get offset pricing to display to the customer.

Create a Transaction with Flight Info

Use our models to infer carbon footprint emitted on flights, get back estimations and best carbon offset prices

Request URL
POST https://api.pairly.me/v1/transaction/client/flight/

Request Body

public_key (required, string): your api public key
flight_legs (required, array of Objects): legs of flight as a list
- airline (required, string): flight airline carrier
- flight_number (required, string): flight number
- date (required, integer): date of flight in YYYYMMDD format
- airport_code_type (optional, string): either "iata" or "icao", defaults to "iata"
- origin_airport (required, string): code of origin airport, specify code type using airport_code_type
- destination_airport (required, string): code of destination airport, specify code type using airport_code_type
- cabin_class (optional, string): either "economy" or "premium", defaults to "economy"
currency (optional, string): requested currency code of price, defaults to "USD"
passenger_count (optional, integer > 0) = number of passengers, defaults to 1
email (optional, string): email of client
tag (optional, string): additional information to filter by like name of OTA site, company name, etc.

curl --location --request POST 'https://api.pairly.me/v1/transaction/client/flight/' \
--header 'Content-Type: application/json' \
--data-raw '{
		"public_key": "<YOUR_PUBLIC_KEY>",
    "currency": "USD",
    "flight_legs":[
        {"airline": "American Airlines",
        "flight_number":"AA 123",
        "date":20220710,
        "origin_airport": "BOS",
        "destination_airport":"SFO",
        "airport_code_type": "iata",
        "cabin_class":"economy"
        },
         {"airline": "United Airlines",
        "flight_number":"UA 1234",
        "date":20220731,
        "origin_airport": "SFO",
        "destination_airport":"BOS",
        "airport_code_type": "iata",
        "cabin_class":"economy"
        }
    ]
}'

Response Body

id (string): id of transaction
company (string): id of your company
project (string): id of project for offsetting
activity_description (string): description of flight
activity_type (string): type of footprint, e.g. "flight"
estimate_mass_kilograms (integer): estimated mass of carbon footprint in kg
estimate_price_cents (integer): price of offsetting in cents
currency (string): currency code of price in response
consumer_impact (string): a sentence describing the impact of the carbon footprint for consumers
tag (string): the tag for the transaction

{
    "id": "57a070c4-1a44-40d3-8711-163916222e03",
    "company": "db0d45d8-3cac-49b5-a8d0-f88907f9ddb1",
    "project": "53f9956f-bfd4-47bc-81dd-935259d55d9a",
    "activity_description": "flight booked on Your Brand",
    "activity_type": "flight",
    "estimate_mass_kilograms": 1181,
    "estimate_price_cents": 2613,
    "currency": "USD",
    "consumer_impact": "That’s the same impact as leaving a light bulb on for 6 years."
}

Create a Transaction with Ferry Info

Use our models to infer carbon footprint emitted on ferry, get back estimations and best carbon offset prices

Request URL
POST https://api.pairly.me/v1/transaction/client/ferry/

Request Body

public_key (required, string): your api public key
ferry (required, Object): ferry ship data
- trip_length_hours (required, decimal): the length of the journey in hours
- ship_passenger_capacity (optional, integer): the number of passengers onboard the ferry, defaults to 1000
- ship_vehicle_capacity (optional, integer): the number of passengers onboard the ferry, defaults to 100
- gross_tonnage (optional, integer): the gross tonnage of the ship, defaults to 5000
currency (optional, string): requested currency code of price, defaults to "USD"
passenger_count (optional, integer > 0) = number of passengers, defaults to 1
vehicle_count (optional, integer >= 0) = number of passengers, defaults to 0
email (optional, string): email of client
tag (optional, string): additional information to filter by like name of OTA site, company name, etc.

curl --location --request POST 'https://api.pairly.me/v1/transaction/client/ferry/' \
--header 'X-API-Key: <YOUR_SECRET_KEY>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "public_key": "<YOUR_PUBLIC_KEY>",
    "currency": "USD",
    "ferry": {
        "trip_length_hours": 24,
        "ship_passenger_capacity": 306,
        "ship_vehicle_capacity": 50,
        "gross_tonnage": 3000
    },
    "passenger_count": 2,
    "vehicle_count": 1,
}'

Response Body

id (string): id of transaction
company (string): id of your company
project (string): id of project for offsetting
activity_description (string): description of ferry
activity_type (string): type of footprint, e.g. "ferry"
estimate_mass_kilograms (integer): estimated mass of carbon footprint in kg
estimate_price_cents (integer): price of offsetting in cents
currency (string): currency code of price in response
consumer_impact (string): a sentence describing the impact of the carbon footprint for consumers
tag (string): the tag for the transaction

{
    "id": "0fb5c4b6-ca3c-44fc-a68c-dc5dd12806fc",
    "company": "db0d05d8-3cac-49b5-a8d0-f88907f9ddb1",
    "project": "53f9956f-bfd4-47bc-81dd-935b59d55d9b",
    "activity_description": "ferry booked on Your Brand",
    "activity_type": "ferry",
    "estimate_mass_kilograms": 430,
    "estimate_price_cents": 651,
    "currency": "USD",
    "consumer_impact": "That’s the same impact as leaving a light bulb on for 2 years."
}

Create a Transaction with Cruise Info

Use our models to infer carbon footprint emitted on cruise, get back estimations and best carbon offset prices

Request URL
POST https://api.pairly.me/v1/transaction/client/cruise/

Request Body

public_key (required, string): your api public key
cruise (required, Object): cruise ship data
- trip_length_hours (required, decimal): the length of the journey in hours
- ship_capacity (optional, integer): the number of passengers onboard the cruise, defaults to 1000
- gross_tonnage (optional, integer): the gross tonnage of the ship, defaults to 10000
currency (optional, string): requested currency code of price, defaults to "USD"
passenger_count (optional, integer > 0) = number of passengers, defaults to 1
email (optional, string): email of client
tag (optional, string): additional information to filter by like name of OTA site, company name, etc.

curl --location --request POST 'https://api.pairly.me/v1/transaction/client/cruise/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "public_key": "<YOUR_PUBLIC_KEY>",
    "currency": "USD",
    "cruise": {
        "trip_length_hours": 168,
        "ship_capacity": 306,
        "gross_tonnage": 8539
    }
}'

Response Body

id (string): id of transaction
company (string): id of your company
project (string): id of project for offsetting
activity_description (string): description of flight
activity_type (string): type of footprint, e.g. "flight"
estimate_mass_kilograms (integer): estimated mass of carbon footprint in kg
estimate_price_cents (integer): price of offsetting in cents
currency (string): currency code of price in response
consumer_impact (string): a sentence describing the impact of the carbon footprint for consumers
tag (string): the tag for the transaction

{
    "id": "fa318ef9-e5e9-4546-9671-1bca786deedf",
    "company": "db0d05d8-3cac-49b5-a8d0-f88907f9ddb1",
    "project": "53f9956f-bfd4-47bc-81dd-935b59d55d9b",
    "activity_description": "cruise booked on Your Brand",
    "activity_type": "cruise",
    "estimate_mass_kilograms": 1153,
    "estimate_price_cents": 1759,
    "currency": "USD",
    "consumer_impact": "That’s the same impact as leaving a light bulb on for 6 years."
}

Create a Transaction with Car Info

Use our models to infer carbon footprint emitted on a car, get back estimations and best carbon offset prices

Request URL
POST https://api.pairly.me/v1/transaction/client/car/

Request Body

public_key (required, string): your api public key
car (required, Object): cruise ship data
- make (optional, string): the make of the car
- model (optional, string): the model of the car
distance_m (required, integer > 0) = distance traveled in meters
currency (optional, string): requested currency code of price, defaults to "USD"
email (optional, string): email of client
tag (optional, string): additional information to filter by like name of OTA site, company name, etc.

curl --location --request POST 'https://api.pairly.me/v1/transaction/client/cruise/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "public_key": "<YOUR_PUBLIC_KEY>",
    "currency": "USD",
    "distance_m": 500000,
    "car": {
        "make": "toyota",
        "model": "camry"
    }
}'

Response Body

id (string): id of transaction
company (string): id of your company
project (string): id of project for offsetting
activity_description (string): description of car trip
activity_type (string): type of footprint, e.g. "car"
estimate_mass_kilograms (integer): estimated mass of carbon footprint in kg
estimate_price_cents (integer): price of offsetting in cents
currency (string): currency code of price in response
consumer_impact (string): a sentence describing the impact of the carbon footprint for consumers
tag (string): the tag for the transaction

{
    "id": "65bf9e90-5743-426d-86a1-f0e50595f3ad",
    "company": "db0d05d8-3cac-49b5-a8d0-f88907f9ddb1",
    "project": "53f9956f-bfd4-47bc-81dd-935b59d55d9b",
    "activity_description": "car trip booked on Your Brand",
    "activity_type": "car",
    "estimate_mass_kilograms": 120,
    "estimate_price_cents": 217,
    "currency": "USD",
    "consumer_impact": "That’s the same impact as leaving a light bulb on for 1 year."
}

Create a Transaction with Shipping Info

Use our models to infer carbon footprint emitted on shipping, get back estimations and best carbon offset prices

Request URL
POST https://api.pairly.me/v1/transaction/client/shipping/

Request Body

public_key (required, string): your api public key
transportation_method (required, string): method of transportation, must be one of ['air', 'road', 'sea', 'rail']
mass_g (required, integer > 0): mass shipped in grams
distance_m (required, integer > 0): distance traveled in meters
currency (optional, string): requested currency code of price, defaults to "USD"
email (optional, string): email of client
tag (optional, string): additional information to filter by like name of OTA site, company name, etc.

curl --location --request POST 'https://api.pairly.me/v1/transaction/client/shipping/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "public_key": "<YOUR_PUBLIC_KEY>",
    "currency": "USD",
    "mass_g": 1000000,
    "distance_m": 3000000,
    "transportation_method": "air"
}'

Response Body

id (string): id of transaction
company (string): id of your company
project (string): id of project for offsetting
activity_description (string): description of shipping
activity_type (string): type of footprint, e.g. "shipping"
estimate_mass_kilograms (integer): estimated mass of carbon footprint in kg
estimate_price_cents (integer): price of offsetting in cents
currency (string): currency code of price in response
consumer_impact (string): a sentence describing the impact of the carbon footprint for consumers
tag (string): the tag for the transaction

{
    "id": "4da71249-afec-4e33-bf02-c6e065e7b175",
    "company": "b8c016d2-4d06-4147-a353-2797f8e29846",
    "project": "53f9956f-bfd4-47bc-81dd-935b59d55d9b",
    "activity_description": "shipping booked on GTT",
    "activity_type": "shipping",
    "estimate_mass_kilograms": 2172,
    "estimate_price_cents": 3377,
    "currency": "USD",
    "consumer_impact": "That’s the same impact as leaving a light bulb on for 11 years."
}

Create a Transaction with CO2 Info

For brands that have in house estimators or already calculated a CO2 footprint, use this endpoint to make an unconfirmed transaction and get back the best carbon offset prices

Request URL
POST https://api.pairly.me/v1/transaction/client/

Request Body

public_key (required, string): your api public key
activity_description (required, string): description of activity emitted CO2
activity_type (required, string): type of footprint, e.g. "flight"
estimate_mass_kilograms (required, integer): estimated mass of carbon footprint in kg
currency (optional, string): requested currency code of price, defaults to "USD"
tag (optional, string): additional information to filter by like name of OTA site, company name, etc.

curl --location --request POST 'https://api.pairly.me/v1/transaction/client/' \
--header 'Content-Type: application/json' \
--data-raw '{
		"public_key": "<YOUR_PUBLIC_KEY>",
    "activity_description": "shipping paper towels on amazon",
    "activity_type": "shipping",
    "estimate_mass_kilograms": 122,
    "currency": "USD"
}'

Response Body

id (string): id of transaction
company (string): id of your company
project (string): id of project for offsetting
activity_description (string): description of flight
activity_type (string): type of footprint, e.g. "flight"
estimate_mass_kilograms (integer): estimated mass of carbon footprint in kg
estimate_price_cents (integer): price of offsetting in cents
currency (string): currency code of price in response
consumer_impact (string): a sentence describing the impact of the carbon footprint for consumers
tag (string): the tag for the transaction

{
    "id": "e767b9a4-ab5d-423d-a6d7-9d3cf089f035",
    "company": "db0d05z8-3cac-49b5-a8d0-f88907f9ddb1",
    "project": "53f9956f-bfd4-47bc-81zd-935b59d55d9a",
    "activity_description": "shipping paper towels on amazon",
    "activity_type": "shipping",
    "estimate_mass_kilograms": 122,
    "estimate_price_cents": 270,
    "currency": "USD",
    "consumer_impact": "That’s the same impact as leaving a light bulb on for 1 year."
}

Confirm a Transaction

Use to confirm a customer's action on an unconfirmed transaction.

Patch a Transaction to Confirm

Request URL
PATCH https://api.pairly.me/v1/transaction/client/<transaction_id>/

Request Body

public_key (required, string): your api public key
fraction_offset (required, decimal >= 0): fraction of carbon footprint offset, 1 designates offset entire footprint, 0 designates offset none of it
email (required, string): email of client
card_number (required, integer): credit card number
card_exp_month (required, integer): credit card month
card_exp_year (required, integer): credit card year
card_cvc (optional, integer): credit card cvc

curl --location --request PATCH 'http://localhost:8000/v1/transaction/client/<transaction_id>/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "public_key": "<YOUR_PUBLIC_KEY>",
    "fraction_offset": 0.5,
    "email": "[email protected]",
    "card_number": 4242424242424242,
    "card_exp_month": 8,
    "card_exp_year": 2023,
    "card_cvc": 424
}'

Response Body

id (string): id of transaction
user (string): id of user
company (string): id of your company
project (string): id of project for offsetting
activity_description (string): description of flight
activity_type (string): type of footprint, e.g. "flight"
estimate_mass_kilograms (integer): estimated mass of carbon footprint in kg
estimate_price_cents (integer): price of offsetting in cents
currency (string): currency code of price in response
confirmed (boolean): true
offset_mass_kilograms (integer): kilograms of carbon offset, calculated by multiplying fraction_offset and estimate_mass_kilograms
total_paid_cents (integer): total amount paid / invoiced to customer for offset, calculated by multiplying fraction_offset and estimate_price_cents

{
    "id": "c665235-f262a-4a95-ac40-5429275d88ec",
    "user": "7427c28e-12s3e-49a-8823-a42gc61b242ad",
    "company": "c8692a5f-90ab-4d28-87b8-2fa0cce7323e",
    "activity_description": "flight booked on Your Brand",
    "activity_type": "flight",
    "estimate_mass_kilograms": 1181,
    "estimate_price_cents": 2613,
    "currency": "USD",
    "project": "53f9956f-bfd4-47bc-81dd-935b59d55d9a",
    "confirmed": true,
    "offset_mass_kilograms": 590,
    "total_paid_cents": 1306
}