📖API reference

General information

The TGB Public API is a RESTful API. Our API has resource-oriented URLs, it accepts JSON-encoded data and returns JSON-encoded data. We use standard HTTP response codes to communicate status of the request to the consumers and standard verbs to manipulate the resources.

The API is designed to be integrated with one of the consumer's back-end services. It won't work with browsers since our CORS policy doesn't allow this and it would require consumers to store API login and password on the browser side.

It's recommended to use Staging environment during the development to build your application. Donations made to the Staging environment use real crypto networks so you can test everything end-to-end.

Base API URL

Staging environment: https://public-api.tgb-preprod.com Production environment: https://public-api.tgbwidget.com

Passing Access Token

API uses Bearer authentication (also called “token authentication”) therefore Access Token should be passed in a Authorization Header with a Bearer prefix, example:

Authorization: Bearer YOUR_ACCESS_TOKEN

Example:

if your Access Token is abcdef123456 then token should be passed like this

curl --request GET \
  --url https://public-api.tgbwidget.com/v1/organization/99 \
  --header 'Authorization: Bearer abcdef123456'

Responses format

All responses from the API will be returned in JSON format.

Successful request’s response format:

{
  "data": { 
    "someProperty": "some data"
  },
  "requestId": "uuid for tracing purposes"
}

To simplify investigations for any sort of errors please send requestId to the TheGivingBlock team

Whenever error happens, it will be returned in a following format:

{
  "data": {
    "errorMessage": string;
    "errorType": string;
    "meta": {
      "errorCode": string;
    }
  },
  "requestId": string;
}

Description of every property:

Property	Always present?	Description
errorMessage	Yes	Human readable description of error. Do not use it for programmatic error handling because these messages are likely to be changed over time
errorType	Yes	Human readable description of error. Do not use it for programmatic error handling because these messages are likely to be changed over time
meta	Yes	Type of error, for example: err.authentication, err.forbidden, err.validation, etc.
meta.errorCode	No	In some cases this error code will be present in the response. This property along with errorType can be used for programmatic error handling. See Error Codes section of documentation for list of available errors

Example of Error response when validation error happened:

{
  "data": {
    "errorMessage": "Request body validation failed",
    "errorType": "err.validation",
    "meta": {
      "errorCode": "INVALID_REQUEST"
      "validationErrorMessage": "\"login\" is required",
      "failedAttributes": [
        {
          "attributeName": "login",
          "message": "\"login\" is required",
          "path": [
            "login"
          ]
        }
      ]
    }
  },
  "requestId": "325a3fa0-d3b1-433c-b36a-573368cdbe2e"
}

Here is another example of Error response when you pass expired Access Token

{
  "data": {
    "errorMessage": "Auth token is invalid. Please refresh tokens or log in again",
    "errorType": "err.forbidden",
    "meta": {
      "errorCode": "INVALID_JWT_TOKEN"
    }
  },
  "requestId": "0a2420df2-544c-47fd-a501-a69ebbdf1493"
}

Endpoints documentation

Login

POST https://public-api.tgbwidget.com/v1/login

This endpoint should be used to obtain pair of Access and Refresh Tokens No Access Token required

Request Body

Name	Type	Description
login*	string	Your api user login
password*	string	Your api user password

200

{
  "data": {
    "accessToken": "your-access-token-returned-here",
    "refreshToken": "your-refresh-token-returned-here"
  },
  "requestId": "some uuid"
}

Examples:

cURL

curl --request POST \
  --url https://public-api.tgbwidget.com/v1/login \
  --header 'Content-Type: application/json' \
  --data '{
	"login": "your-login",
	"password": "your-password"
}'

Node.js

import axios from "axios";

const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/login',
    headers: {'Content-Type': 'application/json'},
    data: {
        login: 'your login',
        password: 'your password'
    }
};

axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});

Possible Error Codes:

• INVALID_REQUEST in case if invalid POST body passed

• INVALID_LOGIN_CREDENTIALS if incorrect pair of login/password passed

• INACTIVE_USER if user is restricted to access the API

RefreshTokens

POST https://public-api.tgbwidget.com/v1/refresh-tokens

This endpoint should be used to refresh a pair of Access and Refresh Tokens to avoid repetitive Login requests. No Access Token required

Request Body

Name	Type	Description
refreshToken*	string	Your refresh token

200

{
  "data": {
    "accessToken": "your-access-token-returned-here",
    "refreshToken": "your-refresh-token-returned-here"
  },
  "requestId": "some uuid"
}

Examples:

cURL

curl --request POST \
  --url https://public-api.tgbwidget.com/v1/refresh-tokens \
  --header 'Content-Type: application/json' \
  --data '{
	"refreshToken": "your-refresh-token-value"
}'

Node.js

import axios from "axios";

const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/refresh-tokens',
    headers: {'Content-Type': 'application/json'},
    data: {
        refreshToken: 'your refresh token'
    }
};

axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});

Possible Error Codes:

• INVALID_REQUEST in case if invalid POST body passed

• INVALID_JWT_TOKEN if Refresh Token not found or revoked

• INACTIVE_USER if user is restricted to access the API

GetOrganizationsList

GET https://public-api.tgbwidget.com/v1/organizations/list

This endpoint should be used to retrieve a list of available nonprofits. This list is used to display a list of Organizations so users can choose one of them for donation. Access Token required

Query Parameters

Name	Type	Description
sortColumn	String	Specifies a column on which to sort the organizations list.
sortOrder	String	Specifies that the values in the specified column should be sorted in ascending or descending order. Descending is the default sort order.

200 Array of Organizations

{
  "data": {
    "organizations": [
      {
        "id": 99, // ID of organization
        "name": "TGB Preproduction",
        "logo": "https://static.tgb-preprod.com/organization_logo/04fdb90f-10e9-4fe7-a6f8-f0c6689735b1.jpeg",
        "country": "USA",
        "allowsAnon": true, // Are anonymous Donations allowed
        "nonprofitTaxID": "01-0000000",
        "areNotesEnabled": true, // Are Donation notes allowed
        "isReceiptEnabled": true, // Indicates whether Donation
                                  // receipt email sending is forbidden by organization
        "createdAt": "2022-05-09T12:02:29.603Z",
        "state": "AL",
        "city": "Washington",
        "postcode": "20036",
        "nonprofitAddress1": "1712 N St NW",
        "nonprofitAddress2": "Suite 101",
        "uuid": "b3d94d59-48a5-4bc1-acee-f4e88148357d",
        "areFiatDonationsEnabled": true,
        "areCryptoDonationsEnabled": true
      },
    ]    
  },
  "requestId": "some uuid"
}

Examples:

cURL

curl --request GET \
  --url https://public-api.tgbwidget.com/v1/organizations/list \
  --header 'Authorization: Bearer your-access-token'

Node.js

import axios from "axios";

const options = {
    method: 'GET',
    url: 'https://public-api.tgbwidget.com/v1/organizations/list',
    headers: {
        Authorization: 'Bearer {your-access-token}'
    }
};

axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});

Possible Error Codes:

• INVALID_REQUEST in case if invalid POST body passed

• INVALID_JWT_TOKEN if Access Token is invalid (for example signature is invalid)

• EXPIRED_JWT_TOKEN if Access Token is expired. Please refresh tokens

• UNAUTHORIZED_USER if no Access Token is passed or endpoint usage is not allowed to your user

• INACTIVE_USER if user is restricted to access the API

GetOrganizationById

GET https://public-api.tgbwidget.com/v1/organization/:id

This endpoint should be used to retrieve nonprofit by id. This response is used to display details on the organization page. Access Token required

Path Parameters

Name	Type	Description
id	number	Organization id

200 Detailed information regarding single Organization

