Guides

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 an item of amount 0 and charge_type: "one_time". This checkout only tokenizes the card without charging anything.

$curl -X POST https://app.recurrente.com/api/checkouts \
>  -H "X-PUBLIC-KEY: your_public_key" \
>  -H "X-SECRET-KEY: your_secret_key" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "items": [
>      {
>        "name": "Update payment method",
>        "currency": "GTQ",
>        "amount_in_cents": 0,
>        "charge_type": "one_time"
>      }
>    ],
>    "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.

Include the subscriber’s user_id so the checkout pre-fills their information (name, email, etc.).

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.

If you don’t have webhooks configured, you can also get the payment_method_id by doing a GET /api/checkouts/{id} on the checkout once it’s been paid. The payment_method.id field will be in the response.

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-PUBLIC-KEY: your_public_key" \
>  -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.

If the subscription has a pending payment (e.g., a failed charge), Recurrente will automatically attempt to charge it with the new card when you update it.

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 ──│                           │