"Under the hood" updates to the Stripe Integration
We have just released an upgrade to the RaiseDonors integration with Stripe. While all of this work is mostly “under the hood", it has significantly improved the way that data flows between the two systems. This also sets the stage for us to begin developing new channels for payments on Stripe (ex: ApplePay, GooglePay, ACH, etc).
If you have integrations communicating directly into Stripe, outside of RaiseDonors - a small possibility exists for breaking changes.
Notifications from Stripe
Nothing has changed, but for reference, below is a list of the web-hooks which RaiseDonors receives from Stripe:
- charge.refunded
- customer.subscription.created
- customer.subscription.deleted
- invoice.payment_failed
- invoice.payment_succeeded
When these updates are received, RaiseDonors also makes corresponding updates to the donor data.
Meta-Data
There have been no changes to the names or data points sent to Stripe’s meta data fields. The meta data object exists in multiple levels in Stripe; the customer object, a payment object, and a subscription object.
One Time Charges
The Old Way
A one-time donation would create a payment in Stripe that included metadata, but did not associate the payment with a Stripe customer.
The New Way
One of the most common requests in our Stripe integration has been to associate one-time payments with a customer object and to save the payment method. And we have listened and delivered!
A one-time donation creates a payment in Stripe that includes metadata and associates the payment with a stripe customer and saves the payment method.
The logic to find an existing customer in Stripe is as follows:
- Find all customers in Stripe associated with the donor’s email address.
- If there is no match, then the integration will create a new stripe customer.
- If there is only one match, then the integration will assign this donation to that customer.
- If there is more than one match, the integration will assign this donation to the most recent customer record.
Once that is complete, the donor’s credit card will be added as the default payment source on the stripe customer. The charge is then processed and associated within this Stripe customer account.
New Recurring Charges
The Old Way
A recurring charge would create two tokens from the one credit card.
The first token was used to place a single transaction in Stripe.
If that charge was successful, a second token was used to create a customer and subscription. This token was saved as the default payment source.
No metadata was stored at the customer level.
In this process, there was no lookup to see if the donor already existed as a customer—so a new customer was always created. If this same donor created an additional recurring donation, then an additional Stripe customer was created.
The new subscription was set up to start the following month, on the day of the month the user selected. This meant that the subscription wouldn’t be active until the first charge. The subscription would have a "trial" of “x” number of days until the charge on the following month. Metadata would then be saved at the subscription level.
Payment:
Customer + Subscription:
The New Way
This has been a huge feature request from all of you (our customers) - to ensure all payments and schedules from a donor are associated with a singular stripe customer account.
A recurring charge creates one token from the credit card. The token is added to the Stripe customer. The Stripe customer is not automatically created, but follows the same (new) look-up feature as the one-time charge.
With the Stripe customer and the credit card saved as the default payment source, a payment is created using the customer's default payment source. The payment contains all of the metadata.
Next a subscription is created, with the start date set to the following month, on the day of the month selected by the donor. The subscription contains all the metadata.
1st Payment + Customer + Subscription:
Editing Fund and Amount Designations on Recurring Schedules
Old Way
In the past, editing the amount of a schedule would properly update the schedule in Stripe. But the integration did not update any of the key/value data in the meta-data to reflect the changes.
New Way
When you edit the amount of a schedule…it immediately updates the schedule. The schedule’s metadata will have all relevant fields updated as needed. This keeps both systems current and in sync with requested changes.
Editing Charge Date on Recurring Schedules
Old Way / New Way
Nothing has changed here. It continues to work perfectly in full glory and splendor.
Editing Payment Method and Billing Address
Old Way
If a donor only updated their billing address, then the billing address of their default payment source in Stripe would be updated.
If a donor provided both a new credit card and billing address, then this new information would replace the default payment method in Stripe and be set to default.
New Way
If a donor only updates their billing address, then the address for that specific payment method for the schedule is updated.
If a donor provides both a new credit card and billing address, the integration will create a new payment method in Stripe for the customer
The current "default" payment method for the customer remains unchanged, but the payment method for the schedule will be updated along with the schedule’s meta-data.
The new payment method and billing address is also updated in the local RaiseDonors schedule (mirror) object. And the new information will be properly displayed in the RaiseDonor admin.
Editing Charge Date on Recurring Schedules via the Donor Portal
Old Way
When changing the charge date, the system would make the correct update, but the metadata was not updated.
New Way
When changing the charge date, the system will make the update and update the metadata.
Editing Payment Method and Billing Address via the Donor Portal
Old Way
Update via the Donor Portal worked exactly the same as updates made via the Admin area of RaiseDonors.
New Way
Update via the Donor Portal work exactly the same as updates made via the Admin area of RaiseDonors.