{
  "data": {
    "organization": {
      "id": 99,
      "name": "TGB Preproduction",
      "logo": "https://static.tgb-preprod.com/organization_logo/04fdb90f-10e9-4fe7-a6f8-f0c6689735b1.jpeg",
      "country": "USA",
      "allowsAnon": true,
      "nonprofitTaxID": "01-0000000",
      "areNotesEnabled": true,
      "isReceiptEnabled": true,
      "createdAt": "2022-05-09T12:02:29.603Z",
      "state": "AL",
      "city": "Washington",
      "postcode": "20036",
      "nonprofitAddress1": "1712 N St NW",
      "nonprofitAddress2": "Suite 101",
      "uuid": "b3d94d59-48a5-4bc1-acee-f4e88148357d",
      "areFiatDonationsEnabled": true,
      "areCryptoDonationsEnabled": true,
      "categories": [
        {
          "id": 4,
          "name": "Animals"
        }
      ],
      "widgetCode": {
          "iframe": "<iframe frameborder=\"0\" width=\"430\" height=\"820\" scrolling=\"no\" src=\"https://tgbwidget.com?charityUuid=xxx-xxx-xxx&display=embedded&version=2&apiUserId=1\"></iframe>",
	  "script": "<script id=\"tgb-widget-script\">  !function t(e,i,n,g,x,r,s,d,a,y,w,c,o){var p=\"tgbWidgetOptions\";e[p]?(e[p]=e[p].length?e[p]:[e[p]],  e[p].push({id:r,apiUserId:x,domain:g,buttonId:d,scriptId:s,uiVersion:a,donationFlow:y,fundraiserId:w}))  :e[p]={id:r,domain:g,buttonId:d,scriptId:s,uiVersion:a,donationFlow:y,fundraiserId:w},  (c=i.createElement(n)).src=[g,\"/widget/script.js\"].join(\"\"),c.async=1,  (o=i.getElementById(s)).parentNode.insertBefore(c,o)  }(window,document,\"script\",\"https://tgbwidget.com\",\"1\",  \"1\",\"tgb-widget-script\",\"tgb-widget-button\",   \"2\", \"\", \"\");</script>",
	  "popup": "<button id=\"tgb-widget-button\" style=\"font-family: 'Noto Sans', 'Roboto','Helvetica','Arial',sans-serif;border-radius: 5px;background-color: #FCD42B;border: 1px solid #FCD42B;color: #291B4F;font-size: 16px;font-weight: 500;padding: 13px 30px 14px;    \">Donate Now</button><script id=\"tgb-widget-script\">  !function t(e,i,n,g,x,r,s,d,a,y,w,c,o){var p=\"tgbWidgetOptions\";e[p]?(e[p]=e[p].length?e[p]:[e[p]],  e[p].push({id:r,apiUserId:x,domain:g,buttonId:d,scriptId:s,uiVersion:a,donationFlow:y,fundraiserId:w}))  :e[p]={id:r,domain:g,buttonId:d,scriptId:s,uiVersion:a,donationFlow:y,fundraiserId:w},  (c=i.createElement(n)).src=[g,\"/widget/script.js\"].join(\"\"),c.async=1,  (o=i.getElementById(s)).parentNode.insertBefore(c,o)  }(window,document,\"script\",\"https://tgbwidget.com\",\"1\",  \"1\",\"tgb-widget-script\",\"tgb-widget-button\",   \"2\", \"\", \"\");</script>"
      },
      "websiteBlocks": {
        "url": {
          "settings": {
            "isEnabled": true
          },
          "value": "https://www.nonprofit.example.org/"
        },
        "donationUrl": {
          "settings": {
            "isEnabled": true
          },
          "value": "https://www.nonprofit.example.org/bitcoin"
        },
        "socialTitle": {
          "settings": {
            "isEnabled": true
          },
          "value": "Donate Bitcoin to Save The Children | The Giving Block"
        },
        "socialDescription": {
          "settings": {
            "isEnabled": true
          },
          "value": "Donate Bitcoin to nonprofits like Save The Children who accept cryptocurrency, crypto donations are tax deductible"
        },
        "taxType": {
          "settings": {
            "isEnabled": false
          },
          "value": null
        },
        "is501C3": {
          "settings": {
            "isEnabled": true
          },
          "value": "false"
        },
        "missionStatement": {
          "settings": {
            "isEnabled": true
          },
          "value": "This is a test mission."
        },
        "whyDonate": {
          "settings": {
            "isEnabled": false
          },
          "value": null
        },
        "youtubeUrl": {
          "settings": {
            "isEnabled": false
          },
          "value": null
        },
        "twitterHandle": {
          "settings": {
            "isEnabled": false
          },
          "value": null
        },
        "slug": {
          "settings": {
            "isEnabled": true
          },
          "value": "preprod"
        },
        "tags": {
          "value": null
        },
        "pageTitle": {
          "settings": {
            "isEnabled": true
          },
          "value": "TGB Preproduction"
        },
        "isLeaderboardEnabled": {
          "settings": {
            "isEnabled": true
          },
          "value": "false"
        }
      },
      "fundsDesignations": [
        {
          "value": "Cat Food",
          "uuid": "4bd8b172-6167-4cbe-9936-ea833471b898"
        },
        {
          "value": "dogs food",
          "uuid": "b6fae9bc-0704-4460-97cc-3139159bac26"
        }
      ],
      "shift4ApiVersion": 2,
      "shift4PublicKey": "public-key-for-card-donations"
    }
  },
  "requestId": "24d83fe9-1baa-4076-a2ca-8da9130a359d"
}

Examples:

cURL

curl --request GET \
  --url https://public-api.tgbwidget.com/v1/organization/1189133200 \
  --header 'Authorization: Bearer your-access-token'

Node.js

import axios from "axios";

const options = {
    method: 'GET',
    url: 'https://public-api.tgbwidget.com/v1/organization/1189133201',
    headers: {
        Authorization: 'Bearer {your-access-token}'
    }
};

axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});

Possible Error Codes:

• INVALID_REQUEST in case if invalid POST body passed

• INVALID_JWT_TOKEN if Access Token is invalid (for example signature is invalid)

• EXPIRED_JWT_TOKEN if Access Token is expired. Please refresh tokens

• UNAUTHORIZED_USER if no Access Token is passed or endpoint usage is not allowed to your user

• INACTIVE_USER if user is restricted to access the API

GetWidgetSnippet

POST https://public-api.tgbwidget.com/v1/organization/:id/widget-snippet

If no config is passed, default values are used.

We provide 3 options to inject the widget:

1. IFrame - The widget will be embedded in the iframe. Not recommended

2. Embedded - Provided script will generate code to embed the widget

3. Popup - The widget will be shown as a popup by clickling on trigger button

Request Body

Name	Type	Description
uiVersion	1 or 2	2 - is the latest ui version and used by default
scriptId		If you would like to use more then 1 widget at the same page, they must have different scriptId
button.id	String	If you would like to use more then 1 popup widget at the same page, trigger buttons must have different id
button.text	String	Text for the trigger button. Donate Now by default
button.style	String	Inline CSS style for trigger button. For default apperance check screenshot below

200: OK

