Skip to main content
Version: v1

Goodstack Services

Introduction

Goodstack API allows you to build good into your product by facilitating charitable donations. We achieve this through the API's listed and specified in this documentation.

For all donations using the Goodstack API, Goodstack handles the vetting and validation of the good causes and onward the disbursement of the donation.

The Goodstack API is organised around REST. All API responses, including errors, return JSON and use standard HTTP response codes. In all API requests you must specify the content-type HTTP header as application/json. All API requests must be made over HTTPS.

Authentication

Authenticate your API requests by setting your live secret API key in the Authorization header.

Two keys are provided to you, a publishable key prefixed with pk_ and a secret key prefixed with sk_.

Publishable API keys are meant solely to identify your goodstack account. These can safely be published in places like your JavaScript code, or in an Android or iPhone app and are meant for usage with our SDKs.

Secret API keys should be kept confidential and only used in secure server environments.

Anywhere that accepts a Publishable key will also accept a Secret key, but routes marked to accept a Secret key will not accept a Publishable key.

Formats

Dates​

Dates are encoded as strings following the ISO 8601 standard 2021-08-01T12:00:00.000Z.

Pagination​

A maximum of 100 objects can be returned per request and the limit can be specified by using the pageSize query parameter. By default, the pageSize is set to 25.

Metadata​

Some objects have a metadata parameter that you can use to store key-value data.

You can specify up to 20 keys, with key names up to 40 characters long and values up to 250 characters long.

Errors​

The API returns standard HTTP response codes to indicate success or failure of API requests. Errors may include a custom error message. Error objects have these attributes, an id, a message corresponding to the HTTP response phrase of the error, an optional invalid-params attribute detailing issues with the request.

An example error object returned from the API:

{
  error: {
    code: 'bad_request',
    title: 'Bad request',
    message: 'Something is wrong with your request, please check any parameters and try again',
    reasons: ['amount is a required field']
  }
}

A summary of the HTTP status codes returned from the api is listed in the table below.

CodeTitleDescription
200SuccessRequest successful
204No ContentRequest successful with no content returned
400Bad RequestRequest was invalid
401UnauthorisedAuthorization header is invalid
403ForbiddenInsufficient permissions
404Not FoundResource does not exist
429Too Many RequestsRate Limited
500sInternal Server ErrorSomething went wrong with the Goodstack API

Retry recommendations

Although rare, network requests may fail due to their inherent unreliability. To ensure a robust integration with Goodstack we recommend that you implement a retry mechanism, so that if a network request fails you are able to retry the request. Goodstacks API supports idempotency for safely retrying requests through usage of idempotency keys.

For some POST endpoints we allow clients to specify an idempotency key in the Idempotency-Key header. This allows the client to retry requests without accidentally performing the same operation twice.

If the same idempotency key is used for multiple requests, only the first successful request will be actioned and subsequent calls will return the result of the first request. Failed requests may be retried with the same idempotency key.

Requests with the same idempotency key and different payload will fail.

The idempotency key expires after 21 days. After this time, a new request with the same idempotency key will be treated as a new request.

Webhooks

Use webhooks to subscribe to updates on particular events that occur in Goodstack. Each time an event that you have subscribed to occurs, Goodstack submits a POST request to the designated webhook URL with information about the event.

To receive webhook notifications, use the webhook subscriptions API.

For detailed webhook event specifications, see the webhook events section.

Webhook Structure​

All webhook payloads contain object and data fields. The data record contains:

ParameterTypeDescription
idstringId of the event
createdAtstringTimestamp of when the event was created
eventTypestringThe type of the event e.g. validation_request.approved
eventDatarecordData associated with the event

Webhook Security & Delivery​

IP Addresses: Webhook notifications come from these IP addresses:

Production: 54.228.234.204, 54.76.67.168, 34.248.188.89, 34.243.152.218

Sandbox: 79.125.45.124, 54.76.168.240, 99.81.243.145, 54.220.118.167

Response Requirements: Your endpoint must return a 2xx HTTP status code to acknowledge receipt.

Retry Policy: Failed webhooks are retried 4 times over 14 hours with increasing delays.

Verification: Each webhook includes a Goodstack-Signature header generated using HMAC SHA-256 with your webhook subscription secret as the key.

Idempotency: Use the event id to handle duplicate webhook deliveries idempotently.

Authentication​

API key starting with 'pk_' that can be made public

Security Scheme Type:

apiKey

Header parameter name:

Authorization

Validation submission events​

See the Validation submission events reference.

Donation events​

See the Donation events reference.