Create a secure, Pelcro-hosted link where the authenticated customer can add or replace their card. Card details are entered in Stripe Elements on the hosted page and go straight to Stripe — they never pass through your integration. On completion the card is saved, set as the customer's default, and their subscriptions are switched to charge it automatically. The link is single-use and expires. Requires a Stripe connected account.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Overview
Create a secure, Pelcro-hosted link where the authenticated customer can add or replace their card. You get back a URL; the customer opens it and enters their card in Stripe Elements on a Pelcro-hosted page, so the card goes straight to Stripe and never passes through your integration.
Use this instead of collecting card details yourself whenever you only need the customer to update their card — including from an AI agent or support conversation, where card numbers should never be typed.
Example:
curl --request POST \
--url 'https://www.pelcro.com/api/v1/sdk/payment_methods/setup-link?site_id=1232' \
--header 'Authorization: Bearer <JWT>' \
--header 'Content-Type: application/json' \
--data '{ "return_url": "https://example.com/account/billing", "expires_in_hours": 48 }'What happens when the customer completes the form
- The card is tokenized inside Stripe's iframe and posted back to Pelcro as a token.
- Pelcro creates the payment method and sets it as the customer's default.
- All of the customer's subscriptions are switched to charge that payment method automatically.
- The customer is redirected to
return_url, or to the Pelcro-hosted success page whenreturn_urlwas not provided.
Link behavior
| Property | Behavior |
|---|---|
| Scope | Encrypted and bound to the single customer it was minted for |
| Single-use | Claimed atomically on the first successful save. A replayed link returns 410 Gone |
| Expiry | Controlled by expires_in_hours (1–168, default 24). An expired link returns 410 Gone |
| Failed save | The link is released again, so the customer can retry with the same URL |
| Rate limit | Submissions on the hosted page are throttled to 10 per minute |
Email delivery
The link is always emailed to the customer's address on file — there is no opt-in parameter. The email is only sent if the site has the Payment Method Setup Link template enabled in Email Center.
Read email_queued in the response:
true— the email will be sent to the customer.false— no email will be sent. Share theurlwith the customer yourself.
Requirements and limits
- The hosted page renders Stripe Elements, so the account must be on Stripe and have a Stripe connected account. Anything else returns
422with the site's support-contact message. - A customer can store at most 200 payment methods. At the limit, the hosted page rejects the submission.
- If the account also has an active Braintree gateway with PayPal enabled, the hosted page offers PayPal alongside the card field.
Related
- Update payment method — set an existing payment method as default, or replace a card using a token you already hold.