---
title: "Create a payment method session"
method: POST
path: "/subscriptions/paymentmethods/sessions"
tags: ["Subscription Payments"]
---

# Create a payment method session

`POST /subscriptions/paymentmethods/sessions`

## Request

- Base URL: `https://api.smokeball.com`
- URL: `https://api.smokeball.com/subscriptions/paymentmethods/sessions`
- Auth: API key in header `x-api-key` and API key in header `Authorization`

Creates a hosted page where the user enters a card for the account, and returns its url.
            
Adding a card:
* Call this endpoint and redirect the user to 'url'.
* The user enters a card and is redirected to 'successUrl', or to 'cancelUrl' if they leave.
* The card is added asynchronously once the user completes the page. Poll the payment methods endpoint to see it.

## Request body

- CreatePaymentMethodSessionRequest
  - `successUrl` string, required: Absolute url the user is redirected to after entering a payment method. The payment method is added asynchronously, so it may not be listed yet when the user lands here.
  - `cancelUrl` string, required: Absolute url the user is redirected to if they leave without entering a payment method.
  - `isDefault` boolean, nullable: Optional: Whether to set the new payment method as the default for the entire account. This does not set the default payment method for the subscription.
  - `chargeImmediately` boolean, nullable: Optional: Whether to charge immediately if subscription(s) are overdue. Defaults to true. If a subscription id is passed as a parameter to the request, only that subscription will be charged immediately if overdue.

## Response `200`

When request is successful. Returns a 'PaymentMethodSessionResponse' object.

- PaymentMethodSessionResponse: A hosted page where the user enters a payment method. Redirect the user to Finance.Subscriptions.Api.Models.PaymentMethodSessionResponse.Url.
  - `url` string, nullable: The hosted page to redirect the user to.
  - `expiresAt` string, date-time: When the url stops working. Create a new session after this time.

## Other responses

- `400`: When a redirect url is not a valid absolute url.
- `404`: When the account is not associated to a customer.
- `500`: When an error occurs while creating the session.

## Changes

- **2026-10-28** `2fe552c5d11d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/smokeball/apis/smokeball-api/changes/subscriptions/paymentmethods/sessions/post.md)

---

[API](https://skmtc.dev/smokeball/apis/smokeball-api.md) - [All operations](https://skmtc.dev/smokeball/apis/smokeball-api/llms.txt) - [OpenAPI document](https://skmtc.dev/smokeball/apis/smokeball-api/revisions/6e350cf667d4?raw)