SMsmokeball
Subscription Payments

Create a payment method session

Changed on

Creates a hosted page where the user enters a card for the account, and returns its url. Once the user completes it, the card is also set as the default payment method for the specified subscription.

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.
post/subscriptions/{subscriptionId}/paymentmethods/sessions

Request

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

Path parameters

subscriptionIdstring required

The unique identifier of the subscription

Request body

successUrlstring 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.

cancelUrlstring required

Absolute url the user is redirected to if they leave without entering a payment method.

isDefaultboolean 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.

chargeImmediatelyboolean 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.

Example request

{
  "successUrl": "https://app.smokeball.com/billing/payment-methods?added=true",
  "cancelUrl": "https://app.smokeball.com/billing/payment-methods",
  "isDefault": true,
  "chargeImmediately": true
}

Response

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

urlstring nullable

The hosted page to redirect the user to.

expiresAtstring date-time

When the url stops working. Create a new session after this time.

Example response

{
  "url": "https://checkout.stripe.com/c/pay/cs_test_1234567890",
  "expiresAt": "2026-10-27T01:00:00Z"
}

Changes