API Suggestion: Charge History REST Endpoint

Patreon Feedback Feedback
1

Suggestion

I would like to suggest a new API endpoint that provides a history of charges for your campaign.

Background

Currently you get data like this:

https://api.patreon.com/oauth2/api/campaigns/XXXX/pledges

{
      "attributes": {
        "amount_cents": 2000,
        "created_at": "2017-06-28T03:46:43.822702+00:00",
        "declined_since": "2017-07-09T13:15:50+00:00",
        "patron_pays_fees": false,
        "pledge_cap_cents": 2000
      },
      "id": "XXX",
      ...
}

With this API, you can kind of reverse engineer that the above user has had no successful payments, if you wait until the 5th of the month or so when payments are complete. That requires a number of assumptions about when charges are attempted, and you can’t grant rewards as charges are made (you have to wait until all charges are done for the month to know for sure there was a decline).

In the case of a successful payment:

{
      "attributes": {
        "amount_cents": 500,
        "created_at": "2017-06-10T11:15:45.253492+00:00",
        "declined_since": null,
        "patron_pays_fees": false,
        "pledge_cap_cents": 500
      },
      "id": "YYY",
      ...
}

You don’t actually know for sure that a payment was charged, just that one hasn’t been declined. If you wait long enough, it’s probably safe to trust this data, but again, there’s a lot of assumptions involved.

Business Justification

I have an external website that uses the OAuth integration to link our accounts with customers’ Patreon accounts. Currently I am using the CSV export to determine charge status each month and sync the user database based on Patreon e-mail. This technique is fine, however, it has these down sides:

  • Manual CSV process means chance for error (uploading wrong CSV to backend, etc)
  • Works okay for once-per-month syncs, but patrons want offsite rewards right away. Even as a small dev, I already have had four requests in the past month to switch to instant-charge as users want the offsite rewards instantly.
  • Customers have to wait until a human is available to do the CSV upload.

Suggested Charge History API Example

https://api.patreon.com/oauth2/api/campaigns/XXXX/chargeHistory

Parameters: An optional parameter will limit the history of charges to the most recent X days. For performance, this could default to 90 days, but ideally a full history could be requested. Pagination could also be supported for large Patreon projects.

[
	{
		"patron_id": "YYY",
		"history": [{
				"amount_cents": 2000,
				"attempted_on": "2017-07-01T03:46:43.822702+00:00",
				"result": "CHARGED"
			},
			{
				"amount_cents": 2000,
				"attempted_on": "2017-06-01T03:46:43.822702+00:00",
				"result": "CHARGED"
			},
			{
				"amount_cents": 2000,
				"attempted_on": "2017-05-01T03:46:43.822702+00:00",
				"result": "CHARGED"
			}
		]
	},
	{
		"patron_id": "XXX",
		"history": [{
			"amount_cents": 2000,
			"attempted_on": "2017-07-01T03:46:43.822702+00:00",
			"result": "DECLINED"
		}]
	}
]

Possible charge results: CHARGED, DECLINED, PENDING, CHARGEBACK, etc

Thank you for your consideration.

2 Likes
2

Wow! Thank you for this excellent rundown. Seriously…

I’m the PM working on the API here and @ellie made sure I saw this. This is super helpful at this stage. I’d like to learn more about what you’re trying to do with the data and understand the full use case. I agree the CSV method is not where we want to be long term.

Can you tell me about what you’re building for patrons? At the experience level and what features this would let you create. How would this information help you accomplish that? Thank you very much!

Tal

1 Like
3

Hi Tal (and Ellie)!

Thanks for getting in touch. Here is way too much information on what I’m building.

The TLDR is I’m trying to use the API as a way to add Patreon payment support to my existing e-commerce enabled website / game account system so as to 1) provide a unified customer experience, 2) support innovative game-specific cloud features and 3) deter piracy.

My project is a text adventure game that has been (slowly!) in development for the past few years in my spare time. At the core of the business model, it could be considered shareware – there is a free demo available (the first three chapters of gameplay), but in order to access the full content (chapter 4+ and various extra in-game features), users must pay a one time fee of $15. Users are encouraged to share the demo version, and so it often winds up on various image sharing sites (it compiles down to a portable Flash/SWF file). This has helped with users organically discovering the game if it meets their interests, and so there is now a small, but passionate, following for the game.

This has worked out well for the past few years on a traditional payment gateway, and I recently added Patreon support as a new revenue stream after receiving some user requests for both Patreon and PayPal support.

At this time, I also added some various monthly rewards to encourage ongoing support. The reward structure looks as follows, with all rewards but the $15 one being Patreon exclusives currently:

  • $5/month - Vote in feature polls, e-mail’ed updates (also: possibly early story snippets in future TBA).
  • $10/month - Player’s name in the credits shown when the game starts up for that month (users can configure what name to show via my website. As it’s a NSFW game, they may prefer a different username to be shown than their default Patreon name, so this defaults to off until configured).
  • $15/one time - Account receives Full Game access, with ongoing stable updates / new chapters when each is complete.
  • $20/month - WIP builds not polished/complete enough for release to wider audience.
  • $25/month - In-game item suggestion (cosmetic/aesthetic clothing items only).
  • $100/month - Player’s name will appear somewhere in the game as a cameo.

