Medios de pago guardados

Tu cliente guarda su medio de pago una vez y después le cobras sin que intervenga. Es lo que usan las suscripciones para cobrar cada periodo.

Hoy disponible solo en modo prueba (kuti_test_…). En producción el método YAPE todavía no se ofrece: te avisaremos en el changelog cuando esté activo.

Con el método YAPE tu cliente aprueba una sola vez, en su app de Yape, que tu negocio le cobre. Su Yape queda guardado y los cobros siguientes se debitan sin que intervenga. Es la base de las Suscripciones y del pago con un toque.

1
Crea un cobro con YAPE
POST /payment-intents con un cliente y "YAPE" en payment_method_types. Puedes ofrecerlo junto con QR y banca.
2
Tu cliente afilia su Yape
En el enlace de pago elige Yape y escribe su número. Recibe la solicitud en su app y tiene 15 minutos para aprobarla.
3
KUTI cobra y guarda
Apenas aprueba, KUTI debita ese cobro y guarda su Yape. Recibes payment_method.attached y payment.succeeded.
4
Los siguientes cobros
Ya no necesita aprobar: le cobras con una suscripción, con un toque desde el enlace o directo desde tu backend.

Reglas

El cobro debe tener cliente: el Yape guardado pertenece a ese cliente en tu negocio.
Máximo S/ 2,500 por cobro.
El Yape guardado es por negocio y por modo: el de prueba no existe en producción.
KUTI no guarda el número: solo los últimos 4 dígitos (display.phone_last4).
Tu cliente puede quitar la afiliación desde su app de Yape. KUTI se entera al intentar cobrar: el medio pasa a REVOKED y recibes payment_method.revoked.

Cobrar con el Yape guardado

Hay tres formas. En todas el resultado es un cobro normal: llega payment.succeeded.

Forma	Cuándo usarla	Cómo
Directo desde tu backend	Tu cliente no está presente (consumo, renovación, cuota).	POST /payment-intents con payment_method (pm_…) y confirm: true.
Con un toque desde el enlace	Le envías el enlace a su WhatsApp o correo.	saved_payment_methods: "enabled" al crear el cobro. Durante 30 minutos el enlace le muestra su Yape guardado.
Con código por correo	Tu cliente abre un enlace sin ese permiso.	No haces nada: el enlace le pide un código de 6 dígitos que llega a su correo registrado y luego le muestra su Yape.

Cobro directo, sin el cliente presentebash

curl -s https://api.kuti.pe/v1/payment-intents \
  -H 'Authorization: Bearer kuti_test_…' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 6f1f0c1e-7a55-4b3e-9d1e-2f0d6c0a7b11' \
  -d '{
    "amount": { "amount": "184.00", "currency": "PEN" },
    "customer": { "id": "cus_01J8Z3K4M5N6P7Q8R9S0T1U2V3" },
    "payment_method_types": ["YAPE"],
    "payment_method": "pm_01J8Z3K4M5N6P7Q8R9S0T1U2V3",
    "confirm": true,
    "description": "Consumo de octubre"
  }'

La respuesta trae last_saved_method_payment con el resultado del débito. Si se deniega, el cobro queda abierto y su enlace sigue sirviendo: tu cliente puede pagarlo con cualquier método.

last_saved_method_payment.status	Qué significa
SUCCEEDED	Cobrado. El cobro ya está SUCCEEDED.
PROCESSING	Se está confirmando; se resuelve solo en segundos. Espera payment.succeeded.
FAILED	Denegado. El motivo viene en failure_code.

failure_code	Qué pasó	Qué hacer
insufficient_funds	Tu cliente no tiene saldo en Yape.	Reintenta más tarde o envíale el enlace.
payment_method_revoked	Quitó la afiliación desde su app.	No reintentes: tiene que afiliar de nuevo.
amount_exceeds_method_limit	El monto pasa el tope del método.	Cobra un monto menor o usa otro método.
temporarily_unavailable	Falla temporal.	Reintenta en unos minutos.

El permiso saved_payment_methods: "enabled" hace que cualquiera con el enlace vea el Yape guardado durante 30 minutos. Actívalo solo cuando envíes el enlace a un canal que es de tu cliente. Se renueva con POST /payment-intents/{id}/saved-payment-methods/enable.

Los medios guardados de un cliente

Listar: GET /customers/{id}/payment-methods
Desvincular: DELETE /customers/{id}/payment-methods/{payment_method_id}. Deja de poder cobrarse de inmediato.

status	Qué significa
ACTIVE	Se puede cobrar sobre él.
REVOKED	Tu cliente lo quitó en su app. No se puede cobrar.
DETACHED	Lo desvinculaste tú. No aparece en la lista.

Eventos

Evento	Cuándo	data
payment_method.attached	Tu cliente afilió su Yape.	payment_method
payment_method.revoked	Quitó la afiliación desde su app (lo sabemos al intentar cobrar).	payment_method
payment_method.detached	Lo desvinculaste desde KUTI.	payment_method
payment.succeeded	Se cobró sobre el Yape guardado.	payment_intent

Probarlo

En modo prueba no hay app de Yape. Desde el panel, en Cobros → Simular pago, eliges si tu cliente aprueba, rechaza o deja vencer la afiliación, y cómo responde el débito (cobrado, sin saldo, en proceso).

Suscripciones — cobro automático por periodo
Crear cobro — payment_method + confirm
Medios guardados — GET /customers/{id}/payment-methods