Blog

Share this post on Twitter

Photo of Max Lahey

Unifying payment types in the API

Max Lahey on March 11, 2015

As we expand the range of payment types that we support, we’ve released a new API version to unify the interface across payments of all types.

Globally, credit cards are the source of most online payments but they’re far from ubiquitous. Local payment mechanisms (such as China’s prominent e-wallets) power commerce in markets around the world. Meanwhile, novel payment types, from digital currencies to Apple Pay, are establishing new standards for online transactions.

In accepting these new instruments, there’s a lot to be excited about: broader global reach, increased revenue, and improved user experience. We want to make supporting them as easy as possible—hence building this unified API. For essentially all purposes, a payment is a payment regardless of where it came from. Payments of all types behave identically in the API and Dashboard.

Here’s a quick overview of the new API version:

UpdateCreate a charge from a source

Charge objects returned by the API now have a source property in place of the card property. This describes the source that you used for the charge, such as a card or Bitcoin receiver.

You can still create a charge using the card parameter, but it is now superseded by the source parameter.

UpdateManage customer sources

Customer objects now have the sources and default_source properties in place of cards and default_card. Similarly, we’ve introduced the new request parameters source and default_source although the old parameters will be supported indefinitely.

There is a new API endpoint for managing the customer’s payment sources beyond just cards: /v1/customers/{CUSTOMER_ID}/sources.

Here is an example of creating a charge in the new API version:


curl https://api.stripe.com/v1/charges \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -d source=aliacc_4hzzUhIjJ9sZZv \
   -d amount=1000 \
   -d currency=usd

{
  "id": "ch_15aZNk2eZvKYlo2CW82HVvQf",
  "object": "charge",
  "amount": 1000,
  "currency": "usd",
  "source": {
    "id": "aliacc_4hzzUhIjJ9sZZv",
    "object": "alipay_account",
    "created": 1424987420,
    "username": "maidongxi@example.com",
    "reusable": true,
    ...
  },
  ...
}

Switching to the source property means that you don’t need additional code changes to accept the new payment types that we add over time. We’ve made this switch as easy as possible: old API versions include both the old and new properties on all responses. For instance, if you charge a card on an old API version then the charge object will have identical card and source properties. If you charge an Alipay account on an old API version then the card property will be null and the source property will be the Alipay account.

If you have questions or feedback about this change, then we’d love to hear from you!