Refunds details sometimes in data object, sometimes not.

[Julien]

Hey,
I have an issue with a refund object passed in an event's data.object.

99% of the refunds I get are returned as lists, which I understand are arrays. They look like this:

   "refunds": {
      "object": "list",
      "data": [
        {
          "id": "re_1B5KWIE7R8BZB6Yn6GwbyrFR",
          "object": "refund",
          "amount": 8000,
          "balance_transaction": "txn_1B5KWIE7R8BZB6Ynh5ajRnMw",
          "charge": "ch_1B3O76E7R8BZB6Yn2QYduSdu",
          "created": 1506199598,
          "currency": "usd",
          "metadata": {
          },
          "reason": "requested_by_customer",
          "receipt_number": null,
          "status": "succeeded"
        }
      ],
      "has_more": false,
      "total_count": 1,
      "url": "/v1/charges/ch_1B3O76E7R8BZB6Yn2QYduSdu/refunds"
    },

However, I have an issue with 1 event in particular, which returns the refund's details like this, which is not passed in refunds.data, but directly in refunds.
This is also the 1st refund I see with a reason: duplicate. Not sure what that means.

  "refunds": [
    {
      "id": "re_BbVaXPz4KV3DLV",
      "object": "refund",
      "amount": 63900,
      "balance_transaction": "txn_BbVa5kVmzkDOpd",
      "charge": "ch_BIsd9VvNQv9iv9",
      "created": 1508337029,
      "currency": "usd",
      "metadata": {},
      "reason": "duplicate",
      "receipt_number": null,
      "status": "succeeded"
    }
  ],

Questions:

• Is it normal that refunds sometimes returns a data object, sometimes not? According to the API doc, it's supposed to be a hash with a data property that contains an array. I might have misunderstood what a list is.
• What does "reason: duplicate" means for a refund? If my objective is to list refunds made on purpose, does this count as a refund my user would care about, or is it some kind of internal operation I can just ignore?
  

Thanks,
Julien

[Remi J.]

Hey Julien,

Thanks for the questions! Let me answer inline to make this a bit clearer!

 

Questions:

• Is it normal that refunds sometimes returns a data object, sometimes not? According to the API doc, it's supposed to be a hash with a data property that contains an array. I might have misunderstood what a list is.

This is usually due to a difference in API version between the two requests. The refunds property is a hash but it was not always the case. Before the API version 2014-06-17, the `refunds` property was an array instead of a hash which is documented here [1]:

Change refunds property on charge responses from an array to a sublist object, which contains the has_more, url, and data parameters.

The refunds you mentioned live in 2 different Stripe accounts. The first one is on a recent API version while the second one is on a really old API version from 2012. It's expected that the API would behave differently on both accounts and a lot of things have changed in 5 years.

When making API requests on behalf of different accounts, you should make sure to always force the API version that you have built your code against. This is done using the `Stripe-Version` header as documented here [2]. Doing so ensures that your code behaves the same way no matter the API version set on each account.

Finally, if you're making API requests on behalf of different accounts because you are building a service, for example to analyze their Stripe data, you should instead use Stripe Connect [3]. This would allow you to get access to each account separately while making all API requests through your own account and with your own API version. You can read more about this here [4].

• What does "reason: duplicate" means for a refund? If my objective is to list refunds made on purpose, does this count as a refund my user would care about, or is it some kind of internal operation I can just ignore?
  

This is here to indicate that you refunded a charge because there was a duplicate one created by mistake. It's hard to say if your users would care about this though as it might depend on their business.

Hope this helps!

Remi

[1] https://stripe.com/docs/upgrades#2014-06-17 

[2] https://stripe.com/docs/api#versioning

[3] https://stripe.com/docs/connect

[4] https://stripe.com/docs/building-integrations

[Julien]

Hey Remi,

Thanks for the thorough answers.

This is usually due to a difference in API version between the two requests.

Weird, as both requests were made from the same version of code. Not run at the same time, but definitely using the same code, which already forces an API version:

stripe.setApiVersion('2017-04-06');

However, I noticed that we lag behind both latest API version and latest Node library.

I'll update both and see if it fixes the issue.

---

Regarding Stripe Connect: yes, we're aware of this option — and actually use it on another service we made — but can't properly use it in this case. We're making a desktop app, and don't want to involve a 3rd-party server to handle oAuth. See the answer my partner made here :)

https://groups.google.com/a/lists.stripe.com/d/msg/api-discuss/7GzcLYSe9-s/J9WA8G3BAAAJ

Thanks!

Julien

[Julien]

Hm, I've just noticed the following from the doc on setting the API version:

If your library relies on webhook events, their data format and structure depend on the user’s account API version.

Our app gets most information from events, which it expands to get e.g. refunds.

Could this means that objects expanded from events have the same data format and structure than the webhooks, which depend on the API version? Which would explain why forcing the API version using the node library does not work?

In such case, I understand there's only 2 solutions:

- ask the user to upgrade its own API version

- use Stripe Connect so we're sure we're using our API version (would that work even for events?)

Thanks!

Julien

Le mardi 7 novembre 2017 15:07:06 UTC+1, Remi J. a écrit :

[Remi J.]

Hey Julien,

That's correct. The event payload is always based on the API version set on the account at the time the event was generated. Even when forcing an API version, you will still get the payload as it was when it was created.

In this situation you should retrieve the corresponding charge/refund via the API instead of relying on the event so that your code always works no matter which API version their account is set to.

Hope this helps!

Remi

--
You received this message because you are subscribed to the Google Groups "Stripe API Discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-discuss+unsubscribe@lists.stripe.com.
To post to this group, send email to api-d...@lists.stripe.com.
Visit this group at https://groups.google.com/a/lists.stripe.com/group/api-discuss/.

[Julien]

Ok, thanks for the clarification Remi.

We'll see what's best in our case.

Cheers!

Julien

To unsubscribe from this group and stop receiving emails from it, send an email to api-discuss...@lists.stripe.com.