Update Subscription Card

When a subscriber needs to change the card used for their subscription, the flow has two steps:

1. Tokenize the new card — Create a checkout in “setup” mode and send the link to the customer so they can enter their new card.
2. Update the subscription — When the customer completes the checkout, you receive the payment_method_id via webhook and use it to update the subscription.

Step 1: Create a tokenization checkout

Create a checkout with mode: "setup". This checkout only tokenizes the card without charging anything.

$
curl -X POST https://app.recurrente.com/api/checkouts \
>
  -H "X-SECRET-KEY: your_secret_key" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "mode": "setup",
>
    "user_id": "us_SUBSCRIBER_ID",
>
    "success_url": "https://yoursite.com/card-updated",
>
    "cancel_url": "https://yoursite.com/cancelled"
>
  }'

Response:

1
{
2
  "id": "ch_eegw9j5zgqoae3ms",
3
  "checkout_url": "https://app.recurrente.com/checkout-session/ch_eegw9j5zgqoae3ms"
4
}

Send the checkout_url to your customer (via email, WhatsApp, within your app, etc.) so they can enter their new card.

Step 2: Receive the payment_method_id via webhook

When the customer completes the checkout, Recurrente sends a setup_intent.succeeded webhook to your configured endpoint. The payload includes the new card’s payment_method_id:

1
{
2
  "id": "pa_abc123",
3
  "status": "succeeded",
4
  "type": "setup_intent.succeeded",
5
  "payment_method": {
6
    "id": "pay_m_new123",
7
    "type": "card",
8
    "card": {
9
      "last4": "5678",
10
      "network": "mastercard"
11
    }
12
  }
13
}

Save the payment_method.id — you’ll need it in the next step.

Step 3: Update the subscription with the new card

Use the payment_method_id obtained to update the subscription:

$
curl -X PUT https://app.recurrente.com/api/subscriptions/su_SUBSCRIPTION_ID \
>
  -H "X-SECRET-KEY: your_secret_key" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "payment_method_id": "pay_m_new123"
>
  }'

Response:

1
{
2
  "id": "su_nehndm7j",
3
  "status": "active",
4
  "description": "Monthly Subscription",
5
  "default_payment_method": {
6
    "id": "pay_m_new123",
7
    "type": "card",
8
    "card": {
9
      "last4": "5678",
10
      "network": "mastercard"
11
    }
12
  }
13
}

From this point on, all future automatic charges for the subscription will use the new card.

Flow summary

Your backend                Recurrente                    Customer
    │                            │                           │
    │── POST /api/checkouts ────▶│                           │
    │◀── checkout_url ──────────│                           │
    │                            │                           │
    │── Send link to customer ──────────────────────────────▶│
    │                            │                           │
    │                            │◀── Enters new card ───────│
    │                            │                           │
    │◀── Webhook ───────────────│                           │
    │    setup_intent.succeeded  │                           │
    │    (payment_method_id)     │                           │
    │                            │                           │
    │── PUT /api/subscriptions ─▶│                           │
    │   (payment_method_id)      │                           │
    │◀── Subscription updated ──│                           │