Stripe Payments

Add round-up or fixed donations to your Stripe payments by integrating your platform with Change

This guide will walk through each step of integrating Stripe with Change to add donations to your existing payment flow.

1. Create a Change account

Sign up for Change, then visit the Developers page. Click the “View test keys” switch to see your sandbox keys. Use these keys while building and testing your Change integration.

2. Adjust the payment amount

To include a donation in your existing payment flow, adjust the payment amount to include the donation.

For example, if you’re using Stripe Checkout, add a donation line item to the payment:

# Add a donation to the payment amount
Stripe::Checkout::Session.create({
  line_items: [
    {
      price_data: {
        currency: 'usd',
        product_data: { name: 'Donation to Make-a-Wish' },
        unit_amount: 2000,
      },
      quantity: 1,
    },
    ...
  ],
  mode: 'payment',
  success_url: 'https://example.com/success'
})

If you’re not using Stripe Checkout, the same principle applies to other Stripe products: adjust the payment amount to include the donation you’d like to make.

3. Listen for the payment_intent.succeeded webhook

When a payment is successful, Stripe sends a payment_intent.succeeded webhook. This works for many Stripe flows including Checkout, Subscriptions, and more. Listen for this webhook to create a donation with Change.

If you’ve never used Stripe webhooks before, visit the Stripe docs to learn how to set up webhooks for your application. If you prefer not to use webhooks, see the alternatives to webhooks section below.

4. Create the donation with Change

When you receive the payment_intent.succeeded webhook, create a donation with Change using the Create a donation endpoint.

# Using Sinatra. (This code is boilerplate from the Stripe docs)
post '/webhook' do
  payload = request.body.read
  event = Stripe::Event.construct_from(
    JSON.parse(payload, symbolize_names: true)
  )

  # Handle the event
  case event.type
  when 'payment_intent.succeeded'
    # Create a Donation
    HTTParty.post("https://api.getchange.io/api/v1/donations",
      body: {
        amount: 2000, # $20.00
        nonprofit_id: 'n_B7e7Xu5RFvYHGLHDCSMQ5Yck',
        funds_collected: true,
      },
      headers: headers,
      basic_auth: { username: 'YOUR_PUBLIC_KEY', password: 'YOUR_SECRET_KEY' }
    )
  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end

In the example above, a $20 donation is created when a payment is successful. Change will keep track of the donations you create. Each month, you’ll receive an invoice from Change for the total amount of donations you’ve created. When you pay the invoice, Change will automatically distribute the donations to the nonprofits you’ve selected.

Donate to multiple nonprofits

In the example above, every donation is to a single nonprofit, but you can adjust the donation amount, nonprofit, and more. Donate to other nonprofits by changing the nonprofit_id field. You can find nonprofit IDs in the Change dashboard on the nonprofit search page.

If you allow for different donation amounts or nonprofits, keep track of these options in your application. Every payment flow is different. Common approaches include:

• Hardcoded — If you only allow donations to a single nonprofit, you can hardcode the nonprofit ID in your application.
• User input — If you allow users to choose the nonprofit, you can store the nonprofit ID in the metadata of the payment. When you receive the webhook, read the metadata to determine the nonprofit. Many Stripe products support metadata, including Checkout, PaymentIntents, Subscriptions, and more.
• SKU based — If you associate nonprofits with certain products, you can use the product ID or SKU to determine the nonprofit in your server code. When you receive the webhook, look up the product ID or SKU to determine the nonprofit.

Alternatives to webhooks

If you don’t want to use webhooks, you can create donations in a batch job or other asynchronous process. You can create donations at any time after the payment is successful. Some prefer to create donations in a job at the end of the day by looping over their successful payments from that day.