{
	"data": {
		"iframe": "<iframe frameborder=\"0\" width=\"430\" height=\"820\" scrolling=\"no\" src=\"https://tgbwidget.com?charityId=1&display=embedded&version=2&apiUserUuid=xxxx-xxxx-xxx\"></iframe>",
		"script": "<script id=\"tgb-widget-script\">  !function t(e,i,n,g,x,r,s,d,a,y,w,c,o){var p=\"tgbWidgetOptions\";e[p]?(e[p]=e[p].length?e[p]:[e[p]],  e[p].push({id:r,apiUserId:x,domain:g,buttonId:d,scriptId:s,uiVersion:a,donationFlow:y,fundraiserId:w}))  :e[p]={id:r,domain:g,buttonId:d,scriptId:s,uiVersion:a,donationFlow:y,fundraiserId:w},  (c=i.createElement(n)).src=[g,\"/widget/script.js\"].join(\"\"),c.async=1,  (o=i.getElementById(s)).parentNode.insertBefore(c,o)  }(window,document,\"script\",\"https://tgbwidget.com\",\"1\",  \"1\",\"tgb-widget-script\",\"tgb-widget-button\",   \"2\", \"\", \"\");</script>",
		"popup": "<button id=\"tgb-widget-button\" style=\"\">Give me your money</button><script id=\"tgb-widget-script\">  !function t(e,i,n,g,x,r,s,d,a,y,w,c,o){var p=\"tgbWidgetOptions\";e[p]?(e[p]=e[p].length?e[p]:[e[p]],  e[p].push({id:r,apiUserId:x,domain:g,buttonId:d,scriptId:s,uiVersion:a,donationFlow:y,fundraiserId:w}))  :e[p]={id:r,domain:g,buttonId:d,scriptId:s,uiVersion:a,donationFlow:y,fundraiserId:w},  (c=i.createElement(n)).src=[g,\"/widget/script.js\"].join(\"\"),c.async=1,  (o=i.getElementById(s)).parentNode.insertBefore(c,o)  }(window,document,\"script\",\"https://tgbwidget.com\",\"1\",  \"1\",\"tgb-widget-script\",\"tgb-widget-button\",   \"2\", \"\", \"\");</script>"
	},
	"requestId": "8ac257ca-861f-4218-9f0d-61f1321bdccb"
}

Appearance examples

Both screenshots represent an embedded appearance. You need to use script the endpoint response in order to display the embedded widget. The first screen shows the old widget UI(uiVersion=2). The second screen shows the latest UI (uiVersion=2).

Example how what the trigger button looks like. depending on the passed uiVersion, a popup will contain either an old or a new UI.

Request examples

cURL

curl --request POST \
  --url https://public-api.tgbwidget.com/v1/organization/1/widget-snippet \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json' \
  --data '{
	"uiVersion": 2,
	"button": {"text": "Support US"}
}'

Node.js

import axios from "axios";

const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/organization/99/widget-snippet',
    headers: {
        Authorization: 'Bearer {your-access-token}'
    },
    data: {
        uiVersion: 2,
        button: { text: "Support Us" }
    }
};

axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});

• INVALID_REQUEST in case if invalid POST body passed

• INVALID_JWT_TOKEN if Access Token is invalid (for example signature is invalid)

• EXPIRED_JWT_TOKEN if Access Token is expired. Please refresh tokens

• UNAUTHORIZED_USER if no Access Token is passed or endpoint usage is not allowed to your user

• INACTIVE_USER if user is restricted to access the API

GetWidgetUrl

POST https://public-api.tgbwidget.com/v1/organization/:id/widget-url

Request Body

Name	Type	Description
uiVersion	1 or 2	2 - is the latest ui version and used by default
externalId		This parameter will help match partner donation ID with donations in TGB storage
defaultAmount	String	This is the default fiat value on donation form that donors will see
returnUrl	String	Donation form will be redirected to this value after donation is received

200: OK

{
  "data": {
    "url": "https://tgb-dev-k8s.com/?charityID=1&version=2&donationDataId=ad4c8d54-3264-45b6-9388-2ff72376e45a"
  },
  "requestId": "fea2b439-d89d-4598-b9d9-99546bb47fd4"
}

Provides endpoint by which partners are able to get URL to Donation Form where donor will finalize payment/donation.

Request examples:

cURL

curl --request POST \
  --url https://public-api.tgbwidget.com/v1/organization/1/widget-url \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json' \
  --data '{
	"externalId": "some-external-id",
	"defaultAmount": 500,
	"uiVersion": 2,
	"returnUrl": "https://thegivingblock.com/"
}'

Node.js

import axios from "axios";

const options = {
  method: 'POST',
  url: 'https://public-api.tgb-dev-k8s.com/v1/organization/1/widget-url',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer your-access-token'
  },
  data: {
    uiVersion: 2,
    externalId: 'some-external-id',
    defaultAmount: 500,
    returnUrl: 'some-return-url'
  }
};

axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});

Get Crypto Rate

GET https://public-api.tgbwidget.com/v1/crypto-to-usd-rate?currency={currencyCode}

This endpoint should be used to retrieve cryptocurrency to USD rate.

Access Token required

Query Parameters

Name	Type	Description
currency*	String	Cryptocurrency code (btc, eth, doge etc.)

200: OK

{
  "data": {
    "rate": 48360.59
  },
  "requestId": "d12c8a86-7719-443e-bf77-5e297859e3ff"
}

Examples:

cURL

curl --request GET \
  --url 'https://public-api.tgbwidget.com/v1/crypto-to-usd-rate?currency=ETH' \
  --header 'Authorization: Bearer your-access-token'

Node.js

import axios from "axios";

const options = {
    method: 'GET',
    url: 'https://public-api.tgbwidget.com/v1/crypto-to-usd-rate',
    params: {currency: 'ETH'},
    headers: {
        Authorization: 'Bearer {your-access-token}'
    }
};

axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});

Possible Error Codes:

• INVALID_REQUEST in case if invalid POST body passed

• INVALID_JWT_TOKEN if Access Token is invalid (for example signature is invalid)

• EXPIRED_JWT_TOKEN if Access Token is expired. Please refresh tokens

• UNAUTHORIZED_USER if no Access Token is passed or endpoint usage is not allowed to your user

• INACTIVE_USER if user is restricted to access the API

CreateDepositAddress

POST https://public-api.tgbwidget.com/v1/deposit-address

This endpoint is used to create a crypto Deposit Address for Donation. Access Token required

Request Body

Name	Type	Description
organizationId	number	12345678
isAnonymous	boolean	false
pledgeCurrency	string	"BTC"
pledgeAmount	string	"0.0001"
firstName	string	"John"
lastName	string	"Doe"
receiptEmail	string	"[e-mail]"
addressLine1	string	"My street 1"
addressLine2	string	"apt 2"
country	string	"US"
state	string	"NY"
city	string	"New York"
zipcode	string	"4422211"

200 Deposit address is returned along with QR code

{
  "data": {
    "depositAddress": "some crypto wallet address",
    "pledgeId": "fe497575-cf4b-4eec-b7e3-b6ce75298bdb",
    "qrCode": "{base64 encoded image}"
  },
  "requestId": "some uuid"
}

receiptEmail is optional. The Giving Block won't send receipt email If organization has isReceiptEnabled as false (available in response from GetOrganizationsList method) or your API account has default setting that tells us to not send any receipt emails for transactions created through the API. In case if you need The Giving Block to send receipt emails - ask us to set up your API account accordingly and make sure you send receiptEmail in CreateDepositAddress request.

If donation is not anonymous - fields firstName, lastName, addressLine1, addressLine2, country, state, city, zipcode are required.

Returned pledgeId field is an unique identifier for the donation. It will be sent along with transactions' notifications as pledgeId to link events to donations.

Important note: If XRP is passed as pledgeCurrency, the depositTag will be returned in the response. This property should be shown to clients - if the depositTag is not specified in the address, we wouldn't be able to correctly process this transaction. The example how it should be presented can be found in Stock Donation Flow page.

Some notes on qrCode property: it is base64 encoded QR code image that represents depositAddress . That being said, when you decode that QR code, you'll get a text that is in depositAddress field. This image can be used to display on your donation page to give to the donor an easy way to enter depositAddress to make a donation.

Examples:

cURL

curl --request POST \
  --url https://public-api.tgbwidget.com/v1/deposit-address \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json' \
  --data '{
	"organizationId": 99,
	"isAnonymous": true,
	"pledgeCurrency": "btc",
	"pledgeAmount": "0.000001"
}'

Node.js

import axios from "axios";

const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/deposit-address',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer {your-access-token}'
    },
    data: {
        organizationId: 1,
        isAnonymous: false,
        pledgeCurrency: 'ETH',
        pledgeAmount: '0.1',
        receiptEmail: '[e-mail]',
        firstName: 'Test',
        lastName: 'User',
        addressLine1: 'Street 4321',
        addressLine2: 'Apt 55',
        country: 'US',
        state: 'NY',
        city: 'New York',
        zipcode: '442452'
    }
};

axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});

Possible Error Codes:

• INVALID_REQUEST in case if invalid POST body passed

• INVALID_JWT_TOKEN if Access Token is invalid (for example signature is invalid)

• EXPIRED_JWT_TOKEN if Access Token is expired. Please refresh tokens

• UNAUTHORIZED_USER if no Access Token is passed or endpoint usage is not allowed to your user

• INACTIVE_USER if user is restricted to access the API

List Currencies

POST https://public-api.tgbwidget.com/v1/currencies/list

Scope: authorized, bearer token is required Lists available currencies

Request Body

Name	Type	Description
filters	object	filters object
filters.name	string	finds all the currencies, which have this string in their name
filters.code	string	filters by currency official code (BTC, ETH etc)
pagination	object	Pagination object
pagination.page	number	page to list in response
pagination.itemsPerPage	number	amount of items listed on a page

200: OK Paginated response

{
  "data": {
    "data": [
      {
        "id": "06760767-8b4b-4ba9-a764-9d88f96aa3d3",
        "name": "Polygon",
        "code": "MATIC",
        "imageUrl": "https://url-to-image.png",
        "minDonation": 0.1,
        "network": "polygon"
      },
      {
        "id": "4fc399be-7ed7-41d8-9987-31d1a4dfc4d8",
        "name": "Ethereum",
        "code": "ETH",
        "imageUrl": "https://static.tgb-preprod.com/currency_images%2Fc8fcd5a1-659f-4154-958e-f8eadeb6f4bb.png",
        "isErc20": false,
        "network": "ethereum",
        "minDonation": 0.001
      },
      {
        "id": "1185632f-4b01-4c26-9743-d725ebf9acbb",
        "name": "Bitcoin",
        "code": "BTC",
        "imageUrl": "https://static.tgb-preprod.com/currency_images%2Ff953733b-12dc-4f01-842d-afdf3a227e0e.png",
        "isErc20": false,
        "network": "bitcoin",
        "minDonation": 0.00001
      },
      {
        "id": "099fcf45-10d4-4f51-a8a7-b0402a35425a",
        "name": "UMA",
        "code": "UMA",
        "imageUrl": "https://url-to-image.png",
        "minDonation": 0.01,
        "network": "ethereum"
      }
    ],
    "pagination": {
      "page": 1,
      "itemsPerPage": 4,
      "count": 26
    }
  },
  "requestId": "7622bda4-4d28-47f7-bb55-368e3d561484"
}

200: OK Non-paginated response

{
  "data": [
    {
      "id": "1185632f-4b01-4c26-9743-d725ebf9acbb",
      "name": "Bitcoin",
      "code": "BTC",
      "imageUrl": "https://static.tgb-preprod.com/currency_images%2Ff953733b-12dc-4f01-842d-afdf3a227e0e.png",
      "isErc20": false,
      "network": "bitcoin",
      "minDonation": 0.00001
    },
    {
      "id": "11a3b5c8-67cd-4db8-937d-f8b5fdedb9c1",
      "name": "USD Coin",
      "code": "USDC",
      "imageUrl": "https://static.tgb-preprod.com/currency_images%2Fbb6ccbe7-6da3-4f72-ad55-7a46d1efa4ea.png",
      "isErc20": true,
      "network": "ethereum",
      "minDonation": 0.1
    },
    {
      "id": "20f0ecc7-4b3e-4133-a440-0a4cb1e40015",
      "name": "Dogecoin",
      "code": "DOGE",
      "imageUrl": "https://static.tgb-preprod.com/currency_images%2F8658d28d-140c-4468-963f-58d35af9af45.png",
      "isErc20": false,
      "network": "dogecoin",
      "minDonation": 0.1
    },
    {
      "id": "4fc399be-7ed7-41d8-9987-31d1a4dfc4d8",
      "name": "Ethereum",
      "code": "ETH",
      "imageUrl": "https://static.tgb-preprod.com/currency_images%2Fc8fcd5a1-659f-4154-958e-f8eadeb6f4bb.png",
      "isErc20": false,
      "network": "ethereum",
      "minDonation": 0.001
    },
    {
      "id": "06760767-8b4b-4ba9-a764-9d88f96aa3d3",
      "name": "Polygon",
      "code": "MATIC",
      "imageUrl": "https://url-to-image.png",
      "minDonation": 0.1,
      "network": "polygon"
    }
  ],
  "requestId": "eafedeec-776f-4bbd-9cbd-f25489c01e94"
}

Examples

cURL

curl --request POST \
  --url https://public-api.tgbwidget.com/v1/currencies/list \
  --header 'Authorization: Bearer your-access-token'

Node.js

import axios from "axios";

const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/currencies/list',
    headers: {
        Authorization: 'Bearer {your-access-token}'
    }
};

axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});

Possible Error Codes:

• INVALID_REQUEST in case if invalid POST body passed

• INVALID_JWT_TOKEN if Access Token is invalid (for example signature is invalid)

• EXPIRED_JWT_TOKEN if Access Token is expired. Please refresh tokens

• UNAUTHORIZED_USER if no Access Token is passed or endpoint usage is not allowed to your user

• INACTIVE_USER if user is restricted to access the API​

GetTransactionList

POST https://public-api.tgbwidget.com/v1/transaction/list

This list is used to display a list of Transactions so users can see all transaction information. Please note that this endpoint is not accessible by default. To be able to access it, please contact The Giving Block Integrations Team Access Token required

Request Body

Name	Type	Description
pagination.page*	number	Current page
pagination.itemsPerPage*	number	Maximum items per one page
filters.date.from	number	Timestamp in milliseconds, only transactions that were created after that point will be returned
filters.date.to	number	Timestamp in milliseconds, only transactions that were created after that point will be returned
filters.date.externalId	string	Only transactions with externalId assigned to them will be listed

200

