Skip to content
Aller au contenu
Charitips

Integrate

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.

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, with your user's id as uniqueExternalId. Then, each time the page opens, your server creates a token with Create a donor widget token and passes it to the page.

POST /v1/authentication/donor/widget
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>"  }'
Built from the spec and the API code

Request bodies are written for this docs and checked against the API's validation; ids in angle brackets are placeholders. Response values are placeholders built from the schema.

Charity choice and payment

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.      }}    />  );}
Loading the widget from the sandbox
Live widget, connected to the sandbox. Payments take test cards and move no money.

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.

JavaScript
createDonorWidget({  baseUrl: 'https://embed.sandbox.charitips.com',  container: document.querySelector('#give'),  token: '<donor widget token>',  type: 'payment',  publicKey: '<campaign publicKey>',  charityId: '<charityId>',});
Loading the widget from the sandbox
Live widget, connected to the sandbox. Payments take test cards and move no money.

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.

Loading the widget from the sandbox
Live widget, connected to the sandbox. Payments take test cards and move no money.

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 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.  },});
Loading the widget from the sandbox
Live widget, connected to the sandbox. Payments take test cards and move no money.

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.

On the sandbox, pay with the 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, Billing and fiscal receipts, Widgets.