Stripe Connect

Most applications can use the basic Stripe integration, the simplest way to add donations to your Stripe flow. However, if you require the use of Stripe Connect, you can use it to send donations directly to Change.

Acquire a Change Conected Account ID

First, you’ll need to get a Change Connected Account ID. This ID is used to forward donations directly to Change. To get your Connected Account ID, send an email to admin@getchange.io. First, we’ll ask you a few questions about your integration to make sure Stripe Connect is the right integration for you.

Add Change to your Stripe Connect integration

There are many ways to process a payment using Stripe. Change works with all of them. For this example, we’ll use a Stripe::PaymentIntent. Let’s say you create a Stripe::PaymentIntent like this:

Stripe::PaymentIntent.create({
  amount: 5_00,
  currency: 'usd',
  payment_method: 'pm_card_visa',
  confirm: true
})

To add a donation to your integration, use the transfer_data field to use Stripe Connect to transfer a portion of the payment to Change (you can also choose to transfer the entire payment):

Stripe::PaymentIntent.create({
  amount: 5_00,
  currency: 'usd',
  payment_method: 'pm_card_visa',
  confirm: true,
  # Add transfer_data to send a portion of the payment to Change.
  transfer_data: {
    destination: 'CHANGE_CONNECTED_ACCOUNT_ID',
    amount: 1_00,
  },
})

Now, when you capture the PaymentIntent, Stripe will automatically transfer $1 to Change.

Tell Change where to send your donations

Now that you’ve sent a transfer to Change, you need to tell Change where to send the donation. To do this, use the Capture a Stripe Transfer endpoint from the Change API.

# Complete a Stripe payment using Stripe Connect. $1 is transfered to Change.
payment_intent = Stripe::PaymentIntent.create({ ... })

# Tell Change where to send your transferred donation.
# You can use any Nonprofit ID from the Change network.
response = HTTParty.post('https://api.getchange.io/api/v1/transfers',
  body: {
    nonprofit_id: 'n_IfEoPCaPqVsFAUI5xl0CBUOx',
    stripe_destination_payment_id: payment_intent.latest_charge.transfer.destination_payment,
  },
  basic_auth: {
    username: 'YOUR_PUBLIC_KEY',
    password: 'YOUR_SECRET_KEY'
  }
)

If you receive a successful 200 response from Change, you’re all set. A donation has been created to the specified nonprofit for the amount you transferred. You can see your donation in the Change dashboard on the donations page.

Other considerations

In this example, we captured the transfer using Change immediately after confirming the Stripe::PaymentIntent. However, you do not need to capture the transfer immediately. Transfers can be captured any time after the are created - for example, in a webhook or batch job.

If you capture transfers asynchronously, you’ll need the ability to remember which nonprofit each transfer is destined for. We recommend using Stripe metadata to store the nonprofit ID.

# Save the nonprofit ID in the Stripe metadata to help capture the transfer asynchronously.
Stripe::PaymentIntent.create({
  ...
  metadata: {
    change_nonprofit_id: 'n_IfEoPCaPqVsFAUI5xl0CBUOx',
  },
})

Webhook

To capture a transfer in a webhook, first identify the Stripe webhook relevant to your implementation. For this example, it would be the payment_intent.succeeded webhook.

# Called when receiving a payment_intent.succeeded webhook from Stripe.
def payment_intent_succeeded(payment_intent)
  # Tell Change where to send your transferred donation.
  # You can use any Nonprofit ID from the Change network.
  response = HTTParty.post('https://api.getchange.io/api/v1/transfers',
    body: {
      nonprofit_id: payment_intent.metadata['change_nonprofit_id'],
      stripe_destination_payment_id: payment_intent.latest_charge.transfer.destination_payment,
    },
    basic_auth: {
      username: 'YOUR_PUBLIC_KEY',
      password: 'YOUR_SECRET_KEY'
    }
  )
end

Batch job

To capture multiple transfers in a periodic batch job, fetch the list of transfers from Stripe that you have not yet captured.

# In a monthly-running job

payment_intents = Stripe::PaymentIntent.list({
  created: { gte: 1.month.ago },
})
payment_intents.each do |pi|
  # Tell Change where to send your transferred donation.
  # You can use any Nonprofit ID from the Change network.
  response = HTTParty.post('https://api.getchange.io/api/v1/transfers',
    body: {
      nonprofit_id: pi.metadata['change_nonprofit_id'],
      stripe_destination_payment_id: pi.latest_charge.transfer.destination_payment,
    },
    basic_auth: {
      username: 'YOUR_PUBLIC_KEY',
      password: 'YOUR_SECRET_KEY'
    }
  ) 
end