Transitioning to the Payment Methods API

Learn about the differences compared to Sources and Tokens.

The Payment Methods API replaces the existing Tokens and Sources APIs as the recommended way for integrations to collect and store payment information. It works with the Payment Intents API to create payments for a wide range of payment methods.

Transitioning to the Payment Methods API

The main difference between the Payment Methods and Sources APIs is that Sources describes transaction state through the status property, which means that each Source object must be transitioned to a chargeable state before it can be used for a payment. In contrast, a PaymentMethod is stateless, relying on the PaymentIntent object to represent payment state.

We are continually adding payment methods support on the Payment Methods API. In the meantime, the Sources API may be right for payment methods not yet supported on the Payment Methods API.

Flows	Payment Methods with Payment Intents API	Tokens or Sources with Charges API
Cards	Supported	Supported on Tokens Not recommended on Sources
Dynamic 3D Secure	Supported	Not supported
Card present	Supported	Not supported
Alipay	Planned	Supported
ACH Debit	Planned	Supported on Tokens Not supported on Sources
ACH Credit Transfer	Planned	Beta
Bancontact	Supported	Supported
BECS Direct Debit (Australia)	Supported	Not supported
EPS	Supported	Beta
giropay	Supported	Supported
iDEAL	Supported	Supported
Multibanco	Planned	Beta
Przelewy24	Supported	Beta
SEPA Direct Debit	Supported	Supported
SOFORT	Planned	Supported
WeChat Pay	Planned	Beta

If your integration currently uses the Sources or Tokens API, follow the migration guide to transition to the Payment Intents and Payment Methods APIs.

When you have chosen the API to integrate against, our guide to payment methods may help you determine the right payment method types to support for your customers. This guide includes detailed descriptions of each payment method and describes the differences in the customer-facing flows, along with the geographic regions where they are most relevant. You can enable any payment method available to you within the Dashboard. Activation is generally instantaneous and does not require additional contracts nor include a lengthy process.

Compatibility with Sources and cards

If you previously collected customer payment details with Stripe using cards or Sources, you can start using the Payment Methods API immediately without migrating any payment information for payment types that are available on the Payment Methods API.

Compatible payment instruments that have been saved to a Customer are usable in any API that accepts a PaymentMethod object. For example, you can use a saved card as a PaymentMethod when creating a PaymentIntent:

curl https://api.stripe.com/v1/payment_intents \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "payment_method_types[]"=card \
  -d amount=1099 \
  -d currency=usd \
  -d customer=cus_HlzLuEmdFPUtpz \
  -d payment_method=card_1HCRMz2eZvKYlo2COJaV25dq
curl https://api.stripe.com/v1/payment_intents \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d "payment_method_types[]"=card \
  -d amount=1099 \
  -d currency=usd \
  -d customer=cus_HlzLuEmdFPUtpz \
  -d payment_method=card_1HCRMz2eZvKYlo2COJaV25dq

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

Stripe::PaymentIntent.create({
  payment_method_types: ['card'],
  amount: 1099,
  currency: 'usd',
  customer: 'cus_HlzLuEmdFPUtpz',
  payment_method: 'card_1HCRMz2eZvKYlo2COJaV25dq',
})
# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

Stripe::PaymentIntent.create({
  payment_method_types: ['card'],
  amount: 1099,
  currency: 'usd',
  customer: 'cus_HlzLuEmdFPUtpz',
  payment_method: 'card_1HCRMz2eZvKYlo2COJaV25dq',
})

# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

stripe.PaymentIntent.create(
  payment_method_types=['card'],
  amount=1099,
  currency='usd',
  customer='cus_HlzLuEmdFPUtpz',
  payment_method='card_1HCRMz2eZvKYlo2COJaV25dq',
)
# Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

stripe.PaymentIntent.create(
  payment_method_types=['card'],
  amount=1099,
  currency='usd',
  customer='cus_HlzLuEmdFPUtpz',
  payment_method='card_1HCRMz2eZvKYlo2COJaV25dq',
)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

\Stripe\PaymentIntent::create([
  'payment_method_types' => ['card'],
  'amount' => 1099,
  'currency' => 'usd',
  'customer' => 'cus_HlzLuEmdFPUtpz',
  'payment_method' => 'card_1HCRMz2eZvKYlo2COJaV25dq',
]);
// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

