---
title: "Donor widgets"
description: "Let your users give their own money in your product, once or every month, with the payment, the receipt and the charity choice handled by Charitips."
canonical: https://www.charitips.com/docs/widgets/donor
---

# Donor widgets

> Let your users give their own money in your product, once or every month, with the payment, the receipt and the charity choice handled by Charitips.

The donor widgets take a donation your user pays with their own card: they collect the payment and the details for the fiscal receipt, create the donation already paid, and issue the receipt in the user's name. They need the B2C use case on your plan. The use case, step by step, is [Your users give their own money](https://www.charitips.com/docs/use-cases/b2c.md).

> **In short**
>
> - **Signed in**: your server creates a `Donor` for the user, then a donor token, valid one day. The user's donations, recurring donations and receipts are then grouped under their donor.
> - **Guest**: no token, the campaign's `publicKey` is enough. Each donation creates a new donor.
> - Show the charity choice and the payment together, or the payment only, for a charity your product already chose.
> - The card is charged at once: nothing is added to your invoice.

## Signed-in donors

Create the donor once per user with [Create a donor](https://www.charitips.com/docs/api-reference/create-donor.md), with your user's id as `uniqueExternalId`. Then, each time the page opens, your server creates a token with [Create a donor widget token](https://www.charitips.com/docs/api-reference/create-donor-widget-token.md) and passes it to the page.

```bash
curl -X POST https://api.sandbox.charitips.com/v1/authentication/donor/widget \
  -H "Authorization: Bearer $CHARITIPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "donorId": "<donorId>"
  }'
```

### Charity choice and payment

**React**

```tsx
import { DonorCharitySelectionAndPaymentWidget } from '@charitips/embed-react';

export function GiveScreen({ token, publicKey }: { token: string; publicKey: string }) {
  return (
    <DonorCharitySelectionAndPaymentWidget
      token={token}
      publicKey={publicKey}
      onSuccess={({ donationId, charityId, amount }) => {
        // The payment went through. Your server also gets donation_create.
      }}
    />
  );
}
```

**JavaScript**

```javascript
import { createDonorWidget } from '@charitips/embed';

createDonorWidget({
  baseUrl: 'https://embed.sandbox.charitips.com', // https://embed.charitips.com on live
  container: document.querySelector('#give'),
  token: '<donor widget token>',
  type: 'charity-selection-and-payment',
  publicKey: '<campaign publicKey>',
  onSuccess({ donationId, charityId, amount }) {
    // The payment went through. Your server also gets donation_create.
  },
});
```

_Interactive component `<DonorWidget />`: open the page in a browser to use it._

### Payment only

When your product shows the charities itself, pass the chosen `charityId` with the `payment` type (`DonorPaymentWidget` in React). Show enough of each charity for your users to choose: see [Charities and selections](https://www.charitips.com/docs/concepts/charities.md).

```javascript
createDonorWidget({
  baseUrl: 'https://embed.sandbox.charitips.com',
  container: document.querySelector('#give'),
  token: '<donor widget token>',
  type: 'payment',
  publicKey: '<campaign publicKey>',
  charityId: '<charityId>',
});
```

_Interactive component `<DonorWidget />`: open the page in a browser to use it._

### Monthly giving

Add `availableDonationTypes: ['RECURRING']` to the `payment` type: the user sets up a donation every month, charged on their saved card. One type at a time: `['ONE_TIME']` or `['RECURRING']`. The campaign must be a recurring one; see [Monthly giving by your users](https://www.charitips.com/docs/use-cases/recurring-donations.md).

_Interactive component `<DonorWidget />`: open the page in a browser to use it._

## Guests

Without a token, the widgets open with the campaign's `publicKey` only, and each donation creates a new donor. Suited to one-off gifts from people without an account in your product.

- **Charity choice and payment**: the [charity selection widget](https://www.charitips.com/docs/widgets/charity_selection.md) with the `donate` type (`CharitySelectionWidget` in React). `onPaymentSuccess` receives the `donationId`, the `charityId` and the `amount`.
- **Payment only**: `createB2CPaymentWidget` (`B2CPaymentWidget` in React) with the `publicKey` and the `charityId`. `onSuccess` receives the same.

```javascript
import { createWidget } from '@charitips/embed';

createWidget({
  baseUrl: 'https://embed.sandbox.charitips.com',
  container: document.querySelector('#give'),
  publicKey: '<campaign publicKey>',
  type: 'donate',
  onPaymentSuccess({ donationId, charityId, amount }) {
    // Link the donation to your user if you need to: set its externalId with Update a donation.
  },
});
```

_Interactive component `<Widget />`: open the page in a browser to use it._

## Options

- `initialAmount`: the amount shown first.
- `hideSuccessScreen`: skips the thank-you screen, for your product to take over in `onSuccess`.
- `hideImpactIndicator`: hides what the amount funds at the charity.
- `onAmountUpdate`: called with the amount each time the user changes it.
- `size`, `locale`, `id`: see [Options every widget shares](https://www.charitips.com/docs/widgets.md#options-every-widget-shares).

On the sandbox, pay with the [test payment methods](https://www.charitips.com/docs/get-started/sandbox.md#test-payment-methods). Rely on the `donation_create` and `donation_update` webhooks rather than on the callbacks for anything your server must not miss.

## Related

[Your users give their own money](https://www.charitips.com/docs/use-cases/b2c.md), [Billing and fiscal receipts](https://www.charitips.com/docs/concepts/billing-and-receipts.md), [Widgets](https://www.charitips.com/docs/widgets.md).