--- updatedAt: 2026-06-30T16:05:21.000Z agentTools: projectIndex: https://docs.pelcro.com/llms.txt --- # Create payment method Attach a payment method to a customer using a gateway token. ## 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](https://docs.pelcro.com/docs/subscriptions#automatic-collection-method-transition) and [Automatic Update of Default Payment Method](https://docs.pelcro.com/docs/subscriptions#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 | # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "core-api", "version": "1.88" }, "servers": [ { "url": "https://www.pelcro.com/api/v1/core" } ], "components": { "securitySchemes": { "sec0": { "type": "apiKey", "in": "header", "name": "Authorization", "x-bearer-format": "bearer" }, "sec1": { "type": "apiKey", "in": "query", "name": "site_id" } } }, "security": [ { "sec0": [], "sec1": [] } ], "paths": { "/sources": { "post": { "summary": "Create payment method", "description": "Attach a payment method to a customer using a gateway token.", "operationId": "api-core-create-payment-method", "parameters": [ { "name": "site_id", "in": "query", "description": "The unique identifier of the site associated with your account.", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "customer_id", "in": "query", "description": "The unique identifier of the customer for which to create the payment method for.", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string", "default": "Bearer eyJ***" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "object_gateway", "object_id" ], "properties": { "object_gateway": { "type": "string", "description": "One of \"stripe\", \"braintree\", \"tap\", \"vantiv\", or \"cybersource\". See full list of supported [payment gateways](https://docs.pelcro.com/reference/payment-gateways)." }, "object_id": { "type": "string", "description": "The unique identifier of the payment method object as it exists on the payment gateway." }, "properties": { "type": "object", "description": "The properties of the payment method. These vary based on the payment gateway as follows:

`stripe`

none required

`tap`

tap_customer_id: the unique identifier of the customer on Tap.

`vantiv`