\Stripe\PaymentIntent::create([
  'payment_method_types' => ['card'],
  'amount' => 1099,
  'currency' => 'usd',
  'customer' => 'cus_HlzLuEmdFPUtpz',
  'payment_method' => 'card_1HCRMz2eZvKYlo2COJaV25dq',
]);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

PaymentIntentCreateParams params =
  PaymentIntentCreateParams.builder()
    .setAmount(1099L)
    .setCurrency("usd")
    .addPaymentMethodType("card")
    .setCustomer("cus_HlzLuEmdFPUtpz")
    .setPaymentMethod("card_1HCRMz2eZvKYlo2COJaV25dq")
    .build();

PaymentIntent paymentIntent = PaymentIntent.create(params);
// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

PaymentIntentCreateParams params =
  PaymentIntentCreateParams.builder()
    .setAmount(1099L)
    .setCurrency("usd")
    .addPaymentMethodType("card")
    .setCustomer("cus_HlzLuEmdFPUtpz")
    .setPaymentMethod("card_1HCRMz2eZvKYlo2COJaV25dq")
    .build();

PaymentIntent paymentIntent = PaymentIntent.create(params);

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const paymentIntent = await stripe.paymentIntents.create({
  payment_method_types: ['card'],
  amount: 1099,
  currency: 'usd',
  customer: 'cus_HlzLuEmdFPUtpz',
  payment_method: 'card_1HCRMz2eZvKYlo2COJaV25dq'
});
// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

const paymentIntent = await stripe.paymentIntents.create({
  payment_method_types: ['card'],
  amount: 1099,
  currency: 'usd',
  customer: 'cus_HlzLuEmdFPUtpz',
  payment_method: 'card_1HCRMz2eZvKYlo2COJaV25dq'
});

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &stripe.PaymentIntentParams{
  PaymentMethodTypes: stripe.StringSlice([]string{
    "card",
  }),
  Amount: stripe.Int64(1099),
  Currency: stripe.String(string(stripe.CurrencyUSD)),
  Customer: stripe.String("cus_HlzLuEmdFPUtpz"),
  PaymentMethod: stripe.String("card_1HCRMz2eZvKYlo2COJaV25dq"),
}
pi, _ := paymentintent.New(params)
// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &stripe.PaymentIntentParams{
  PaymentMethodTypes: stripe.StringSlice([]string{
    "card",
  }),
  Amount: stripe.Int64(1099),
  Currency: stripe.String(string(stripe.CurrencyUSD)),
  Customer: stripe.String("cus_HlzLuEmdFPUtpz"),
  PaymentMethod: stripe.String("card_1HCRMz2eZvKYlo2COJaV25dq"),
}
pi, _ := paymentintent.New(params)

// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var options = new PaymentIntentCreateOptions
{
  PaymentMethodTypes = new List<string>
  {
    "card",
  },
  Amount = 1099,
  Currency = "usd",
  Customer = "cus_HlzLuEmdFPUtpz",
  PaymentMethod = "card_1HCRMz2eZvKYlo2COJaV25dq"
};
var service = new PaymentIntentService();
service.Create(options);
// Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var options = new PaymentIntentCreateOptions
{
  PaymentMethodTypes = new List<string>
  {
    "card",
  },
  Amount = 1099,
  Currency = "usd",
  Customer = "cus_HlzLuEmdFPUtpz",
  PaymentMethod = "card_1HCRMz2eZvKYlo2COJaV25dq"
};
var service = new PaymentIntentService();
service.Create(options);

Remember to provide the customer ID that your compatible payment instrument is saved to when attaching the object to a PaymentIntent.

You can retrieve all saved compatible payment instruments through the Payment Methods API.

