Skip to main content
POST
Create a payment method session

Authorizations

Authorization
string
header
required

A secret key, sk_test_... or sk_live_...; a publishable key (pk_...) on the browser routes only

Body

application/json
customer
string<uuid>

A customer of your workspace the collected method will belong to.

payment_method_types
enum<string>[]

One type. card when omitted.

Minimum array length: 1
Available options:
card,
us_bank_account
Example:
amount
integer

Required for a us_bank_account session without a customer: the amount the account holder authorizes, in cents. The charge must match it.

Example:

21375

currency
enum<string>

With amount; USD only.

Available options:
USD,
usd
Example:

"USD"

Response

The session, with its client secret

object
enum<string>
required
Available options:
payment_method_session
id
string
required
Example:

"pms_test_7Hs2kQ9mL1pXv4cR8tWzAbCd"

status
enum<string>
required
Available options:
requires_payment_method,
succeeded,
canceled,
expired
Example:

"requires_payment_method"

customer
string<uuid> | null
required
Example:

null

payment_method_types
enum<string>[]
required
Available options:
card,
us_bank_account
Example:
amount
integer | null
required

What a one-time bank debit will authorize, in the smallest unit of currency. Null on a card session and when a bank account is being saved.

Example:

null

currency
enum<string> | null
required
Available options:
USD
Example:

null

livemode
boolean
required
Example:

false

expires_at
string<date-time>
required
Example:

"2026-09-17T18:30:00.000Z"

canceled_at
string<date-time> | null
required
Example:

null

succeeded_at
string<date-time> | null
required
Example:

null

card
object | null
required

Set once the browser confirmed a card.

Example:

null

us_bank_account
object | null
required

Set once the browser confirmed a bank account.

Example:

null

ach_authorization
object | null
required

On a us_bank_account session: the authorization shown to the account holder, and when they accepted it.

Example:

null

payment_method
string | null
required

The payment method your server created from this session, once it did.

Example:

null

created_at
string<date-time>
required
Example:

"2026-09-17T18:00:00.000Z"

client_secret
string
required

Returned only here. Hand it to the browser; never store it server-side.

Example:

"pms_test_7Hs2kQ9mL1pXv4cR8tWzAbCd_secret_9qmY2w6f0Rj8XpLs3vTb1nHc7KdGaZe4"