Create payment method

Time	Status	User Agent
Retrieving recent requests…

Overview

Attach a payment method to a customer using a gateway token. The new payment method is automatically set as the customer's default, and their subscriptions are updated to charge automatically.

Example: A customer adds a new credit card during checkout. Pass the Stripe token to create the payment method and start charging their subscription.

Conditional Requirements

Condition	Required Fields
Always	`customer_id`, `object_gateway`
Stripe	`object_id` (must match `src_`, `card_`, or `pm_` prefix)
Tap	`object_id` (must match `card_` prefix), `properties.tap_customer_id` (must match `cus_` prefix)
Vantiv	`object_id` (unique per account), `properties.exp_month`, `properties.exp_year`, `properties.last4`, `properties.card_type`
Cybersource	`object_id` (max 32 chars), `properties.exp_month`, `properties.exp_year`, `properties.last4`, `properties.card_type`
Braintree	`object_id` (unique per account), `properties.braintree_customer_id`

Validation Constraints

Field	Constraint
`customer_id`	Must exist under the current site and account
`object_gateway`	Must be a valid, active payment gateway on the account
`object_id`	Must be unique (Stripe: globally unique; Vantiv/Braintree: unique per account)
`object_id` (Stripe)	Validated against Stripe API to confirm token exists
`properties.exp_month`	2 digits (Vantiv, Cybersource)
`properties.exp_year`	4 digits (Vantiv, Cybersource)
`properties.last4`	4 digits (Vantiv, Cybersource)
`customer_old_provider_id`	If provided, must match the same customer as `customer_id`

Side Effects (All Gateways)

These side effects apply regardless of the payment gateway:

Auto-default: The new payment method is automatically set as the customer's default source.
Billing update: All of the customer's subscriptions are switched to charge_automatically billing and updated to use the new default payment method. This behavior is enabled by default and can be configured via Billing Settings — see Automatic Collection Method Transition and Automatic Update of Default Payment Method.
Event fired: source.created event is dispatched after successful creation.

Side Effects by Payment Gateway

Stripe

Behavior	Detail
External API call	Validates the token against Stripe (`pm_` tokens retrieved via PaymentMethods API, others via Sources API)
Customer sync	If the customer does not yet exist on Stripe, creates the Stripe customer first
Ownership validation	For `pm_` tokens, verifies the payment method belongs to the customer on Stripe
Set default (Stripe sync)	Syncs the new default payment method to Stripe so future charges use it automatically
Local effect	Creates or updates the payment method record

Braintree

Behavior	Detail
External API call	Retrieves and validates the payment method from Braintree
Ownership validation	Verifies that `braintree_customer_id` matches the payment method's customer on Braintree
Integration sync	Stores the `braintree_customer_id` as a customer integration ID
Local effect	Creates or updates the payment method record

Tap

Behavior	Detail
External API call	Retrieves card details from the Tap API
Integration sync	Stores the `tap_customer_id` as a customer integration ID
Local effect	Creates or updates the payment method record with card properties from Tap. The `object_id` is stored as the card's `fingerprint` from Tap, not the `card_id`.

Vantiv

Behavior	Detail
Gateway interaction	Expects a pre-existing Vantiv token — the token is not validated against the gateway. Typically used for importing or migrating payment methods.
Local effect	Creates the payment method record with `cnpToken`, `cnpTxnId`, and `networkTransactionId` in properties

Cybersource

Behavior	Detail
Gateway interaction	Expects a pre-existing Cybersource token — the token is not validated against the gateway. Typically used for importing or migrating payment methods.
Local effect	Creates the payment method record with `cybersource_card_id` in properties