{
  "data": {
    "transactions": {
      "data": [
        {
          "transactionDate": "2023-03-21T08:57:33Z",
          "currency": "SOL",
          "amount": 0.069,
          "grossAmount": 1.49,
          "totalFees": 0.070862672,
          "netAmount": 1.428783328,
          "txId": "3yNGgzMmrxnFYUcJ2Dxo3QUn4dyiFmGXdxeZzVZuPXvtU4QFQbimDZrDq9iVUbj4neHxnZKymAEhMAXSa68PxPkM",
          "destination": "CJYVKdU4SFCkjk3BiCrvaKX9Nvb9VUMvXbN125ASRrga",
          "origin": null,
          "anon": true,
          "donationNotes": "Hope that will help people to survive",
          "fundsDesignation": null,
          "organizationId": 1189132264,
          "organizationName": "The Best Organization Ever",
          "donorName": null,
          "donorFirstName": null,
          "donorLastName": null,
          "donorEmail": null,
          "donorAddress": null,
          "city": null,
          "zipcode": null,
          "state": null,
          "country": null,
          "id": "1754",
          "type": "Deposit",
          "timestampms": "1679389053444",
          "method": "Crypto",
          "totalFeesPercentage": 4.729724554294425,
          "netAmountCurrency": "USD",
          "uuid": "b4f14acb-44e2-43ac-919e-4af630ae399b",
          "originalTransactionId": null,
          "externalId": "some-external-id"
        },
        {
          "transactionDate": "2023-03-21T08:41:24Z",
          "currency": "USD",
          "amount": 11.69,
          "grossAmount": 11.69,
          "totalFees": 0.35,
          "netAmount": 11.33,
          "txId": "char_hWSlEpaeYA4FRHsJa7AigwiG",
          "destination": "a0341cbe-bfba-49f3-85d1-b9eeaea71562",
          "origin": null,
          "anon": false,
          "donationNotes": "",
          "fundsDesignation": null,
          "organizationId": 1189132264,
          "organizationName": "The Best Organization Ever",
          "donorName": "Example Donor",
          "donorFirstName": "Example",
          "donorLastName": "Donor",
          "donorEmail": "[e-mail]",
          "donorAddress": "111 Test st",
          "city": "Allentown",
          "zipcode": "18109",
          "state": "Pennsylvania",
          "country": "United States",
          "id": "1752",
          "type": "Deposit",
          "timestampms": "1679388084929",
          "method": "Card",
          "totalFeesPercentage": 3,
          "netAmountCurrency": "USD",
          "uuid": "d90f0950-c3a4-4581-bc7e-52b6dd54177e",
          "originalTransactionId": null,
          "externalId": "some-external-id"
        },
        {
          "transactionDate": "2023-03-21T08:49:11Z",
          "currency": "FOUR",
          "amount": 100,
          "grossAmount": 6694,
          "totalFees": 0,
          "netAmount": 6694,
          "txId": null,
          "destination": "07ccc3b6-35df-4dd6-8ac8-856b5b442aab",
          "origin": null,
          "anon": false,
          "donationNotes": "That means a lot to me, thank you for all things you do",
          "fundsDesignation": null,
          "organizationId": 1189132264,
          "organizationName": "The Best Organization Ever",
          "donorName": "Example Donor",
          "donorFirstName": "Example",
          "donorLastName": "Donor",
          "donorEmail": "[e-mail]",
          "donorAddress": "111 Test st",
          "city": "Allentown",
          "zipcode": "18109",
          "state": "Pennsylvania",
          "country": "United States",
          "id": "1753",
          "type": "Deposit",
          "timestampms": "1679388551398",
          "method": "Stock",
          "totalFeesPercentage": 0,
          "netAmountCurrency": "USD",
          "uuid": "23975e28-09e6-4c75-be89-63b79cf21316",
          "originalTransactionId": null,
          "externalId": null
        }
      ],
      "pagination": {
        "page": 1,
        "itemsPerPage": 3,
        "count": 578
      }
    }
  },
  "requestId": "2d1f73f9-1742-4298-b454-177d92073dcf"
}

Examples:

cURL

curl --request POST \
  --url https://public-api.tgbwidget.com/v1/transaction/list \
  --header 'Authorization: Bearer {your-access-token}' \
  --header 'Content-Type: application/json' \
  --data '{
  "pagination": {
    "page": 1,
    "itemsPerPage": 100
  },
  "filters": {
    "date": {
      "from": 1664632635000
    },
    "externalId": "some-external-id"
  }
}'

Node.js

import axios from "axios";

const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/transaction/list',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer {your-access-token}'
    },
    data: {
        pagination: {page: 1, itemsPerPage: 100},
        filters: {date: {from: 1664632635000}},
        externalId: "some-external-id"
    }
};

axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});

Possible errors

Error Codes:

• INVALID_REQUEST in case if invalid POST body passed

• INVALID_JWT_TOKEN if Access Token is invalid (for example signature is invalid)

• EXPIRED_JWT_TOKEN if Access Token is expired. Please refresh tokens

• UNAUTHORIZED_USER if no Access Token is passed or endpoint usage is not allowed to your user

• INACTIVE_USER if user is restricted to access the API

GetTotalRaisedStats

POST https://public-api.tgbwidget.com/v1/organizations/total-raised

This endpoint should be used to retrieve how much was raised by every organization. Pagination is optional and if passed - overallTotal will remain the same but totalByOrganization will be paginated. Default page size is 30 items per page.

It's recommended to pass timestampmsFrom and timestampmsTo in filters if you need to get stats for period of time. If not passed - returns stats for all time.

By passing filter organizationIds, the endpoint will return information only for requested organiations

Sorting can be changed by passing sortBy.column and sortBy.order. Default sorting is by allDonations field in descending order.

Please note that this endpoint is not accessible by default. To be able to access it, please contact The Giving Block Partnership Team. Access Token required

Request Body

Name	Type	Description
pagination.page	number	Current page
pagination.itemsPerPage	number	Maximum items per one page
filters.timestampmsFrom	number	Start of time period to get stats from, passed in milliseconds
filters.timestampmsTo	number	End of time period to get stats from, passed in milliseconds
sortBy.column	string	Valid values: 'organizationId', 'totalDirectDonations', 'totalFundsDonations', 'allDonations'
sortBy.order	string	Valid values: 'desc', 'asc'
filters.organizationIds	Array[number]	Array of organizations ids

200

{
  "data": {
    "overallTotal": {
      "totalCryptoDonations": 30384.589535,
      "totalCryptoDonationsNumber": "256",
      "totalFiatDonations": 414.68,
      "totalFiatDonationsNumber": "64",
      "totalStocksDonations": 102602.48,
      "totalStocksDonationsNumber": "34",
      "totalDirectDonations": 133401.74953499998,
      "totalDirectDonationsNumber": "354",
      "totalImpactIndexFundsDonations": 15426.61,
      "totalImpactIndexFundsDonationsNumber": "12",
      "totalMatchedFundsDonations": 3600,
      "matchedFundsDonationsNumber": "4",
      "totalFundsDonations": 19026.61,
      "totalFundsDonationsNumber": "16",
      "allDonations": 148828.35953499997,
      "donationsNumber": 366
    },
    "totalByOrganization": [
      {
        "organizationId": 1189132048,
        "totalCryptoDonations": 0,
        "totalCryptoDonationsNumber": 0,
        "totalFiatDonations": 0,
        "totalFiatDonationsNumber": 0,
        "totalStocksDonations": 54676,
        "totalStocksDonationsNumber": "17",
        "totalDirectDonations": 54676,
        "totalDirectDonationsNumber": "17",
        "totalImpactIndexFundsDonations": 9505.61,
        "totalImpactIndexFundsDonationsNumber": "9",
        "totalMatchedFundsDonations": 3600,
        "totalMatchedFundsDonationsNumber": 0,
        "totalFundsDonations": 13105.61,
        "totalFundsDonationsNumber": "13",
        "allDonations": 64181.61000000001,
        "donationsNumber": 26
      },
      {
        "organizationId": 99,
        "totalCryptoDonations": 30384.589535,
        "totalCryptoDonationsNumber": "256",
        "totalFiatDonations": 414.68,
        "totalFiatDonationsNumber": "64",
        "totalStocksDonations": 47926.48,
        "totalStocksDonationsNumber": "17",
        "totalDirectDonations": 78725.74953500001,
        "totalDirectDonationsNumber": "337",
        "totalImpactIndexFundsDonations": 5921,
        "totalImpactIndexFundsDonationsNumber": "3",
        "totalMatchedFundsDonations": 0,
        "totalMatchedFundsDonationsNumber": 0,
        "totalFundsDonations": 5921,
        "totalFundsDonationsNumber": "3",
        "allDonations": 84646.74953500001,
        "donationsNumber": 340
      }
    ],
    "pagination": {
      "page": 1,
      "itemsPerPage": 100,
      "count": 2
    }
  },
  "requestId": "71b184d9-47a6-4ffe-b55e-c1c0150298ea"
}

Examples:

cURL

curl --request POST \
  --url https://public-api.tgbwidget.com/v1/organizations/total-raised \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json' \
  --data '{
    "filters": {
    	"organizationIds": [99]
    }
  }'

Node.js

import axios from "axios";

const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/organizations/total-raised',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer {your-access-token}'
    },
    data: {
        pagination: {page: 1, itemsPerPage: 100},
        filters: {organizationIds: [1000120214]}
    }
};

axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});

Possible Error Codes:

• INVALID_REQUEST in case if invalid POST body passed

• INVALID_JWT_TOKEN if Access Token is invalid (for example signature is invalid)

• EXPIRED_JWT_TOKEN if Access Token is expired. Please refresh tokens

• UNAUTHORIZED_USER if no Access Token is passed or endpoint usage is not allowed to your user

• INACTIVE_USER if user is restricted to access the API

CreateFiatDonationPledge

