Connect in one call. We handle the cause.

Send one request when an order is paid or a booking is confirmed. Heartswill records a pledge to the cause assigned to your business and returns a tracking code for your customer. Within about 30 days the delivery comes back as a sealed story with photos.

The causes on Heartswill

Heartswill selects the NGOs and assigns each business one of these causes after review. They are listed here so you can see exactly what your customers' orders fund. Tap one to see its id in the code samples.

Request a partner key

Heartswill reviews every partner before issuing a key. Ecommerce stores, service businesses and enterprises all use the same API. You will hear back by email, usually within two working days.

Choose how you pay

Heartswill never touches money. Every rupee goes from you straight to the bank account of the verified NGO running your chosen cause, such as AnandBodh Foundation. Pick the option that suits your business. You can change it later with the Foundation.

Send your first pledge

Call this from your server after payment succeeds or a booking is confirmed. Never call it from the browser, because your key must stay secret.

Copycurl -X POST https://heartswill.com/api/v1/pledges \
  -H "Authorization: Bearer $HEARTSWILL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"partner_ref":"ORDER-24817","event":"order.paid","amount_inr":500}'

Copyconst res = await fetch("https://heartswill.com/api/v1/pledges", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HEARTSWILL_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    partner_ref: order.id,          // your order or booking reference
    event: "order.paid",
    amount_inr: 500
  })
});
const { data } = await res.json();
// save data.track_code and show data.track_url to the customer

Copy$ch = curl_init("https://heartswill.com/api/v1/pledges");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("HEARTSWILL_KEY"),
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "partner_ref" => $order->id,
    "event" => "order.paid",
    "amount_inr" => 500
  ])
]);
$data = json_decode(curl_exec($ch), true)["data"];

Copyimport os, requests

r = requests.post(
    "https://heartswill.com/api/v1/pledges",
    headers={"Authorization": f"Bearer {os.environ['HEARTSWILL_KEY']}"},
    json={
        "partner_ref": order_id,
        "event": "order.paid",
        "amount_inr": 500,
    },
    timeout=10,
)
data = r.json()["data"]

Response 201 Created for a new pledge or 200 OK when the same reference was already recorded. status is funded for prepaid partners and pledged for monthly and split partners until they settle.

{
  "data": {
    "id": "6f1c…",
    "status": "pledged",
    "project": "girl-education",
    "amount_inr": 500,
    "units": 2,
    "duplicate": false,
    "track_code": "K7Q2MX9D",
    "track_url": "https://platform.heartswill.com/h/K7Q2MX9D"
  }
}

Authentication

Send your partner key as a bearer token. Keys start with hw_live_. Keep the key on your server and in an environment variable. If a key leaks, ask the Foundation to replace it and the old key stops working at once.

Authorization: Bearer hw_live_xxxxxxxxxxxxxxxxxxxxxxxx

Public reads below need no key.

POST /v1/pledges

Records a pledge for one confirmed order or booking.

GET /v1/impact

Your totals, published stories and funding, including your prepaid balance_inr and a low_balance flag. Needs your key. Check it daily if you are prepaid.

POST /v1/pledges/reverse

Reverses a pledge when an order is cancelled or refunded before settlement. Send the same partner_ref you used for the pledge.

{ "partner_ref": "ORDER-24817" }

Settled monthly pledges cannot be reversed because the money has already reached the NGO. Prepaid pledges can be reversed until items are delivered, and the amount goes back to your credit. The reversal is written to the public ledger.

Tracking codes

Every pledge gets an eight-character track_code and a track_url. Show the link on your receipt email, order page or booking confirmation. Customers see their pledge move from recorded to settled to delivered, then the sealed photos when they arrive.

GET /v1/track/{code} returns the same journey as JSON with no key.

Public reads

Errors

Errors share one shape. Show message in your logs and branch on code.

{ "error": { "code": "invalid_amount", "message": "amount_inr must be a whole number of at least 50." } }

Plugins

Badges and widget

One standard widget, drawn from GET /v1/widget. You choose the card and the API decides where every click goes, so links stay correct as Heartswill grows.

Copy<!-- Partner impact card -->
<div data-heartswill-partner="your-partner-id"></div>

<!-- Personal card on a receipt or thank-you page (use the track_code from the pledge response) -->
<div data-heartswill-pledge="K7Q2MX9D"></div>

<script src="https://heartswill.com/embed.js" async></script>

<!-- Verified badge -->
<a data-heartswill-badge="your-partner-id">Every order gives back</a>
<script src="https://platform.heartswill.com/badge.js" async></script>

Feed shape: GET /v1/widget?partner=id or ?pledge=CODE returns mode, the figures for that card and links.open, the page a click should open. Build your own design from it if you prefer.

Go-live checklist