Donation API

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.

note

Any customer information, or information on a purchase connected to the donation is optional, and not needed to use the API.

Use the partnerReferences property to add donation references to the donations. You can pass in a reference 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.

Overriding your default causes

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.

POST requests to the payment requests endpoint 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 instructions 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',
    }
    amountInCents: 700,
    currencyCode: 'SEK',
    causeIds: ['some-cause-id'] // Optional cause override
  }
});

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

You can read more about the payment requests endpoint in the API documentation.

---

Verify the donation

Since the endpoint for creating donations is publicly available, you will need to validate payment request from your backend. To do this, you will need your secret key and the payment request-id that you received in the response from 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 a 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 for 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.