Save a buyer's card with a hosted setup link

You never touch sensitive card credentials. Create a setup link with the user’s buyer key, show it to them in your product flow, and check the card is ready when they finish. You need: the user’s buyer key.

Create a setup link

API
Agent (MCP)

curl https://api.sapiom.ai/v1/payment-cards/setup-links \
  -H "x-api-key: $SAPIOM_BUYER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"returnUrl":"https://your-app.example/cards/done","cardholderEmail":"jane@example.com"}'

Returns the link’s id, status, expiresAt and a one-time url.

{
  "name": "sapiom_add_payment_method",
  "arguments": { "returnUrl": "https://your-app.example/cards/done" }
}

Returns url and setupLink: { id, status, expiresAt }.

Field	Notes
`returnUrl`	Optional. Where the user lands after saving their card. Must be HTTPS, except for `localhost`.
`cardholderEmail`	API only. Pre-fills the user’s email. They can change it.
`expiresInMinutes`	API only. How long the link works: 30 by default, from 5 to 1440.

Show url only to that user. Sapiom returns it once and never stores it, so keep the id to check progress.

What the user sees

The hosted page shows your platform’s name and logo and asks for the user’s email and card details. After saving, the user goes to your returnUrl, if you set one.

The hosted setup page, branded for a platform called Wayfare

Check the card is ready

After saving, read the link:

curl "https://api.sapiom.ai/v1/payment-cards/setup-links/$SETUP_LINK_ID" \
  -H "x-api-key: $SAPIOM_BUYER_KEY"

When status is completed, cardId is the new card. Store it with your user. The card is ready to pay once GET /v1/payment-cards/{cardId} shows status as active and readiness as anything other than not_ready.

Pick a card for a transaction

List the user’s cards with sapiom_list_payment_methods or GET /v1/payment-cards. Each card shows its brand, last4, isDefault, status and readiness. Suggest the default card if it is active and ready. Once the user picks a card, use that card ID for the whole transaction, including retries.

Manage saved cards

Task	API	MCP tool
List cards	`GET /v1/payment-cards`	`sapiom_list_payment_methods`
Read one card	`GET /v1/payment-cards/{cardId}`
Set the default card	`PUT /v1/payment-cards/{cardId}/default`
Remove a card	`DELETE /v1/payment-cards/{cardId}`	`sapiom_delete_payment_method`

Removing a card stops future transactions with it. It does not cancel or refund past orders.

Get started

Buyers

Cards

Transactions

Governance

Security

Early access

Save a buyer's card with a hosted setup link

Create a setup link

What the user sees

Check the card is ready

Pick a card for a transaction

Manage saved cards

​Create a setup link

​What the user sees

​Check the card is ready

​Pick a card for a transaction

​Manage saved cards

Create a setup link

What the user sees

Check the card is ready

Pick a card for a transaction

Manage saved cards