📖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

NameTypeDescription

login*

string

Your api user login

password*

string

Your api user password

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

Examples:

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

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

NameTypeDescription

refreshToken*

string

Your refresh token

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

Examples:

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

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

NameTypeDescription

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.

{
  "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 --request GET \
  --url https://public-api.tgbwidget.com/v1/organizations/list \
  --header 'Authorization: Bearer your-access-token'

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

NameTypeDescription

id

number

Organization id

{
  "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 --request GET \
  --url https://public-api.tgbwidget.com/v1/organization/1189133200 \
  --header 'Authorization: Bearer your-access-token'

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

NameTypeDescription

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

campaignId

String

ID of the campaign for which donations will be made

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

{
	"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 --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"}
}'

  • 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

NameTypeDescription

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

defaultCryptocurrency

String

This is the code of cryptocurrency which will be selected by default in the donation form. If it's not provided, BTC is used by default.

returnUrl

String

Donation form will be redirected to this value after donation is received 

{
  "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 --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/"
}'

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

NameTypeDescription

currency*

String

Cryptocurrency code (btc, eth, doge etc.)

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

Examples:

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

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

NameTypeDescription

organizationId

number

12345678

isAnonymous

boolean

false

pledgeCurrency

string

"BTC"

pledgeAmount

string

"0.0001"

firstName

string

"John"

lastName

string

"Doe"

receiptEmail

string

"some-donor-email@domain.com"

addressLine1

string

"My street 1"

addressLine2

string

"apt 2"

country

string

"US"

state

string

"NY"

city

string

"New York"

zipcode

string

"4422211"

{
  "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 --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"
}'

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 and rates (optionally).

Request Body

NameTypeDescription

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)

filters.includeRates

boolean

If set to true, currency rates will be included in a response (rate - actual rate, rateTime - ISO time when rate was retrieved, quoteCurrency)

filters.organizationId

number

The Organization ID of organization for which rates should be retrieved - useful for case when you need rates for other currencies than USD

pagination

object

Pagination object

pagination.page

number

page to list in response

pagination.itemsPerPage

number

amount of items listed on a page

{
  "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"
}

Examples

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

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

NameTypeDescription

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

{
  "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": "example-email@thegivingblock.com",
          "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": "example-email@thegivingblock.com",
          "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 --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"
  }
}'