
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!