Skip to main content

Custom integration using the donation API

To create a donation, you can use our donation REST API. The API allows you to create donations (payment requests) either on behalf of your customers or as corporate donations and then retrieve statistics for the donations made.

This is an overview of how things tie together:

Create API keys​

After the integration is created, you will need to generate a secret key to create donations. We will generate a public key for you automatically that you can use for making client-side requests to our donation API.

Create a secret key for your integration by clicking Create new and store the returned key somewhere safe. You should only use the secret key in your backend requests since it has access to all partner API endpoints. Note that we will only display the secret key once it is created. If you lose the key, you will need to replace your existing one.

Calculate donation amount​

You will need to send in an amount for each payment request. The amount can be calculated differently depending on how and where you want to integrate Milkywire in your business. For instance, if you want to add the possibility for your customers to make a donation at a checkout you can use one of these common strategies:

  • The amount is calculated as a round-up - 97 SEK to 100 SEK = 3 SEK donation.
  • Fixed amount - Donate 20 SEK
  • The amount is calculated as a percentage of the order cost - 5% of 100 SEK = 5 SEK

As donations roll in, you will get access to statistics both in Milkywire's partner portal and directly from the integration API, which you can use to display your impact on your service. At the end of each month, Milkywire will send you a donation payment instruction for the donations booked in our system. The money will be distributed to the organizations you have chosen after we receive your payment.

Create a donation​

Each donation is created by providing a donation amount and currency code via a POST request to /payment-requests. In the response, you will receive a payment request ID that you must pass in when validating the donation in the next step.

You can optionally choose to pass in customer information, donation references or both. Pass in customer information when you would like to make a donation on behalf of a customer. This will connect the the donation to the customers email address and allow them to see the donation in the Milkywire app. If you would like to keep the customer anonymous you can instead pass in an anonymous user id in the partner references object.

Use the partnerReferences property to add donation references to the donations. You can pass in an id, a timestamp or a user id that you want to connect to a specific donation. These will be visible in the partner portal and in the payment instructions.

Override default cause

Donations are automatically distributed to the causes that you defined in the partner portal. You can override the default selection by passing in a causeIds array in the payload with the cause IDs that you want to support in the specific donation.

The POST request can be made with your public key on the client side. Each created donation needs to be verified by the PUT request below to be a part of your donation payment instruction later on.

const response = await fetch("https://api.milkywire.com/partners/v2/payment-requests", {
  method: "POST",
  headers: {
    'Content-Type': 'application/json'
    'x-api-key': '<public key>'
  },
  body: {
    customerDetails: {  // Optional
      firstName: 'Mr',
      lastName: 'Bean'
      email: 'mr@bean.com',
    }
    partnerReference: {  // Optional 
      id: '<unique id>',
      timestamp: '2022-09-14',
      userId: '123',
    }
    amount: 700,
    currencyCode: 'SEK',
    causeIds: ['some-cause-id'] // Optional cause override
  }
});

const { id } = await response.json();

You can read more about the request in the API documentation.

Verify the donation​

Since the endpoint for creating donations is publicly available, you will need to verify the payment request. To do this, you will need your secret key and the payment request-id that you received in the response of the POST request when creating the payment request.

const response = await fetch(
  "https://api.milkywire.com/partners/v2/payment-requests/:payment-request-id",
  {
    method: "PUT",
    headers: {
      authorization: "Bearer <secret key>",
      "Content-Type": "application/json",
    },
    body: {
      status: "SUCCEEDED",
    },
  }
);

You can read more about the request in the API documentation.

Cancel the donation​

If you want to cancel your donation you will need your secret key and the payment request-id that you received in the response of the POST request when creating the payment request. You can cancel a donation as long as it is not yet paid. You do so by passing in the status VOID.

const response = await fetch(
  "https://api.milkywire.com/partners/v2/payment-requests/:payment-request-id",
  {
    method: "PUT",
    headers: {
      authorization: "Bearer <secret key>",
      "Content-Type": "application/json",
    },
    body: {
      status: "VOID",
    },
  }
);

You can read more about the request in the API documentation.

Statistics​

You can easily view all donations made through the API in our partner portal and see some statistics to track your impact. If you want, you can also retrieve the statistics through our API and display them in your services by making a request to the statistics endpoint.

The statistics include aggregation of donations made split by causes. It will also show total donation count and number of unique donors.

const response = await fetch(
  "https://api.milkywire.com/partners/v2/statistics",
  {
    method: "GET",
    headers: {
      authorization: "Bearer <secret key>",
    },
  }
);

This is what an an example response could look like:

{
  "currencyCode": "SEK",
  "donationsPerEntity": [
    {
      "amount": 15000,
      "count": 80,
      "causeId": "<causeId1>"
    },
    {
      "amount": 85000,
      "count": 120,
      "causeId": "<causeId2>"
    }
  ],
  "uniqueDonors": 180,
  "totalDonationAmount": 100000,
  "donationCount": 200
}