{
  "id": "card_1EBXBSDuWL9wT9brGOaALeD2",
  "object": "card",
  "address_city": "San Francisco",
  "address_country": "US",
  "address_line1": "1234 Fake Street",
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,  "address_zip_check": null,
  "brand": "Visa",
  "country": "US",
  "customer": "#{customer_id}",
  "cvc_check": null,
  "dynamic_last4": null,
  "exp_month": 8,
  "exp_year": 2024,
  "fingerprint": "53v265akSHAnIk1X",
  "funding": "credit",
  "last4": "4242",
  "metadata": {
  },
  "name": null,
  "tokenization_method": null
}
{
  "id": "card_1EBXBSDuWL9wT9brGOaALeD2",
  "object": "card",
  "address_city": "San Francisco",
  "address_country": "US",
  "address_line1": "1234 Fake Street",
  "address_line1_check": null,
  "address_line2": null,
  "address_state": null,
  "address_zip": null,

See all 26 lines "address_zip_check": null, "brand": "Visa", "country": "US", "customer": "#{customer_id}", "cvc_check": null, "dynamic_last4": null, "exp_month": 8, "exp_year": 2024, "fingerprint": "53v265akSHAnIk1X", "funding": "credit", "last4": "4242", "metadata": { }, "name": null, "tokenization_method": null }

{
  "id": "card_1EBXBSDuWL9wT9brGOaALeD2",
  "object": "payment_method",
  "billing_details": {
    "address": {
      "city": "San Francisco",
      "country": "US",
      "line1": "1234 Fake Street",
      "line2": null,
      "postal_code": null,      "state": null
    },
    "name": null,
    "phone": null,
    "email": null
  },
  "card": {
    "brand": "visa",
    "checks": {
      "address_line1_check": null,
      "address_postal_code_check": null,
      "cvc_check": null
    },
    "country": "US",
    "exp_month": 8,
    "exp_year": 2024,
    "fingerprint": "53v265akSHAnIk1X",
    "funding": "credit",
    "last4": "4242",
    "three_d_secure_usage": {
      "supported": true
    },
    "wallet": null
  },
  "created": 123456789,
  "customer": "cus_EepWxEKrgMaywv",
  "livemode": false,
  "metadata": {
  },
  "type": "card"
}
{
  "id": "card_1EBXBSDuWL9wT9brGOaALeD2",
  "object": "payment_method",
  "billing_details": {
    "address": {
      "city": "San Francisco",
      "country": "US",
      "line1": "1234 Fake Street",
      "line2": null,
      "postal_code": null,

See all 41 lines "state": null }, "name": null, "phone": null, "email": null }, "card": { "brand": "visa", "checks": { "address_line1_check": null, "address_postal_code_check": null, "cvc_check": null }, "country": "US", "exp_month": 8, "exp_year": 2024, "fingerprint": "53v265akSHAnIk1X", "funding": "credit", "last4": "4242", "three_d_secure_usage": { "supported": true }, "wallet": null }, "created": 123456789, "customer": "cus_EepWxEKrgMaywv", "livemode": false, "metadata": { }, "type": "card" }

{
  "id": "src_1AhIN74iJb0CbkEwmbRYPsd4",
  "object": "source",
  "amount": null,
  "client_secret": "src_client_secret_sSPHZ17iQG6j9uKFdAYqPErO",
  "created": 1500471469,
  "currency": null,
  "flow": "none",
  "livemode": false,
  "metadata": {  },
  "owner": {
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line1": "Nollendorfstraße 27",
      "line2": null,
      "postal_code": "10777",
      "state": null
    },
    "email": "jenny.rosen@example.com",
    "name": "Jenny Rosen",
    "phone": null,
    "verified_address": null,
    "verified_email": null,
    "verified_name": null,
    "verified_phone": null
  },
  "status": "chargeable",
  "type": "card",
  "usage": "reusable",
  "card": {
    "exp_month": 4,
    "exp_year": 2024,
    "address_line1_check": "unchecked",
    "address_zip_check": "unchecked",
    "brand": "Visa",
    "country": "US",
    "cvc_check": "unchecked",
    "funding": "credit",
    "last4": "4242",
    "three_d_secure": "optional",
    "tokenization_method": null,
    "dynamic_last4": null
  }
}
{
  "id": "src_1AhIN74iJb0CbkEwmbRYPsd4",
  "object": "source",
  "amount": null,
  "client_secret": "src_client_secret_sSPHZ17iQG6j9uKFdAYqPErO",
  "created": 1500471469,
  "currency": null,
  "flow": "none",
  "livemode": false,
  "metadata": {

See all 46 lines }, "owner": { "address": { "city": "Berlin", "country": "DE", "line1": "Nollendorfstraße 27", "line2": null, "postal_code": "10777", "state": null }, "email": "jenny.rosen@example.com", "name": "Jenny Rosen", "phone": null, "verified_address": null, "verified_email": null, "verified_name": null, "verified_phone": null }, "status": "chargeable", "type": "card", "usage": "reusable", "card": { "exp_month": 4, "exp_year": 2024, "address_line1_check": "unchecked", "address_zip_check": "unchecked", "brand": "Visa", "country": "US", "cvc_check": "unchecked", "funding": "credit", "last4": "4242", "three_d_secure": "optional", "tokenization_method": null, "dynamic_last4": null } }

