# null
Source: https://docs.verdn.com/api-reference/authentication



Verdn uses API keys to authenticate requests. All requests without a valid key will be rejected by the API.

You can create and manage these API keys in the Verdn dashboard. In order to authenticate a request to the Verdn API, pass your key as an [HTTP `Authorization` request header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) prefixed with the `Bearer` keyword.

## Key Modes

When creating an API key, you are given the option to create a **test** key or a **live** key. Testing keys start with `verdn_sk_test` while production keys start with `verdn_sk_live`. You can use any API endpoint with either your test or your live key.

All API JSON response bodies contain an `isLive` property which indicates the live status (i.e., testing or production) of that request.

## Key Levels

There are also two levels of API keys: **unit-level** keys and **team-level** keys.

* A **unit-level** key performs a request authenticated as that unit itself. These keys can be created and managed via the unit's settings dashboard.
* A **team-level** key performs a request on behalf of a unit. These keys can be created and managed via the team's settings dashboard. Moreover, team-level requests require an additional `X-Verdn-Unit-Id` header for unit authentication. This unit ID can be found within that unit's settings dashboard.


# Create Pledge Transaction
Source: https://docs.verdn.com/api-reference/endpoint/create-pledge-transaction

POST /v2/pledge-transaction
Create a new pledge transaction with multiple pledges

## Overview

Creates a new pledge transaction containing one or more pledges. Each pledge represents an impact commitment tied to a specific offering.

## Examples

<CodeGroup>
  ```typescript Minimal Request
  const response = await fetch('https://api.verdn.com/v2/pledge-transaction', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer verdn_sk_test_...',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      reference: "order_123",
      recipient: {
        email: "customer@example.com",
      },
      pledges: [{
        impact: {
          offeringId: "off_123",
          amount: 100,
        },
      }],
    })
  })
  ```

  ```json Minimal Response
  {
    "charge": {
      "amount": "25.00",
      "currencyCode": "USD",
      "paidAt": null
    },
    "createdAt": "2024-01-25T12:00:00Z",
    "id": "ptran_01JH67QPC8R56E4DP7K4PB3MRD",
    "isLive": false,
    "notifications": [],
    "pledges": [
      {
        "detail": {
          "description": null,
          "externalId": null,
          "externalUrl": null,
          "image": null,
          "name": null,
          "nounPlural": null,
          "nounSingular": null
        },
        "id": "p_01JH67QPDG65G48KN5WE2J71Y4",
        "impact": {
          "amount": 100,
          "offeringId": "off_123"
        }
      }
    ],
    "recipient": {
      "email": "customer@example.com",  
      "firstName": null,
      "name": null
    },
    "reference": "order_123",
    "timelineUrl": "https://verdn.com/my/t/abc123xyz789?edit_key=edit_k3y_456",
    "trigger": {
      "date": null,
      "externalUrl": null,
      "phrase": null
    }
  }
  ```

  ```typescript Comprehensive Request
  const response = await fetch('https://api.verdn.com/v2/pledge-transaction', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer verdn_sk_test_...',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      reference: "order_123",
      recipient: {
        email: "customer@example.com",
        name: "John Doe",
        firstName: "John"
      },
      trigger: {
        phrase: "Purchase completed",
        date: "2024-01-25T12:00:00Z",
        externalUrl: "https://example.com/order/123"
      },
      pledges: [{
        impact: {
          offeringId: "off_123",
          amount: 100
        },
        detail: {
          name: "Custom Tree Planting",
          description: "Plant trees in Africa",
          image: "https://example.com/tree.jpg",
          externalUrl: "https://example.com/impact/123",
          externalId: "CUST_123"
        }
      }],
      notifications: ["Email", "Klaviyo"]
    })
  })
  ```

  ```json Comprehensive Response
  {
    "charge": {
      "amount": "25.00",
      "currencyCode": "USD",
      "paidAt": null
    },
    "createdAt": "2024-01-25T12:00:00Z",
    "id": "ptran_01JH67N6WT90W8EW7GF9QN2Y57",
    "isLive": false,
    "notifications": [
      {
        "status": "Pending",
        "type": "Email"
      },
      {
        "status": "Pending",
        "type": "Klaviyo"
      }
    ],
    "pledges": [
      {
        "detail": {
          "description": "Plant trees in Africa",
          "externalId": "CUST_123",
          "externalUrl": "https://example.com/impact/123",
          "image": "https://example.com/tree.jpg",
          "name": "Custom Tree Planting",
          "nounPlural": null,
          "nounSingular": null
        },
        "id": "p_01JH67N6Y8Z56NZK3HC3AATPJF",
        "impact": {
          "amount": 100,
          "offeringId": "off_123"
        },
      }
    ],
    "recipient": {
      "email": "customer@example.com",
      "name": "John Doe",
      "firstName": "John"
    },
    "reference": "order_123",
    "timelineUrl": "https://verdn.com/my/t/abc123xyz789?edit_key=edit_k3y_456",
    "trigger": {
      "date": "2024-01-25T12:00:00Z",
      "externalUrl": "https://example.com/order/123",
      "phrase": "Purchase completed"
    }
  }
  ```