POST https://public-api.tgbwidget.com/v1/donation/fiat

This endpoint is used to create a fiat donation. Access Token required

Request Body

Name	Type	Description
organizationId*	String	99
isAnonymous*	boolean	true
pledgeAmount*	String	10
firstName	String	John
lastName	String	Doe
receiptEmail	String	[e-mail]
addressLine1	String	My street 5
addressLine2	String	appt 6
country	String	US
state	String	NY
city	String	New York
zipcode	String	89000

200: OK

{
  "data": {
    "pledgeId": "434b9bfb-69f1-4f19-baf7-55f41e331faf"
  },
  "requestId": "232b620c-464e-454f-b131-02128bce8419"
}

500: Internal Server Error Fiat donations disabled

{
    "errorMessage":"Organization not found",
    "errorType":"err.generic",
    "meta":{},
    "requestId":"99f0ec91-0def-4aca-99a9-eba17c2af2a3"
}

Examples:

cURL

curl --request POST \
  --url https://public-api.tgbwidget.com/v1/donation/fiat \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json' \
  --data '{
	"organizationId": "99",
	"isAnonymous": true,
	"pledgeAmount": "10"
}'

Node.js

import axios from "axios";

const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/donation/fiat',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer {your-access-token}'
    },
    data: {organizationId: '10120152', isAnonymous: true, pledgeAmount: '10'}
};

axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});

ChargeFiatDonationPledge

POST https://public-api.tgbwidget.com/v1/donation/fiat/charge

This endpoint is used to charge a card

Request Body

Name	Type	Description
pledgeId*	String	434b9bfb-69f1-4f19-baf7-55f41e331faf
cardToken*	String	tok_Nc4ZfL926ZT4X32xtBspxf0y3

200: OK

{
  "data": {
    "success": true
  }
}

500: Internal Server Error Charge failed

{
    "errorMessage":"The charge amount exceeds the available funds or the card's credit limit.",
    "errorType":"err.generic",
    "meta":{},
    "requestId":"99f0ec91-0def-4aca-99a9-eba17c2af2a3"
}

Examples:

cURL

curl --request POST \
  --url https://public-api.tgbwidget.com/v1/donation/fiat/charge \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json' \
  --data '{
	"pledgeId": "434b9bfb-69f1-4f19-baf7-55f41e331faf",
	"cardToken": "tok_Nc4ZfL926ZT4X32xtBspxf0y3"
}'

Node.js

import axios from "axios";

const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/donation/fiat/charge',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer {your-access-token}'
    },
    data: {
        pledgeId: '9534a8a5-80a6-4f4c-a3a4-848c9e921ff8',
        cardToken: 'tok_Nc4ZfL926ZT4X32xtBspxf0y3'
    }
};

axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});

GetBrokersList

GET https://public-api.tgbwidget.com/v1/stocks/brokers

Returns list of brockers that can be used to send stocks from

200: OK

{
	"data": {
		"brokers": [
			{
				"name": "ameriprise",
				"label": "Ameriprise"
			},
			{
				"name": "schwab",
				"label": "Charles Schwab"
			},
			{
				"name": "etrade",
				"label": "E-Trade"
			},
			{
				"name": "fidelity",
				"label": "Fidelity Investments"
			},
			{
				"name": "jpmorgan",
				"label": "J.P. Morgan"
			},
			{
				"name": "lpl",
				"label": "LPL Financial"
			},
			{
				"name": "merrill",
				"label": "Merrill Lynch"
			},
			{
				"name": "morganstanley",
				"label": "Morgan Stanley"
			},
			{
				"name": "ameritrade",
				"label": "TD Ameritrade"
			},
			{
				"name": "tiaa",
				"label": "TIAA Brokerage"
			},
			{
				"name": "trowe",
				"label": "T. Rowe Price"
			},
			{
				"name": "wellsfargo",
				"label": "Wells Fargo"
			},
			{
				"name": "other",
				"label": "Other"
			}
		]
	},
	"requestId": "821ec76e-ae39-4206-b5db-48322b07729d"
}

Examples:

cURL

curl --request GET \
  --url https://public-api.tgbwidget.com/v1/stocks/brokers \
  --header 'Authorization: Bearer your-auth-token'

Node.js

import axios from "axios";

const options = {
    method: 'GET',
    url: 'https://public-api.tgbwidget.com/v1/stocks/brokers',
    headers: {
        Authorization: 'Bearer {your-access-token}'
    }
};

axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});

GetTickersList

POST https://public-api.tgbwidget.com/v1/stocks/tickers

Returns a list of supported tickers without prices. To get prices please use GetTickerCost endpoint

Request Body

Name	Type	Description
filters.name	String	Stock Name (only name or ticket allowed)
filters.ticker	String	Stock Ticker (only name or ticket allowed)
pagination.page	Number
pagination.itemsPerPage	Number

200: OK

{
  "data": {
    "tickers": [
      {
        "name": "Agilent Technologies Inc.",
        "ticker": "A"
      },
      {
        "name": "Alcoa Corporation",
        "ticker": "AA"
      },
      {
        "name": "AXS First Priority CLO Bond ETF",
        "ticker": "AAA"
      },
      {
        "name": "Goldman Sachs Physical Gold ETF Shares",
        "ticker": "AAAU"
      },
      {
        "name": "Ares Acquisition Corporation",
        "ticker": "AAC"
      }
    ],
    "pagination": {
      "itemsPerPage": 5,
      "page": 1,
      "count": 10002
    }
  },
  "requestId": "e50360a5-13c9-4f07-95fc-3bb455f352ea"
}

Examples:

cURL

curl --request POST \
  --url https://public-api.tgbwidget.com/v1/stocks/tickers \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json' \
  --data '{
	"pagination": {
		"itemsPerPage": 25,
		"page": 1
	}
}'

Node.js

import axios from "axios";

const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/stocks/tickers',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer {your-access-token}'
    },
    data: {pagination: {itemsPerPage: 25, page: 1}}
};

axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});

GetTickerCost

GET https://public-api.tgbwidget.com/v1/stocks/ticker-cost

Returns Ticker price in USD

Query Parameters

Name	Type	Description
ticker*	String	FOUR

200: OK

{
  "data": {
    "rate": 10.06
  },
  "requestId": "433d548c-7317-4d10-bedd-0ad56e0eed79"
}

Examples:

cURL

curl --request GET \
  --url 'https://public-api.tgbwidget.com/v1/stocks/ticker-cost?ticker=FOUR' \
  --header 'Authorization: Bearer your-auth-token'

Node.js

import axios from "axios";

const options = {
    method: 'GET',
    url: 'https://public-api.tgbwidget.com/v1/stocks/ticker-cost',
    params: {ticker: 'FOUR'},
    headers: {
        Authorization: 'Bearer {your-access-token}'
    }
};

axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});

CreateStockDonationPledge

POST https://public-api.tgbwidget.com/v1/donation/stocks

Creates a pledge for Stock donation. pledgeAmount is amount of shares that donor donates and assetSymbol along with assetDescription defines what share it is

Request Body

Name	Type	Description
organizationId*	Number	99
assetSymbol*	String	AAAU
assetDescription*	String	Goldman Sachs Physical Gold ETF Shares
pledgeAmount*	Number	1
receiptEmail*	String	[e-mail]
firstName*	String	John
lastName*	String	Doe
addressLine1*	String	Tukan Street 4321
addressLine2*	String	Apt 55
country*	String	US
state*	String	NY
city*	String	New York
zipcode*	String	89000
phoneNumber*	String	55555555

200: OK

{
  "data": {
    "donationUuid": "1c264816-b5c1-4d28-9e23-e5d5c052723a"
  },
  "requestId": "58f9112c-5405-405a-9998-d948eb1039e6"
}

Examples:

cURL