Game builds are downloaded from the game website. There are a few reasons for this:

  1. It is a simpler user experience to have one centralized location for everything game related, rather than have this be split across many different websites. For a similar reason, the wiki login also uses the same game account.
  2. As Flash/SWF cookie storage is particularly volitale, and you can’t access both the network and the user’s disk at the same time in AS3, game saves are entirely cloud based. This means the user must have an account if they wish to save/load their progress. As both web, download, and android platforms are supported, this ends up being convenient for users as they can easily migrate their save games across devices.
  3. In order to make it easy for users so they don’t have to manually login, as well as deter piracy, each downloaded full-game build is tied to a particular account through a visible watermarking process.
  4. Using our database allows payment to be confirmed before providing the most critical rewards. With our older store method, we have an almost non-existent chargeback rate of < 0.2%. Meanwhile, just our last month on Patreon, an astonishing 40% of pledges failed to go through. In my case, these are small sample sizes, but hearing stats on larger games, they also appear to have a relatively high decline rate. Confirming transactions encourages users to use real card information and pledge through the end of the month to ensure their pledge goes through, although I have seen some one or two legit users bail out of the monthly wait and switch to the traditional transaction processor instead.
  5. Users are intelligently notified if there is a newer build available via an update check based on their build edition & version.
  6. As time progresses, I have plans to add additional game-specific cloud features that would also be tied to the user’s game account (user generated content exchange, etc).
  7. Since purchase flow is centralized, I can add or modify our existing payment methods easily based on user feedback, tie purchases to google analytics to see what paid user acquisition is working, or even implement things like affiliate programs in future.

Anyway, that’s a long way of indicating that for projects that are coming from a more traditional e-commerce background, it would be ideal if Patreon can offer some user flow similar to traditional payment processors – mainly to offer a simpler user purchase flow and deter piracy.

I am imagining a system similar to PayPal’s purchase flow, where after selecting payment gateway in our checkout flow, the user is directed to a themed Patreon checkout page where they can either set up a new Patreon account or login to an existing one. After that, they would be able to confirm/adjust their pledge level, and receive information reminding them of the recurring nature of the platform. Finally, payment would be charged, and on success, an IPN call sent to the creator’s backend system so they can reconcile their internal database. (Ideally an IPN could also be sent if there is later a chargeback).

In this way, we can offer users a choice of the payment method and style that works best for them. As part of this, would definitely still want to show users the value of Patreon’s exclusive recurring rewards, as well as make it easy for them to use their existing Patreon accounts.

However, as a shorter term solution, just having API access to charge results would be a great start since the charge information would allow me to know whether I should vend the full game reward – thus allowing users to get access to their rewards right away.

Hope that helps!

~ Sky

2 Likes
4

Wow! I’d like to drill down on your last paragraph as it sounds most immediately relevant to what we’re working on short-term - can you connect it for me, how is history valuable to your game vs. current status? What would the practical implications be?

Thank you for spelling it out and your patience,

Tal

5

For sure, I’m happy to help.

History helps with seeing if there was ever a $15 or greater confirmed purchase so as to unlock the full game. It also would allow revocation in case the purchase is later charged back.

However, if I query frequently (or receive programmatic notifications), I could receive most of the same information based on the current state.

In a current state API, I think this is the information I would need:

  • Confirmed charged amount this month (not merely pledged)
  • Time of the charge or time of expiry (so as to know when the billing cycle rolls over)

If I either query frequently or after a notification, I’d be able to see the confirmed purchase and unlock the game at the appropriate level depending on charge amount.

Figuring out chargebacks makes this a little murkier, since that information extends beyond the current month as these can happen months later – plus if a customer does a chargeback on a $5 reward charge, but not the $15 game charge, they should ideally still have access to the game since they paid for it. History makes it easier to reconcile for that case, but it’s not the only solution.

~ Sky

1 Like
6

Hey Sky, gotcha. And sorry about the delay.

The good news: Internally we’ve straightened out our backend to make this class of requests easier for our product teams to use in the UI, so the hard part is well on its way.

What’s left after that is for our platform API team to surface this externally to partners like yourself.

The bleh news: There’s a few things we prioritized ahead of this around security/infrastructure that we’ll work on first, so I wouldn’t plan around this anytime in the coming months. However, I do want to confirm it is on its way and you are not alone in requesting this kind of information.

Probably not the ideal answer - I hope that does give you a sense that this is something we totally agree on should be easier :slight_smile:

Tal

1 Like
7

Got it. Thanks for the honest answer, it’ll help me set reasonable expectations with customers who have been asking about instant charge that it may be possible for us to hook up eventually, but not in the near term. We’re not blocked by this, so we’ll keep proceeding as we have been and hope for it to come up on the roadmap when it can. Totally understand the need to prioritize security and lay the right technical foundation first. I appreciate all the info and communication!

~ Sky

1 Like