cnpTxnId: the [cnpTxnId](http://support.worldpay.com/support/CNP-API/content/cnptxnid.htm).
networkTransactionId: the networkTransactionId
exp_month: the month of the expiry date of the card.
exp_year: the year of the expiry date of the card.
last4: the last four digits of the card.
card_type: the card type

`cybersource`

exp_month: the month of the expiry date of the card.
exp_year: the year of the expiry date of the card.
last4: the last four digits of the card.
card_type: the card type
" }, "customer_old_provider_id": { "type": "string", "description": "Alternative to customer_id. If provided, resolves the customer by their old_provider_id instead. Must match the same customer as customer_id if both are provided." } } }, "examples": { "Stripe": { "value": { "object_gateway": "stripe", "object_id": "card_1MCN5fK7WesYiaftK3D65kg7" } }, "Tap": { "value": { "object_gateway": "tap", "object_id": "card_J9NZ17221325Ohgf30oP10b475", "properties": { "tap_customer_id": "cus_TS053620221932l3B13011382" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "examples": { "Result": { "value": "{\n\t\"data\": {\n\t\t\"id\": 438404,\n\t\t\"object_gateway\": \"tap\",\n\t\t\"user\": {\n\t\t\t\"id\": 7600407,\n\t\t\t\"addresses\": [],\n\t\t\t\"default_source\": 438404,\n\t\t\t\"organization\": null,\n\t\t\t\"subscriptions\": [],\n\t\t\t\"display_name\": \"John.Mark\",\n\t\t\t\"username\": null,\n\t\t\t\"email\": \"john.mark@.com\",\n\t\t\t\"email_confirm\": false,\n\t\t\t\"email_hardbounce\": false,\n\t\t\t\"first_name\": \"John\",\n\t\t\t\"last_name\": \"Mark\",\n\t\t\t\"mail_marketing\": true,\n\t\t\t\"metadata\": {\n\t\t\t\t\"vvv1\": \"a\"\n\t\t\t},\n\t\t\t\"name\": \"John Mark\",\n\t\t\t\"old_provider_id\": null,\n\t\t\t\"is_imported\": false,\n\t\t\t\"phone\": \"00202157756\",\n\t\t\t\"phone_confirm\": false,\n\t\t\t\"salutation\": null,\n\t\t\t\"language\": null,\n\t\t\t\"title\": null,\n\t\t\t\"tin\": \"12345\",\n\t\t\t\"profile_photo\": null,\n\t\t\t\"default_source_id\": 438404,\n\t\t\t\"tele_marketing\": true,\n\t\t\t\"timezone\": null,\n\t\t\t\"has_password\": true,\n\t\t\t\"password_last_updated_at\": null,\n\t\t\t\"last_login_at\": 1669289102,\n\t\t\t\"last_login_method\": null,\n\t\t\t\"created_at\": 1669289059,\n\t\t\t\"updated_at\": 1670191468\n\t\t},\n\t\t\"object_id\": \"abV%2BW%2B8Y8p7CvzbOh2nux1N1btFrGG2JwJiF8TQa4Yg%3D\",\n\t\t\"exp_month\": 12,\n\t\t\"exp_year\": 2025,\n\t\t\"address_zip_check\": null,\n\t\t\"brand\": \"Visa\",\n\t\t\"country\": null,\n\t\t\"cvc_check\": null,\n\t\t\"fingerprint\": \"abV%2BW%2B8Y8p7CvzbOh2nux1N1btFrGG2JwJiF8TQa4Yg%3D\",\n\t\t\"funding\": null,\n\t\t\"last4\": \"4242\",\n\t\t\"three_d_secure\": null,\n\t\t\"name\": null,\n\t\t\"address_line1_check\": null,\n\t\t\"tokenization_method\": null,\n\t\t\"dynamic_last4\": null\n\t},\n\t\"status\": \"success\"\n}" } }, "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 438404, "default": 0 }, "object_gateway": { "type": "string", "example": "tap" }, "user": { "type": "object", "properties": { "id": { "type": "integer", "example": 7600407, "default": 0 }, "addresses": { "type": "array" }, "default_source": { "type": "integer", "example": 438404, "default": 0 }, "organization": {}, "subscriptions": { "type": "array" }, "display_name": { "type": "string", "example": "John.Mark" }, "username": {}, "email": { "type": "string", "example": "john.mark@.com" }, "email_confirm": { "type": "boolean", "example": false, "default": true }, "email_hardbounce": { "type": "boolean", "example": false, "default": true }, "first_name": { "type": "string", "example": "John" }, "last_name": { "type": "string", "example": "Mark" }, "mail_marketing": { "type": "boolean", "example": true, "default": true }, "metadata": { "type": "object", "properties": { "vvv1": { "type": "string", "example": "a" } } }, "name": { "type": "string", "example": "John Mark" }, "old_provider_id": {}, "is_imported": { "type": "boolean", "example": false, "default": true }, "phone": { "type": "string", "example": "00202157756" }, "phone_confirm": { "type": "boolean", "example": false, "default": true }, "salutation": {}, "language": {}, "title": {}, "tin": { "type": "string", "example": "12345" }, "profile_photo": {}, "default_source_id": { "type": "integer", "example": 438404, "default": 0 }, "tele_marketing": { "type": "boolean", "example": true, "default": true }, "timezone": {}, "has_password": { "type": "boolean", "example": true, "default": true }, "password_last_updated_at": {}, "last_login_at": { "type": "integer", "example": 1669289102, "default": 0 }, "last_login_method": {}, "created_at": { "type": "integer", "example": 1669289059, "default": 0 }, "updated_at": { "type": "integer", "example": 1670191468, "default": 0 } } }, "object_id": { "type": "string", "example": "abV%2BW%2B8Y8p7CvzbOh2nux1N1btFrGG2JwJiF8TQa4Yg%3D" }, "exp_month": { "type": "integer", "example": 12, "default": 0 }, "exp_year": { "type": "integer", "example": 2025, "default": 0 }, "address_zip_check": {}, "brand": { "type": "string", "example": "Visa" }, "country": {}, "cvc_check": {}, "fingerprint": { "type": "string", "example": "abV%2BW%2B8Y8p7CvzbOh2nux1N1btFrGG2JwJiF8TQa4Yg%3D" }, "funding": {}, "last4": { "type": "string", "example": "4242" }, "three_d_secure": {}, "name": {}, "address_line1_check": {}, "tokenization_method": {}, "dynamic_last4": {} } }, "status": { "type": "string", "example": "success" } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"error\": {\n \"status\": 400,\n \"message\": \"Invalid request, please try again.\"\n }\n}" } }, "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "status": { "type": "integer", "example": 400, "default": 0 }, "message": { "type": "string", "example": "Invalid request, please try again." } } } } } } } }, "401": { "description": "Unauthenticated.", "content": { "application/json": { "examples": { "Result": { "value": { "error": "Unauthenticated." } } } } } } }, "deprecated": false } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true } ``` # Sibling pages * [List payment methods](https://docs.pelcro.com/reference/api-core-list-payment-methods.md) * [Get payment method](https://docs.pelcro.com/reference/api-core-get-payment-method.md) * [Delete payment method](https://docs.pelcro.com/reference/api-core-delete-payment-method.md)