curl --request POST \
  --url https://public-api.tgbwidget.com/v1/donation/stocks \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json' \
  --data '{
	"organizationId": "99",
	"assetSymbol": "AAAU",
	"assetDescription": "Goldman Sachs Physical Gold ETF Shares",
	"pledgeAmount": 100,
	"receiptEmail": "[e-mail]",
	"firstName": "John",
	"lastName": "Doe",
	"addressLine1": "Tukan Street 4321",
	"addressLine2": "Apt 51",
	"country": "US",
	"state": "NY",
	"city": "New York",
	"zipcode": "89000",
	"phoneNumber": "55555555"
}'

Node.js

import axios from "axios";

const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/donation/stocks',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer {your-access-token}'
    },
    data: {
        organizationId: '99',
        assetSymbol: 'AAAU',
        assetDescription: 'Goldman Sachs Physical Gold ETF Shares',
        pledgeAmount: 100,
        receiptEmail: '[e-mail]',
        firstName: 'John',
        lastName: 'Doe',
        addressLine1: 'Tukan Street 4321',
        addressLine2: 'Apt 51',
        country: 'US',
        state: 'NY',
        city: 'New York',
        zipcode: '89000',
        phoneNumber: '55555555'
    }
};

axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});

SubmitStockDonation

POST https://public-api.tgbwidget.com/v1/stocks/submit

Adds donor broker information to the Stock donation Pledge

Request Body

Name	Type	Description
donationUuid*	String	1c264816-b5c1-4d28-9e23-e5d5c052723a
brokerName*	String	ameriprise
brokerageAccountNumber*	String	12345678
brokerContactName*	String	Sergii
brokerEmail*	String	[e-mail]
brokerPhone*	String	5555555

200: OK

{
  "data": {
    "isSuccess": true
  },
  "requestId": "3aa84ad9-5222-4e01-a5b0-d0c6c2849836"
}

Examples:

cURL

curl --request POST \
  --url https://public-api.tgbwidget.com/v1/stocks/submit \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json' \
  --data '{
	"donationUuid": "6118018e-6beb-4e04-a3e2-d22fd9aaec0f",
	"brokerName": "ameriprise",
	"brokerageAccountNumber": "12345678",
	"brokerContactName": "John Doe",
	"brokerEmail": "[e-mail]",
	"brokerPhone": "65515254"
}'

Node.js

import axios from "axios";

const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/stocks/submit',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer {your-access-token}'
    },
    data: {
        donationUuid: '6118018e-6beb-4e04-a3e2-d22fd9aaec0f',
        brokerName: 'ameriprise',
        brokerageAccountNumber: '12345678',
        brokerContactName: 'John Doe',
        brokerEmail: '[e-mail]',
        brokerPhone: '65515254'
    }
};

axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});

SignStockDonation

POST https://public-api.tgbwidget.com/v1/stocks/sign

Adds a signature of the donor to the Stock pledge

Request Body

Name	Type	Description
donationUuid*	String	1c264816-b5c1-4d28-9e23-e5d5c052723a
date*	ISO Date	Thu Feb 16 2023 16:21:47 GMT+0800 (Central Indonesia Time)
signature*	Base64 PNG image

200: OK

{
  "data": {
    "isSuccess": true
  },
  "requestId": "93289774-9546-43e5-8258-3ed5a2eaa9a3"
}

Examples:

cURL

curl --request POST \
  --url https://public-api.tgbwidget.com/v1/stocks/sign \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json' \
  --data '{
	"donationUuid": "6118018e-6beb-4e04-a3e2-d22fd9aaec0f",
	"date": "Thu Mar 30 2023 14:44:38 GMT+0200 (Central European Summer Time)",
	"signature": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAADxElEQVR42rXWXUxbZRzH8VNAFzdHhsZ4MS/cjfFOkw2MvJWCol3IJujWls1ysxk2AzozXbKxaKZZ1C0kE+PFkk2NRo2LCS7RicxgtCEICHSU2VJKoZbSlp6+0x2gz/PfL1tO2OjScQ7ln3zuoN9f23NRQc2Vbjc+CC/CVbgExZAvrPchooGn4CwEgIDDFByHJyD34ee3mxA3PgatYAcOtEIaBmA/FObyXW+EXdADi0D3kYJOqIIH1hIugGL4GuJACs3BOXga8lYd3llzUFNe3LgN/3QKZoDWgMM4HIHHsz4fp050CK2HPnrE2HDkgK7UfA1/zIByZAn+hj2wKSN+dWA4//OO71449s6Z3/bvfVeqLjMrCiiQhB/0VXtLLp17WSPI96/PU9Q9ONzb/tk33Gx6j3Sl6zNA+5yBWsz1rPti7ZVQn/YhQb6ROd+jMPSPx80v/PgLNxqO8rIdppyFy3YYqXHXaxzvmkX6tTw9VvEXbMwYADQS9NEfNhv/4JPzTF/7Bl9rvK56D+84Wcc9PTq+ZKsghCnrANlQwEudlj721tFPma68SfGQmlIDbzu8m1l/rmELo3JYwQDZgHeavursYuam47yiZN99w5UlRmo2NbDuL2tZcriSy1GVA5ZZJpy8/fz3vH53i/x8ZHzPhjoD//ZsHcMDthxWPyDTcHCGfh+x8hMffsFeqj7A5fhOXSNvb3uduf98hS+NaeVIrgcsG/J76aceC2t5+zQ79uYhNvhrK1+w76P09Ro5sL4DroVmySb6yeYbp9jkGWKTBylt1y8H1A5QEr8uBmhCdJE03UZpRz1eVKt0wKaMAUri/4WD5BKdJLkO46OvVhInsMDDGQOUxB2ROXKLDpLGG5WEZb2wOWOAkrgzGqJp0U6S/VU1A/qgMGOAkrgrJpIn7KAFe4OaAf2wJWOAkrg7FiZvZJwWHKoGDELRnQO2QK+S+HQ8Qr5bA1R9BZaVn0AeVMFlSK0m/n8iSrNRp9IBKbgMlXD370Sr3y8gXmgNzTaNiv5+xNPZ4jPJGAViE6sdkIYBMMNmIdvhnQtjYmAr4icRdyPO7xX3zccpGHPRYvYBHNzwPmwFYdWHeD7iz7ii4kXEIyvj/vkEheKT2QaE4QI8C3mC2kN8w1Q8ovckol2IS3I8mEpSOOG+1wAJukAPG4RcnG8+KniTsSJfMt6MuBVxFroxT5HE1J0DGIxCMxSlx8qEnB/iGsSfRPx0WEp5Y8kpWro9YAY+hm2gEdb7RClVEJFulCcSziuLTlMXolooUPNaNwHKoyh4NF+RhgAAAABJRU5ErkJggg=="
}'

Node.js

import axios from "axios";