{
  "id": "card_1EBXBSDuWL9wT9brGOaALeD2",
  "object": "payment_method",
  "billing_details": {
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line1": "Nollendorfstraße 27",
      "line2": null,
      "postal_code": "10777",      "state": null
    },
    "name": "Jenny Rosen",
    "phone": null,
    "email": "jenny.rosen@example.com"
  },
  "card": {
    "brand": "visa",
    "checks": {
      "address_line1_check": null,
      "address_postal_code_check": null,
      "cvc_check": null
    },
    "country": "US",
    "exp_month": 4,
    "exp_year": 2024,
    "fingerprint": "53v265akSHAnIk1X",
    "funding": "credit",
    "last4": "4242",
    "three_d_secure_usage": {
      "supported": true
    },
    "wallet": null
  },
  "created": 1500471469,
  "customer": "#{customer_id}",
  "livemode": false,
  "metadata": {
  },
  "type": "card"
}
{
  "id": "card_1EBXBSDuWL9wT9brGOaALeD2",
  "object": "payment_method",
  "billing_details": {
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line1": "Nollendorfstraße 27",
      "line2": null,
      "postal_code": "10777",

See all 41 lines "state": null }, "name": "Jenny Rosen", "phone": null, "email": "jenny.rosen@example.com" }, "card": { "brand": "visa", "checks": { "address_line1_check": null, "address_postal_code_check": null, "cvc_check": null }, "country": "US", "exp_month": 4, "exp_year": 2024, "fingerprint": "53v265akSHAnIk1X", "funding": "credit", "last4": "4242", "three_d_secure_usage": { "supported": true }, "wallet": null }, "created": 1500471469, "customer": "#{customer_id}", "livemode": false, "metadata": { }, "type": "card" }