</CodeGroup>

## API Reference


# Get Pledge Transaction by ID
Source: https://docs.verdn.com/api-reference/endpoint/get-pledge-transaction-by-id

GET /v2/pledge-transaction/{id}
Get an existing pledge transaction by its ID

## Overview

Gets an existing pledge transaction by its ID. A single pledge transaction may contain one or more pledges. Each pledge represents an impact commitment tied to a specific offering.

## Examples

<CodeGroup>
  ```typescript Comprehensive Request
  const response = await fetch(
    'https://api.verdn.com/v2/pledge-transaction/ptran_00000000000000000000000000',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer verdn_sk_test_...',
      },
    },
  );
  ```

  ```json Comprehensive Response
  {
    "createdAt": "2024-01-25T12:00:00Z",
    "reference": "order_123",
    "isLive": false,
    "charge": {
      "amount": "25.00",
      "currencyCode": "USD",
      "paidAt": null
    },
    "trigger": {
      "date": null,
      "externalUrl": null,
      "phrase": null
    },
    "pledges": [
      {
        "id": "p_00000000000000000000000000",
        "impact": {
          "amount": 100,
          "offeringId": "off_123"
        },
        "recipient": {
          "email": "customer@example.com",
          "firstName": null,
          "name": null
        },
        "details": [
          {
            "description": null,
            "externalId": null,
            "externalUrl": null,
            "image": null,
            "name": null,
            "nounPlural": null,
            "nounSingular": null
          }
        ]
      }
    ]
  }
  ```
</CodeGroup>

## API Reference


# Introduction
Source: https://docs.verdn.com/api-reference/introduction

Welcome to the Verdn API Reference documentation

## Overview

The Verdn API is designed to be intuitive and developer-friendly while providing powerful functionality for building robust applications. This documentation covers:

* Complete API endpoints
* Request/response formats
* Authentication methods
* Available parameters
* Example usage

## API Conventions

Our API follows RESTful principles and uses:

* JSON for request and response payloads
* Standard HTTP methods (GET, POST, PUT, DELETE)
* Bearer token authentication
* Consistent error handling

Navigate through the sidebar to explore specific API endpoints and features.


# Introduction
Source: https://docs.verdn.com/introduction

Welcome to the Verdn documentation

<Note>
  Please note that this documentation is a work in progress and may be subject to change. If you have any questions about setting up your account, please contact your Verdn account manager.
</Note>

The Verdn API lets you attach impact pledges, such as tree planting or ocean-bound plastic cleanup, to pretty much any transaction you like. We're designing the Verdn API to be as flexible and expressive as possible to support a wide number of use cases.

Currently, the Verdn API supports the following endpoints:

* [Create Pledge Transaction](/api-reference/endpoint/create-pledge-transaction)
* [Get Pledge Transaction by ID](/api-reference/endpoint/get-pledge-transaction-by-id)