If you have not obtained your JWT access_token or causeId, please refer to the Authorization section to obtain your access_token and Search for a Cause to obtain the causeId.

# Make a Company Donation

Now that we have the cause id and the authorization token, we can begin creating a company donation!

A company donation is another donation type that Benevity offers but unlike a credit card donation, your users do not have to pay immediately in order to create a donation. Instead, your company will receive a donation report at the end of the month.

If you wish to donate using a credit card payment instead, you can go back to make a credit card donation.

To create a donation, we'll be leveraging the POST /donations endpoint and GET /donations/{id} endpoint.

# Create the Donation

Ensure that you authenticate the request with the JWT you've previously obtained, by passing the JWT as an Authorization header.

Great, let's make the donation! All that you have to do now, is to tell us to process the donation. To do so, we will call the POST /donations endpoint to create a donation.

This endpoint requires some additional core donation payment information, such as:

Donation "destination" attributes:

recipientId - the ID of the cause, project, or portfolio you wish to donate to (ex: 124-1234ABCD, 124-1234ABCD/3A19BC2DX3, or 2XABCDE4UT respectively)
foundationId - this is an OPTIONAL attribute
- choose which foundation the donation is routed through
- by default, Benevity will determine an appropriate foundation for the cause you wish to donate to

Donation "funds" attributes:

paymentType - the type of payment being made
currencyCode - the currency code you are donating in
- must be an ISO-4217 (opens new window) currency code
amount - the amount of money being donated in the lowest denominator of a currency
- in the sample response below, 100 cents in CAD is donated

Donation "donor" attributes:

if companies are making anonymous donations on behalf of a guest user, the donor attribute is OPTIONAL
if a donor is present, but does not want their own receipt, receipted can be set to false

Donation "metadata" attributes:

the metadata attribute is OPTIONAL
it contains additional attributes that companies can use to associate extra information with the transaction in the Benevity platform, which can be later used by Benevity Reporting (opens new window)
metadata supports up to 100 key/value pairs
- the key should only contain alphanumeric characters with spaces/underscores/dashes, and can be from 1 to 64 characters in length
- the value allows any characters in the Basic Multilingual Plane (opens new window) except surrogates (opens new window), and can be from 1 to 190 characters in length

# Sample request:

# Sample response:

{
  "data": {
    "type": "donations",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "attributes": {
      "destination": {
        "recipientId": "124-119219814RR0001"
      },
      "donor": {
        "fullName": "Benevity User",
        "email": "test@benevity.com",
        "receipted": true,
        "address": {
          "city": "Calgary",
          "country": "CA",
          "line1": "5555 Calgary St",
          "line2": "Suite 101",
          "state": "AB",
          "zip": "T0A 1B2"
        }
      },
      "funds": {
        "amount": 100,
        "currencyCode": "CAD",
        "paymentType": "DONATION_REPORT",
        "source": "COMPANY"
      },
      "metadata": {
        "vendor-id": "abc-12382",
        "location": "NW Calgary",
        "refill_date": "05/15/2023"
      },
      "state": {
        "processingStatus": "ACCEPTED",
        "statusLastUpdated": "2021-01-16T00:26:15.202Z"
      }
    }
  }
}

# Donation Lifecycle

Once a donation is created, it will first be in the ACCEPTED state for processing.
Within a few minutes, an ACCEPTED donation will begin further processing and transition to one of two possible states:

INITIATED state if the donation was successfully processed
DECLINED state if the donation failed to process

If the donation was DECLINED, a new donation must be created with the error corrected as the existing donation record is immutable and cannot be modified.
An INITIATED donation will continue its lifecycle throughout the following additional states:

IN_PROGRESS state if the donation has been processed and included in a generated Payable/Disbursement
PAID state if a Payable/Disbursement has been sent. The processing time depends on the payment type.
CLEARED state if the payment has cleared the cause's account (i.e. check was cashed, EFT successful). This is the final state for successful donations.

The following flow diagram illustrates complete donation flow with all possible states and transitions:

Donation Flow Diagram

If the donation is declined in the backend, a DECLINED status will be returned and the donation will need to be re-processed
If the payment to the cause is unsuccessful, the status will go back to INITIATED

# Get the Donation Details

Now that you have created a donation, you can use the donation ID to obtain the full details and status updates of your donation through the GET /donations/{id} endpoint.