const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/stocks/sign',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer {your-access-token}'
    },
    data: {
        donationUuid: '6118018e-6beb-4e04-a3e2-d22fd9aaec0f',
        date: 'Thu Mar 30 2023 14:44:38 GMT+0200 (Central European Summer Time)',
        signature: 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAADxElEQVR42rXWXUxbZRzH8VNAFzdHhsZ4MS/cjfFOkw2MvJWCol3IJujWls1ysxk2AzozXbKxaKZZ1C0kE+PFkk2NRo2LCS7RicxgtCEICHSU2VJKoZbSlp6+0x2gz/PfL1tO2OjScQ7ln3zuoN9f23NRQc2Vbjc+CC/CVbgExZAvrPchooGn4CwEgIDDFByHJyD34ee3mxA3PgatYAcOtEIaBmA/FObyXW+EXdADi0D3kYJOqIIH1hIugGL4GuJACs3BOXga8lYd3llzUFNe3LgN/3QKZoDWgMM4HIHHsz4fp050CK2HPnrE2HDkgK7UfA1/zIByZAn+hj2wKSN+dWA4//OO71449s6Z3/bvfVeqLjMrCiiQhB/0VXtLLp17WSPI96/PU9Q9ONzb/tk33Gx6j3Sl6zNA+5yBWsz1rPti7ZVQn/YhQb6ROd+jMPSPx80v/PgLNxqO8rIdppyFy3YYqXHXaxzvmkX6tTw9VvEXbMwYADQS9NEfNhv/4JPzTF/7Bl9rvK56D+84Wcc9PTq+ZKsghCnrANlQwEudlj721tFPma68SfGQmlIDbzu8m1l/rmELo3JYwQDZgHeavursYuam47yiZN99w5UlRmo2NbDuL2tZcriSy1GVA5ZZJpy8/fz3vH53i/x8ZHzPhjoD//ZsHcMDthxWPyDTcHCGfh+x8hMffsFeqj7A5fhOXSNvb3uduf98hS+NaeVIrgcsG/J76aceC2t5+zQ79uYhNvhrK1+w76P09Ro5sL4DroVmySb6yeYbp9jkGWKTBylt1y8H1A5QEr8uBmhCdJE03UZpRz1eVKt0wKaMAUri/4WD5BKdJLkO46OvVhInsMDDGQOUxB2ROXKLDpLGG5WEZb2wOWOAkrgzGqJp0U6S/VU1A/qgMGOAkrgrJpIn7KAFe4OaAf2wJWOAkrg7FiZvZJwWHKoGDELRnQO2QK+S+HQ8Qr5bA1R9BZaVn0AeVMFlSK0m/n8iSrNRp9IBKbgMlXD370Sr3y8gXmgNzTaNiv5+xNPZ4jPJGAViE6sdkIYBMMNmIdvhnQtjYmAr4icRdyPO7xX3zccpGHPRYvYBHNzwPmwFYdWHeD7iz7ii4kXEIyvj/vkEheKT2QaE4QI8C3mC2kN8w1Q8ovckol2IS3I8mEpSOOG+1wAJukAPG4RcnG8+KniTsSJfMt6MuBVxFroxT5HE1J0DGIxCMxSlx8qEnB/iGsSfRPx0WEp5Y8kpWro9YAY+hm2gEdb7RClVEJFulCcSziuLTlMXolooUPNaNwHKoyh4NF+RhgAAAABJRU5ErkJggg=='
    }
};

axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});

InitializeNPOOnboarding

POST https://public-api.tgbwidget.com/v1/non-profit-onboarding

Creates a Nonprofit Organization entity and returns data necessary to be used in next onboarding process calls

Request Body

Name	Type	Description
ein*	String	Tax Number, for US format is 12-1234567
name*	String	Nonprofit organization name
contactEmail*	String	Contact Email for an organization
onboardingSource*	String	Onboarding source value given by TheGivingBlock to you during your integration setup
address1*	String	Address Line 1
address2	String	Address Line 2
city*	String	Address City
state*	String	Address State, please use 2 letter state code
postcode*	String	ZIP Code

200: OK

{
  "data": {
    "organizationId": 1189135543
  },
  "requestId": "61903b99-de34-4d2e-adad-93578d1a0a19"
}

Examples:

cURL

curl --request POST \
  --url https://public-api.tgbwidget.com/v1/non-profit-onboarding \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json' \
  --data '{
      "ein": "12-1234567",
      "name": "Nonprofit Organization Example",
      "contactEmail": "[e-mail]",
      "onboardingSource": "your-company-specific-source",
      "address1": "address line 1",
      "address2": "address line 2",
      "city": "New York",
      "state": "NY",
      "postcode": "89000"
  }'

Node.js

import axios from "axios";

const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/non-profit-onboarding',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer {your-access-token}'
    },
    data: {
        ein: '12-1234567',
        name: 'Nonprofit Organization Example',
        contactEmail: '[e-mail]',
        onboardingSource: 'your-company-specific-source',
        address1: 'address line 1',
        address2: 'address line 2',
        city: 'New York',
        state: 'NY',
        postcode: '89000'
    }
};

axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});

EnableCardPayments

POST https://public-api.tgbwidget.com/v1/non-profit-onboarding/:organizationId/card

Executes all necessary workflows to enable Card payments for a given Organization and returns back auth tokens for card payments and merchantId

Path Parameters

Name	Type	Description
organizationId*	String	Organization ID obtained from the InitializeNPOOnboarding call

Request Body

Name	Type	Description
wireRoutingNumber*	String	NPO Bank account Wire routing number
accountNumber*	String	NPO Bank account number
dateOfIncorporation*	String	Represents the date when company started
controlPerson*	ControlPerson[]	Array of Control persons, normally you need to pass just one for onboarding to succeed
controlPerson[].firstName*	String	First Name of control person
controlPerson[].lastName*	String	Last Name of control person
controlPerson[].phone*	String	Control person phone number
controlPerson[].address*	String	Control person address
controlPerson[].city*	String	Control person address city
controlPerson[].postcode*	String	Control person Postal code
controlPerson[].state*	String	Control person state

200: OK

{
  "data": {
    "onboarded": true,
    "shift4": {
      "merchantId": "123456",
      "apiKeys": {
        "test": {
          "public": "merchant-public-key",
          "secret": "merchant-public-key-secret"
        },
        "live": {
          "public": "merchant-public-key",
          "secret": "merchant-public-key-secret"
        }
      }
    }
  },
  "requestId": "93289774-9546-43e5-8258-3ed5a2eaa9a3"
}

Examples:

cURL

curl --request POST \
  --url https://public-api.tgbwidget.com/v1/non-profit-onboarding/1189135543/card \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json' \
  --data '{
     "wireRoutingNumber": "000000000",
     "accountNumber": "000000000",
     "dateOfIncorporation": "10/22/2000",
     "controlPerson": [
       {
         "firstName": "John",
         "lastName": "Doe",
         "phone": "1234567890",
         "address": "address",
         "city": "city",
         "state": "NY",
         "postcode": "89000"
       }
     ]
}'

Node.js

import axios from "axios";

const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/non-profit-onboarding/1189135543/card',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer {your-access-token}'
    },
    data: {
        wireRoutingNumber: '000000000',
        accountNumber: '000000000',
        dateOfIncorporation: '10/22/2000',
        controlPerson: [
          {
            firstName: 'John',
            lastName: 'Doe',
            phone: '1234567890',
            address: 'address',
            city: 'city',
            state: 'NY',
            postcode: '89000'
          }
        ]
      }
};

axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});

EnableCryptoPayments

POST https://public-api.tgbwidget.com/v1/non-profit-onboarding/:organizationId/crypto

Executes all necessary workflows to enable Crypto payments for a given Organization.

Path Parameters

Name	Type	Description
organizationId*	String	Organization ID obtained from the InitializeNPOOnboarding call

200: OK

{
  "data": {
    "onboarded": true,
  },
  "requestId": "93289774-9546-43e5-8258-3ed5a2eaa9a3"
}

Examples:

cURL

curl --request POST \
  --url https://public-api.tgbwidget.com/v1/non-profit-onboarding/12345/crypto \
  --header 'Authorization: Bearer your-access-token' \
  --header 'Content-Type: application/json'

Node.js

import axios from 'axios';

const options = {
    method: 'POST',
    url: 'https://public-api.tgbwidget.com/v1/non-profit-onboarding/12345/crypto',
    headers: {
        'Content-Type': 'application/json',
        Authorization: 'Bearer {your-access-token}'
    },
    data: {}
};

axios.request(options).then((response) => {
    console.log(response.data);
}).catch((error) => {
    console.error({
        message: error.message,
        stack: error.stack,
        response: error.response,
    });
});

Error Codes

Code	Description
EXPIRED_JWT_TOKEN	Expired JWT token used, refresh tokens to continue using the API
INVALID_JWT_TOKEN	Invalid JWT token used, try login again
UNAUTHORIZED_USER	Access to the endpoint is forbidden
INACTIVE_USER	API user is disabled
INVALID_LOGIN_CREDENTIALS	Wrong pair of login/password used
INVALID_REQUEST	Request validation failed