search

stripe / openapi

An OpenAPI specification for the Stripe API.
MIT License
394 stars 123 forks source link

refund vs. payment_refund #32

Closed jleclanche closed 3 years ago

jleclanche commented 6 years ago

Looking through the spec I don't understand why there is both a refund and a payment_refund type of object. They don't seem to have any concrete difference even. What's this about?

brandur-stripe commented 6 years ago

There's a few different ideas here. In general, we use "charge" to refer specifically to a credit card charge and "payment" to refer to a more general form of money movement that may have a different type of source. In practice from a user's perspective however, both are created via /v1/charges, and the API makes an effort to present a "unified" payments interface in places like refunds where either instrument is made to look the same.

I'd love to get this unwound at some point so that there's just a single API resource for refunds, but in practice it's either going to involve waiting longer for some technical debt to be unwound server-side, or a somewhat ugly hack in the OpenAPI generator. For now, I'd prefer to opt for the former, but we can revisit that decision if it looks like it's going to be a very long time before it ever gets done.

jleclanche commented 6 years ago

Does this make a difference to end-users of the API? I've never noticed those differences you were talking about, so it sounds it's just two types of refund objects internally, which are undistinguishable in the API, correct?

And /v1/refunds lists all of it, yeah?

brandur-stripe commented 6 years ago

Does this make a difference to end-users of the API? I've never noticed those differences you were talking about, so it sounds it's just two types of refund objects internally, which are undistinguishable in the API, correct?

Yeah, there are some differences, but it would be better if we weren't exposing the distinction publicly.

And /v1/refunds lists all of it, yeah?

Yep, both are shaped into the same interface so that they can unified on this endpoint.

jleclanche commented 6 years ago

Could you explain some of the differences?

richardm-stripe commented 3 years ago

Closing as it looks like as of https://github.com/stripe/openapi/commit/b9ff093112c091811b1cf452c281a778100daebb#diff-532f75e4d5235966f11914b18755f9f0709cab7de386fa7318ca94eedbb61323L6524 payment_refund is no more.