Stripe: Create a source

← Sources operations · Get started

Operation stripe.postsources

Provider route: POST /v1/sources. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/stripe with npm, or alter-sdk-stripe with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { StripeIntegration } from "@alter-ai/stripe";

async function execute(input: Parameters<StripeIntegration["sources"]["postSources"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new StripeIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.sources.postSources(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_stripe import StripeIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = StripeIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.sources.post_sources(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
headers	object	Optional	Additional keys: not allowed
headers.Idempotency-Key	string	Optional	Minimum length: 1 Maximum length: 255
body	object	Optional	Additional keys: not allowed
body.amount	integer	Optional	Amount associated with the source. This is the amount for which the source will be chargeable once ready. Required for `single_use` sources. Not supported for `receiver` type sources, where charge amount may not be specified until funds land.
body.currency	string	Optional	Three-letter [ISO code for the currency](https://stripe.com/docs/currencies) associated with the source. This is the currency for which the source will be chargeable once ready. Format: currency
body.customer	string	Optional	The `Customer` to whom the original source is attached to. Must be set when the original source is not a `Source` (e.g., `Card`). Maximum length: 500
body.expand	array	Optional	Specifies which fields in the response should be expanded.
body.expand[]	string	Each item	Maximum length: 5000
body.flow	string	Optional	The authentication `flow` of the source to create. `flow` is one of `redirect`, `receiver`, `code_verification`, `none`. It is generally inferred unless a type supports multiple flows. One of: code_verification, none, receiver, redirect Maximum length: 5000
body.mandate	Model	Optional	Expand Create a source — request body — body mandate
body.metadata	object	Optional	Additional keys: see wildcard field
body.metadata.*	string	Additional keys
body.original_source	string	Optional	The source to share. Maximum length: 5000
body.owner	Model	Optional	Expand Create a source — request body — body owner
body.receiver	object	Optional	Optional parameters for the receiver flow. Can be set only if the source is a receiver (`flow` is `receiver`).
body.receiver.refund_attributes_method	string	Optional	One of: email, manual, none Maximum length: 5000
body.redirect	object	Optional	Parameters required for the redirect flow. Required if the source is authenticated by a redirect (`flow` is `redirect`).
body.redirect.return_url	string	Required within parent
body.source_order	Model	Optional	Expand Create a source — request body — body source order
body.statement_descriptor	string	Optional	An arbitrary string to be displayed on your customer’s statement. As an example, if your website is `RunClub` and the item you’re charging for is a race ticket, you may want to specify a `statement_descriptor` of `RunClub 5K race ticket.` While many payment types will display this information, some may not display it at all. Maximum length: 5000
body.token	string	Optional	An optional token used to create the source. When passed, token properties will override source parameters. Maximum length: 5000
body.type	string	Optional	The `type` of the source to create. Required unless `customer` and `original_source` are specified (see the [Cloning card Sources](https://docs.stripe.com/sources/connect#cloning-card-sources) guide) Maximum length: 5000
body.usage	string	Optional	One of: reusable, single_use Maximum length: 5000

Referenced models: Create a source — request body — body mandate, Create a source — request body — body owner, Create a source — request body — body source order

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Create a source — response body

Referenced models: Create a source — response body

Schemas

24 more schemas are linked from the tables above, on the schema pages.

Create a source — request body — body mandate

Field	Type	Presence	Description and constraints
$	object	Root	Information about a mandate possibility attached to a source object (generally for bank debits) as well as its acceptance status.
acceptance	Model	Optional	Expand Create a source — request body — body mandate acceptance
amount	JSON	Optional
amount (anyOf 1)	integer	Alternative
amount (anyOf 2)	string	Alternative	One of:
currency	string	Optional	Format: currency
interval	string	Optional	One of: one_time, scheduled, variable Maximum length: 5000
notification_method	string	Optional	One of: deprecated_none, email, manual, none, stripe_email Maximum length: 5000

Referenced models: Create a source — request body — body mandate acceptance

Create a source — request body — body owner

Field	Type	Presence	Description and constraints
$	object	Root	Information about the owner of the payment instrument that may be used or required by particular source types.
address	object	Optional
address.city	string	Optional	Maximum length: 5000
address.country	string	Optional	Maximum length: 5000
address.line1	string	Optional	Maximum length: 5000
address.line2	string	Optional	Maximum length: 5000
address.postal_code	string	Optional	Maximum length: 5000
address.state	string	Optional	Maximum length: 5000
email	string	Optional
name	string	Optional	Maximum length: 5000
phone	string	Optional	Maximum length: 5000

Create a source — request body — body source order

Field	Type	Presence	Description and constraints
$	object	Root	Information about the items and shipping associated with the source. Required for transactional credit (for example Klarna) sources before you can charge it.
items	array	Optional
items[]	object	Each item
items[].amount	integer	Optional
items[].currency	string	Optional	Format: currency
items[].description	string	Optional	Maximum length: 1000
items[].parent	string	Optional	Maximum length: 5000
items[].quantity	integer	Optional
items[].type	string	Optional	One of: discount, shipping, sku, tax Maximum length: 5000
shipping	Model	Optional	Expand Create a source — request body — body source order shipping

Referenced models: Create a source — request body — body source order shipping

Create a source — response body — code verification

Field	Type	Presence	Description and constraints
$	object	Root
attempts_remaining	JSON	Required within parent
attempts_remaining (anyOf 1)	integer	Alternative	The number of attempts remaining to authenticate the source object with a verification code.
attempts_remaining (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
status	string	Required within parent	The status of the code verification, either `pending` (awaiting verification, `attempts_remaining` should be greater than 0), `succeeded` (successful verification) or `failed` (failed verification, cannot be verified anymore as `attempts_remaining` should be 0). Maximum length: 5000

Create a source — response body — source order

Field	Type	Presence	Description and constraints
$	object	Root
amount	JSON	Required within parent
amount (anyOf 1)	integer	Alternative	A positive integer in the smallest currency unit (that is, 100 cents for $1.00, or 1 for ¥1, Japanese Yen being a zero-decimal currency) representing the total amount for the order.
amount (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
currency	string	Required within parent	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). Format: currency
email	string	Optional	The email address of the customer placing the order. Maximum length: 5000
items	JSON	Optional
items (anyOf 1)	array	Alternative	List of items constituting the order.
items (anyOf 1)[]	Model	Each item	Expand Create a source — response body — source order items List of items constituting the order item
items (anyOf 2)	null	Alternative
shipping	Model	Optional	Expand Create a source — response body — source order shipping

Referenced models: Create a source — response body — source order shipping, Create a source — response body — source order items List of items constituting the order item

Create a source — response body — owner value address, email, name, phone, verified address, verified email, verified name, verified phone

Field	Type	Presence	Description and constraints
$	object	Root
address	JSON	Optional
address (anyOf 1)	JSON	Alternative	Owner's address.
address (anyOf 1) (anyOf 1)	Model	Alternative	Expand Create a Location — response body — address
address (anyOf 2)	null	Alternative
email	JSON	Optional
email (anyOf 1)	string	Alternative	Owner's email address. Maximum length: 5000
email (anyOf 2)	null	Alternative
name	JSON	Optional
name (anyOf 1)	string	Alternative	Owner's full name. Maximum length: 5000
name (anyOf 2)	null	Alternative
phone	JSON	Optional
phone (anyOf 1)	string	Alternative	Owner's phone number (including extension). Maximum length: 5000
phone (anyOf 2)	null	Alternative
verified_address	JSON	Optional
verified_address (anyOf 1)	JSON	Alternative	Verified owner's address. Verified values are verified or provided by the payment method directly (and if supported) at the time of authorization or settlement. They cannot be set or mutated.
verified_address (anyOf 1) (anyOf 1)	Model	Alternative	Expand Create a Location — response body — address
verified_address (anyOf 2)	null	Alternative
verified_email	JSON	Optional
verified_email (anyOf 1)	string	Alternative	Verified owner's email address. Verified values are verified or provided by the payment method directly (and if supported) at the time of authorization or settlement. They cannot be set or mutated. Maximum length: 5000
verified_email (anyOf 2)	null	Alternative
verified_name	JSON	Optional
verified_name (anyOf 1)	string	Alternative	Verified owner's full name. Verified values are verified or provided by the payment method directly (and if supported) at the time of authorization or settlement. They cannot be set or mutated. Maximum length: 5000
verified_name (anyOf 2)	null	Alternative
verified_phone	JSON	Optional
verified_phone (anyOf 1)	string	Alternative	Verified owner's phone number (including extension). Verified values are verified or provided by the payment method directly (and if supported) at the time of authorization or settlement. They cannot be set or mutated. Maximum length: 5000
verified_phone (anyOf 2)	null	Alternative

Referenced models: Create a Location — response body — address

Create a source — response body — redirect

Field	Type	Presence	Description and constraints
$	object	Root
failure_reason	JSON	Optional
failure_reason (anyOf 1)	string	Alternative	The failure reason for the redirect, either `user_abort` (the customer aborted or dropped out of the redirect flow), `declined` (the authentication failed or the transaction was declined), or `processing_error` (the redirect failed due to a technical error). Present only if the redirect status is `failed`. Maximum length: 5000
failure_reason (anyOf 2)	null	Alternative
return_url	string	Required within parent	The URL you provide to redirect the customer to after they authenticated their payment. Maximum length: 5000
status	string	Required within parent	The status of the redirect, either `pending` (ready to be used by your customer to authenticate the transaction), `succeeded` (successful authentication, cannot be reused) or `not_required` (redirect should not be used) or `failed` (failed authentication, cannot be reused). Maximum length: 5000
url	string	Required within parent	The URL provided to you to redirect a customer to as part of a `redirect` authentication flow. Maximum length: 2048

Create a source — response body — eps

Field	Type	Presence	Description and constraints
$	object	Root
reference	JSON	Optional
reference (anyOf 1)	string	Alternative
reference (anyOf 2)	null	Alternative
statement_descriptor	JSON	Optional
statement_descriptor (anyOf 1)	string	Alternative
statement_descriptor (anyOf 2)	null	Alternative

Policy, approvals and errors

SDK function policy ID: stripe.postsources. Catalog operation: PostSources. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"Stripe-Version": "2026-09-30.endive"}

Official provider source