> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whop.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# API de Setup Intents

> Un Setup Intent guarda el método de pago de un comprador para más adelante sin cobrar dinero ahora.

Créalo a partir de un confirmation token que los payment elements recopilaron en modo de configuración, o a partir de un método de pago ya registrado para volver a verificarlo. Ejecuta el mismo flujo de recopilación que un pago, por lo que es posible que el comprador todavía deba completar un paso: 3D Secure en una tarjeta, una inscripción alojada o la vinculación de una cuenta bancaria.

La respuesta de creación es el setup intent tal como se creó, no su resultado. Pasa su `client_secret` a `handleNextAction` de los elements, o consulta periódicamente [Obtener estado](https://docs.whop.com/es/api-reference/setup-intents/retrieve-setup-status.md) para ver cuánto ha avanzado la configuración y qué queda pendiente. Una vez que llega a `succeeded`, `payment_method_id` identifica el método guardado y Create Payment lo cobra.

## Endpoints

| Endpoint | Solicitud |
| - | - |
| [Listar Setup Intents](https://docs.whop.com/es/api-reference/setup-intents/list-setup-intents.md) | GET `/setup_intents` |
| [Obtener Setup Intent](https://docs.whop.com/es/api-reference/setup-intents/retrieve-setup-intent.md) | GET `/setup_intents/{id}` |
| [Obtener estado de la configuración](https://docs.whop.com/es/api-reference/setup-intents/retrieve-setup-status.md) | GET `/setup_intents/{setup_intent_id}/status` |
| [Crear Setup Intent](https://docs.whop.com/es/api-reference/setup-intents/create-setup-intent.md) | POST `/setup_intents` |
| [Actualizar URL de retorno de la configuración](https://docs.whop.com/es/api-reference/setup-intents/update-setup-return-url.md) | PATCH `/setup_intents/{setup_intent_id}/return_url` |

## Atributos

**id** `string` *required*

ID del setup intent, con el prefijo `sint_`.

**account\_id** `string | null` *required*

La cuenta para la que se guarda el método de pago, con el prefijo `biz_`.

**checkout\_configuration\_id** `string | null` *required*

La configuración de checkout a través de la cual se creó esta configuración, con el prefijo `ch_`.
Es null para una configuración creada mediante esta API en lugar de un checkout alojado.

**client\_secret** `string | null` *required*

La credencial que presenta la interfaz del comprador para consultar esta configuración y definir su
URL de retorno; pásala a `handleNextAction` de los elements. Solo está en configuraciones
creadas mediante esta API, y siempre es null en las respuestas de listado; obtén el
setup intent para conseguirla.

**created\_at** `string` *required*

Cuándo se creó el setup intent, como marca de tiempo ISO 8601.

**last\_setup\_error** `object | null` *required*

Por qué la configuración terminó donde terminó, o `null` cuando nada ha fallado. Está presente en `canceled`: un comprador que abandonó no tiene código, uno rechazado por el proveedor sí. Se elimina una vez que la configuración se completa correctamente.

> [accordion] Propiedades
>
> **code** `string | null` *required*
>
> Una clasificación del fallo legible por máquina, p. ej. `enrollment_declined`.
> Ausente cuando el comprador simplemente abandonó la configuración.
>
> **message** `string | null` *required*
>
> Una explicación del fallo legible por humanos.

**member\_id** `string | null` *required*

El registro de miembro del comprador en la cuenta, con el prefijo `mber_`. Es null sin el
permiso member:basic:read, a menos que quien llama sea el comprador.

**metadata** `object | null` *required*

Tus propios datos clave-valor adjuntados cuando se creó el setup intent.

**payment\_instrument** `object | null` *required*

El método detrás de esta configuración preparado para mostrarse: un nombre visible para el comprador, el conjunto de iconos estándar y la marca de la tarjeta, los últimos cuatro dígitos, el número de identificación del emisor, el vencimiento y el ID de transacción de la red cuando era una tarjeta. Es null hasta que se recopila un método.

> [accordion] Propiedades
>
> **card** `object | null` *required*
>
> Solo para pagos con tarjeta, Apple Pay y Google Pay: la red de la tarjeta, los últimos cuatro dígitos, el número de identificación del emisor, el vencimiento y el ID de transacción de la red.
>
> > [accordion] Propiedades
> >
> > **brand** `string | null` *required*
> >
> > El identificador de la red (`visa`, `amex`, …), que coincide con las entradas de `card.networks`
> > y con los métodos de pago con tarjeta guardados. Es null cuando la bóveda no registró la
> > red.
> >
> > **exp\_month** `number | null` *required*
> >
> > El mes de vencimiento de la tarjeta, de 1 a 12. Es null cuando la bóveda no lo registró.
> >
> > **exp\_year** `number | null` *required*
> >
> > El año de vencimiento de la tarjeta, de cuatro dígitos. Es null cuando la bóveda no lo registró.
> >
> > **issuer\_identification\_number** `string | null` *required*
> >
> > El número de identificación del emisor, también llamado BIN: los primeros seis
> > u ocho dígitos de la tarjeta, que identifican al banco emisor. Es null cuando el procesador no
> > lo informó.
> >
> > **last4** `string | null` *required*
> >
> > Los últimos cuatro dígitos de la tarjeta, cuando se capturaron.
> >
> > **network\_transaction\_id** `string | null` *required*
> >
> > El ID de transacción de la red que esta cuenta usa para la tarjeta. Es el propio ID de esta cuenta, de su primer cargo o verificación con el cliente presente en la tarjeta, cuando Whop tiene uno. De lo contrario, es un ID de transacción de la red anterior para esta tarjeta, que puede provenir de la transacción de otra cuenta o haberse traído con la tarjeta. Cítalo como la transacción previa en un cargo posterior iniciado por el comerciante con esta tarjeta en esta cuenta. Es null hasta que exista uno. Un webhook enviado cuando se registra un pago por primera vez puede incluir `null`, así que obtén el pago para leerlo.
>
> **display\_name** `string` *required*
>
> Nombre del instrumento visible para el comprador: "Visa •••• 4242" cuando se obtuvo la tarjeta; de lo contrario,
> el propio nombre del método ("Klarna").
>
> **icons** `object` *required*
>
> El conjunto de iconos estándar: formas cuadrada y de tarjeta, cada una en variantes de color claras y oscuras.
>
> > [accordion] Propiedades
> >
> > **card** `object` *required*
> >
> > El mosaico con proporciones de tarjeta de crédito (48x30).
> >
> > > [accordion] Propiedades
> > >
> > > **dark** `object` *required*
> > >
> > > La variante de color para superficies oscuras.
> > >
> > > > [accordion] Propiedades
> > > >
> > > > **png\_1x** `string` *required*
> > > >
> > > > Alternativa rasterizada al tamaño nativo de la forma.
> > > >
> > > > **png\_2x** `string` *required*
> > > >
> > > > Alternativa rasterizada a doble densidad.
> > > >
> > > > **png\_4x** `string` *required*
> > > >
> > > > Alternativa rasterizada a cuádruple densidad.
> > > >
> > > > **svg** `string` *required*
> > > >
> > > > El archivo vectorial. Úsalo preferentemente en cualquier lugar donde se renderice SVG.
> > >
> > > **light** `object` *required*
> > >
> > > La variante de color para superficies claras.
> > >
> > > > [accordion] Propiedades
> > > >
> > > > **png\_1x** `string` *required*
> > > >
> > > > Alternativa rasterizada al tamaño nativo de la forma.
> > > >
> > > > **png\_2x** `string` *required*
> > > >
> > > > Alternativa rasterizada a doble densidad.
> > > >
> > > > **png\_4x** `string` *required*
> > > >
> > > > Alternativa rasterizada a cuádruple densidad.
> > > >
> > > > **svg** `string` *required*
> > > >
> > > > El archivo vectorial. Úsalo preferentemente en cualquier lugar donde se renderice SVG.
> >
> > **square** `object` *required*
> >
> > El mosaico cuadrado (32x32).
> >
> > > [accordion] Propiedades
> > >
> > > **dark** `object` *required*
> > >
> > > La variante de color para superficies oscuras.
> > >
> > > > [accordion] Propiedades
> > > >
> > > > **png\_1x** `string` *required*
> > > >
> > > > Alternativa rasterizada al tamaño nativo de la forma.
> > > >
> > > > **png\_2x** `string` *required*
> > > >
> > > > Alternativa rasterizada a doble densidad.
> > > >
> > > > **png\_4x** `string` *required*
> > > >
> > > > Alternativa rasterizada a cuádruple densidad.
> > > >
> > > > **svg** `string` *required*
> > > >
> > > > El archivo vectorial. Úsalo preferentemente en cualquier lugar donde se renderice SVG.
> > >
> > > **light** `object` *required*
> > >
> > > La variante de color para superficies claras.
> > >
> > > > [accordion] Propiedades
> > > >
> > > > **png\_1x** `string` *required*
> > > >
> > > > Alternativa rasterizada al tamaño nativo de la forma.
> > > >
> > > > **png\_2x** `string` *required*
> > > >
> > > > Alternativa rasterizada a doble densidad.
> > > >
> > > > **png\_4x** `string` *required*
> > > >
> > > > Alternativa rasterizada a cuádruple densidad.
> > > >
> > > > **svg** `string` *required*
> > > >
> > > > El archivo vectorial. Úsalo preferentemente en cualquier lugar donde se renderice SVG.
>
> **installment\_count** `number | null` *required*
>
> Solo para métodos de pago a plazos: en cuántos pagos se divide el cargo. Son datos, no
> texto: compón y traduce la etiqueta en el cliente.
>
> **payment\_method\_type** `string` *required*
>
> El identificador del tipo de método de pago, p. ej. `card`, `klarna`, `apple_pay`.

**payment\_method\_id** `string | null` *required*

El método de pago guardado, con el prefijo `payt_`, listo para cobrarse con Create
Payment. Es null hasta que la configuración tenga el estado `succeeded`.

**payment\_method\_type** `string | null` *required*

El tipo de instrumento que se guarda, por ejemplo `card` o `us_bank_account`.

**return\_url** `string | null` *required*

A dónde llega el comprador después de completar un paso externo, o `null` para dejarlo
donde está.

**status** `string` *required*

Cuánto ha avanzado la configuración. **Un 201 o 200 significa que respondimos, no que el método se haya guardado: ramifica siempre según este campo.** `requires_action`: el comprador tiene un paso pendiente; pasa `client_secret` a los elements o consulta periódicamente Retrieve setup status. `processing`: el procesador está decidiendo. `succeeded`: el método está guardado, y solo este estado significa guardado. `canceled`: abandonado o rechazado; consulta `last_setup_error`.

Opciones disponibles: `processing`, `succeeded`, `canceled`, `requires_action`

**three\_ds\_level** `string | null` *required*

Comportamiento de 3D Secure para los pagos con tarjeta en sesión admitidos. `mandate_challenge` exige un desafío 3DS antes de procesar el pago; `mandate_if_required` exige un desafío solo cuando el procesador de pagos lo requiere; `frictionless_if_required` usa el flujo 3DS sin fricción habitual. Los pagos de \$1,000 o más usan `mandate_if_required` a menos que se seleccione `mandate_challenge`. Los requisitos de riesgo y de recuperación de autenticación pueden anular la preferencia. Es la configuración solicitada para esta configuración, o `null` cuando no está definida.

Opciones disponibles: `mandate_challenge`, `mandate_if_required`, `frictionless_if_required`

**three\_ds\_verified** `boolean` *required*

True cuando el comprador completó 3D Secure al guardar este método de pago.

**updated\_at** `string` *required*

Cuándo se actualizó el setup intent por última vez, como marca de tiempo ISO 8601.

**user** `object | null` *required*

El usuario que guarda el método de pago. Es null cuando el comprador es una cuenta en lugar de un usuario.

> [accordion] Propiedades
>
> **id** `string` *required*
>
> ID de usuario, con el prefijo `user_`.
>
> **name** `string | null` *required*
>
> Nombre visible.
>
> **profile\_picture** `object` *required*
>
> Contenedor del avatar. Su `url` siempre está presente y es un marcador de posición generado cuando el usuario no definió ninguna imagen.
>
> > [accordion] Propiedades
> >
> > **url** `string` *required*
> >
> > URL de la imagen del avatar. Siempre está presente. Es un marcador de posición generado cuando el usuario no definió ninguna imagen.
>
> **username** `string` *required*
>
> Nombre de usuario público.

```json SetupIntent theme={null}
{
	"id": "sint_xxxxxxxxxxxxxx",
	"account_id": "biz_xxxxxxxxxxxxxx",
	"checkout_configuration_id": null,
	"client_secret": null,
	"created_at": "2026-09-22T12:00:00.000Z",
	"last_setup_error": null,
	"member_id": "mber_xxxxxxxxxxxxxx",
	"metadata": {
		"customer_id": "cus_4417"
	},
	"payment_method_id": "payt_xxxxxxxxxxxxxx",
	"payment_method_type": "card",
	"return_url": "https://shinetime.example/billing/saved",
	"status": "succeeded",
	"three_ds_verified": false,
	"three_ds_level": "mandate_challenge",
	"updated_at": "2026-09-22T12:00:00.000Z",
	"user": {
		"id": "user_xxxxxxxxxxxxxx",
		"name": "Dana Whitfield",
		"profile_picture": {
			"url": "https://ui-avatars.com/api/"
		},
		"username": "danawhitfield"
	},
	"payment_instrument": {
		"card": {
			"brand": "visa",
			"issuer_identification_number": "41111111",
			"last4": "4242",
			"exp_month": 11,
			"exp_year": 2030,
			"network_transaction_id": "016153570198200"
		},
		"display_name": "Visa •••• 4242",
		"icons": {
			"card": {
				"dark": {
					"png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
					"png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
					"png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
					"svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
				},
				"light": {
					"png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
					"png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
					"png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
					"svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
				}
			},
			"square": {
				"dark": {
					"png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
					"png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
					"png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
					"svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
				},
				"light": {
					"png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
					"png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
					"png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
					"svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
				}
			}
		},
		"installment_count": null,
		"payment_method_type": "card"
	}
}
```