{
  "id": "src_GABJMyRlgnQDAjVYf0xCpa8o",
  "object": "source",
  "amount": null,
  "client_secret": "src_client_secret_GABJMyRlgnQDAjVYf0xCpa8o",
  "created": 1573256458,
  "currency": "eur",
  "flow": "none",
  "livemode": false,
  "mandate": {    "acceptance": {
      "date": null,
      "ip": null,
      "offline": null,
      "online": {
        "date": 1573256458,
        "ip": "127.0.0.1",
        "user_agent": "device"
      },
      "status": "accepted",
      "type": "online",
      "user_agent": null
    },
    "amount": null,
    "currency": null,
    "interval": "variable",
    "notification_method": "stripe_email",
    "reference": "QCHUUDXBBLBS3AM0",
    "url": "https://hooks.stripe.com/adapter/sepa_debit/file/src_1Fch4YEafOxC3pa8VYi8KNox/src_client_secret_G8z2C1kK3xteT9d7mJOlnU4y"
  },
  "metadata": {
  },
  "owner": {
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line1": "Nollendorfstraße 27",
      "line2": null,
      "postal_code": 10777,
      "state": null
    },
    "email": "jenny.rosen@example.com",
    "name": "Jenny Rosen",
    "phone": null,
    "verified_address": null,
    "verified_email": null,
    "verified_name": null,
    "verified_phone": null
  },
  "sepa_debit": {
    "last4": "3000",
    "bank_code": "22222222",
    "fingerprint": "oAnAztLiWFEnfcn6",
    "country": "DE",
    "mandate_reference": "QCHUUDXBBLBS3AM0",
    "mandate_url": "https://hooks.stripe.com/adapter/sepa_debit/file/src_1Fch4YEafOxC3pa8VYi8KNox/src_client_secret_G8z2C1kK3xteT9d7mJOlnU4y",
    "branch_code": null
  },
  "statement_descriptor": null,
  "status": "chargeable",
  "type": "sepa_debit",
  "usage": "reusable"
}
{
  "id": "src_GABJMyRlgnQDAjVYf0xCpa8o",
  "object": "source",
  "amount": null,
  "client_secret": "src_client_secret_GABJMyRlgnQDAjVYf0xCpa8o",
  "created": 1573256458,
  "currency": "eur",
  "flow": "none",
  "livemode": false,
  "mandate": {

See all 63 lines "acceptance": { "date": null, "ip": null, "offline": null, "online": { "date": 1573256458, "ip": "127.0.0.1", "user_agent": "device" }, "status": "accepted", "type": "online", "user_agent": null }, "amount": null, "currency": null, "interval": "variable", "notification_method": "stripe_email", "reference": "QCHUUDXBBLBS3AM0", "url": "https://hooks.stripe.com/adapter/sepa_debit/file/src_1Fch4YEafOxC3pa8VYi8KNox/src_client_secret_G8z2C1kK3xteT9d7mJOlnU4y" }, "metadata": { }, "owner": { "address": { "city": "Berlin", "country": "DE", "line1": "Nollendorfstraße 27", "line2": null, "postal_code": 10777, "state": null }, "email": "jenny.rosen@example.com", "name": "Jenny Rosen", "phone": null, "verified_address": null, "verified_email": null, "verified_name": null, "verified_phone": null }, "sepa_debit": { "last4": "3000", "bank_code": "22222222", "fingerprint": "oAnAztLiWFEnfcn6", "country": "DE", "mandate_reference": "QCHUUDXBBLBS3AM0", "mandate_url": "https://hooks.stripe.com/adapter/sepa_debit/file/src_1Fch4YEafOxC3pa8VYi8KNox/src_client_secret_G8z2C1kK3xteT9d7mJOlnU4y", "branch_code": null }, "statement_descriptor": null, "status": "chargeable", "type": "sepa_debit", "usage": "reusable" }

{
  "id": "src_GABJMyRlgnQDAjVYf0xCpa8o",
  "object": "payment_method",
  "billing_details": {
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line1": "Nollendorfstraße 27",
      "line2": null,
      "postal_code": 10777,      "state": null
    },
    "email": "jenny.rosen@example.com",
    "name": "Jenny Rosen",
    "phone": null
  },
  "created": 1573256458,
  "customer": "cus_GABJMyRlgnQDAj",
  "livemode": false,
  "metadata": {
  },
  "sepa_debit": {
    "bank_code": "22222222",
    "branch_code": null,
    "country": "DE",
    "fingerprint": "oAnAztLiWFEnfcn6",
    "last4": "3000"
  },
  "type": "sepa_debit"
}
{
  "id": "src_GABJMyRlgnQDAjVYf0xCpa8o",
  "object": "payment_method",
  "billing_details": {
    "address": {
      "city": "Berlin",
      "country": "DE",
      "line1": "Nollendorfstraße 27",
      "line2": null,
      "postal_code": 10777,

See all 30 lines "state": null }, "email": "jenny.rosen@example.com", "name": "Jenny Rosen", "phone": null }, "created": 1573256458, "customer": "cus_GABJMyRlgnQDAj", "livemode": false, "metadata": { }, "sepa_debit": { "bank_code": "22222222", "branch_code": null, "country": "DE", "fingerprint": "oAnAztLiWFEnfcn6", "last4": "3000" }, "type": "sepa_debit" }

Note that with this compatibility, no new objects are created; the Payment Methods API provides a different view of the same underlying object. For example, updates to a compatible payment instrument through the Payment Methods API is visible through the Sources API, and vice versa.

For SEPA Direct Debit payments, you can reuse a SEPA source as a PaymentMethod by attaching it to a Customer object. Compatible SEPA sources must have a populated mandate hash with a non single_use interval.

Transitioning to the Payment Methods API

Compatibility with Sources and cards

See also