From the sample request above, you can see that the donation we wish to support has a donation ID of 123e4567-e89b-12d3-a456-426614174000. To retrieve the details of this donation, the donation ID will be passed in as a parameter for the request.

receiptId - the unique ID of receipt generated on making a guest donation, if "receipted" is marked true for the donor.

# Sample Request:

# Sample Response:

# Initiated Donation

Here you can see that the donation was successfully processed from the status INITIATED along with the exact time in which it was last updated.

{
  "data": {
    "type": "donations",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "attributes": {
      "destination": {
        "recipientId": "124-119219814RR0001"
      },
      "donor": {
        "fullName": "Benevity User",
        "email": "test@benevity.com",
        "receipted": true,
        "address": {
          "city": "Calgary",
          "country": "CA",
          "line1": "5555 Calgary St",
          "line2": "Suite 101",
          "state": "AB",
          "zip": "T0A 1B2"
        }
      },
      "funds": {
        "amount": 100,
        "currencyCode": "CAD",
        "paymentType": "DONATION_REPORT",
        "source": "COMPANY"
        "receiptId": "1YTWL8K9AC"
      },
      "metadata": {
        "vendor-id": "abc-12382",
        "location": "NW Calgary",
        "refill_date": "05/15/2023"
      },
      "state": {
        "processingStatus": "INITIATED",
        "statusLastUpdated": "2021-01-18T00:26:13.202Z"
      }
    }
  }
}

# Cleared Donation

Here you can see a donation that was successfully disbursed to a nonprofit with the status CLEARED along with the exact time in which it was last updated. If the donation is in a state where it is linked to a Payable/Disbursement, the payable object will be included in the response with the paymentType attribute detailing the method of payment (CHEQUE/EFT/PAYPAL).

{
  "data": {
    "type": "donations",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "attributes": {
      "destination": {
        "recipientId": "124-119219814RR0001"
      },
      "donor": {
        "fullName": "Benevity User",
        "email": "test@benevity.com",
        "receipted": true,
        "address": {
          "city": "Calgary",
          "country": "CA",
          "line1": "5555 Calgary St",
          "line2": "Suite 101",
          "state": "AB",
          "zip": "T0A 1B2"
        }
      },
      "funds": {
        "amount": 100,
        "currencyCode": "CAD",
        "paymentType": "DONATION_REPORT",
        "source": "COMPANY"
        "receiptId": "1YTWL8K9AC"
      },
      "metadata": {
        "vendor-id": "abc-12382",
        "location": "NW Calgary",
        "refill_date": "05/15/2023"
      },
      "payable": {
        "paymentType": "EFT"
      },
      "state": {
        "processingStatus": "CLEARED",
        "statusLastUpdated": "2021-01-19T00:26:13.202Z"
      }
    }
  }
}

# Declined Donation

Below is an example of a donation that has the status DECLINED. There are several different reasons as to why the donation may have been declined which can be read in detail here.

Under the errors heading, more info is given as to why the donation failed to process through.

{
    "data": {
        "type": "donations",
        "id": "a5e51590-b857-4bfb-9e17-64190ffc618c",
        "attributes": {
            "destination": {
                "recipientId": "321-119219814ABC"
            },
            "funds": {
                "amount": 100,
                "currencyCode": "CAD",
                "paymentType": "DONATION_REPORT",
                "source": "COMPANY"
            },
            "donor": {
                "fullName": "Benevity User",
                "email": "test@benevity.com",
                "receipted": true,
                "address": {
                    "line1": "5555 Calgary St",
                    "line2": "Suite 101",
                    "city": "Calgary",
                    "state": "AB",
                    "zip": "T0A 1B2",
                    "country": "CA"
                }
            },
            "metadata": {
              "vendor-id": "abc-12382",
              "location": "NW Calgary",
              "refill_date": "05/15/2023"
            },
            "state": {
                "processingStatus": "DECLINED",
                "statusLastUpdated": "2021-06-14T21:48:11.455Z",
                "errors": [
                    {
                        "status": "400",
                        "code": "3031",
                        "title": "Bad Request",
                        "detail": "",
                        "source": {
                            "pointer": "cause.321-119219814ABC"
                        },
                        "meta": null
                    }
                ]
            }
        }
    }
}

# 🚀 ☀️ ⭐️ Congratulations! ⭐️ ☀️ 🚀

Fantastic! You have taken action to spread goodness!

← Get Cause Details Make Bulk Company Donations →