plan_, y los artículos de la factura la reciben como plan_id. Usa una factura cuando acuerdes un precio con un cliente antes de que pague, como un presupuesto, un servicio o un pedido de empresa. Construyes un borrador hasta que esté correcto y luego lo emites para fijar los totales y abrirlo para el pago. Enviarlo hace eso y además lo manda por correo en una sola llamada. Para enviar una desde tu panel sin código, consulta Crea y envía facturas.
Las facturas de esta página necesitan
Api-Version-Date: 2026-10-24 o posterior en cada solicitud. Las solicitudes con una versión anterior llegan a la API de facturas heredada, que funciona de otra manera. Consulta Antes de empezar.Cómo funciona una factura
Una factura nativa es un pago. Su ID empieza porpay_ y se mantiene igual después de que el cliente pague, así que también puedes leerla con Retrieve Payment. Cada factura recibe además el siguiente número de la secuencia propia de tu cuenta, como #00000042, o #ACME-00000042 cuando tu cuenta tiene un prefijo de factura.
- Creas un borrador con artículos, un cliente y datos de facturación. Un borrador no cobra nada ni envía correos a nadie.
- Lo emites o lo envías. Emitirla calcula el impuesto final y abre la factura para el pago. Enviarla la emite y la manda por correo, ya sea ahora o en el momento que programes.
- El cliente paga. Whop cobra el método de pago guardado del cliente en cuanto emites o envías la factura, o el cliente paga a través del checkout alojado de Whop.
- Realizas el fulfillment del pedido desde el webhook
payment.succeeded.
release_method: buy_now en lugar de una lista de espera. Una variante de pago único se cobra una vez, y una variante recurrente inicia una suscripción cuando se paga la factura. Consulta Factura una suscripción, que también explica cómo detenerla después de un número determinado de pagos.
Antes de empezar
Envía la versión de la API
/invoices sirve dos APIs diferentes, y el Api-Version-Date al que se resuelve tu solicitud decide cuál responde.
Emitir, enviar, cancelar un envío programado y generar un PDF existen solo en la API nativa, así que llegan a las facturas nativas sea cual sea la versión que envíes. Las rutas que tienen ambas APIs, como
GET /invoices y POST /invoices/{id}/void, siguen la versión.
Envía el encabezado en cada solicitud en lugar de depender de la versión fijada de una clave, para que cambiar de clave nunca te mueva entre ambas. Versiones de la API explica las versiones fijadas y el changelog.
La API nativa no lista ni recupera las facturas heredadas
inv_, y la API heredada no devuelve las nativas.
Llama a la API
Los ejemplos de esta página llaman a la API mediante un pequeño helper que envía el encabezado de versión en cada solicitud.Idempotency-Key en cada POST para que un reintento nunca cree una segunda factura ni repita una acción. Generate Invoice PDF es la excepción: cada llamada crea un archivo nuevo, así que no reproduce respuestas.
Crea un borrador
Create Invoice guarda un borrador conPOST /invoices.
201 Created con el borrador. Crear un borrador no cobra nada, no envía correos y no envía webhooks. Esta respuesta muestra un subconjunto de los campos:
account_id es la cuenta que emite la factura, con el prefijo biz_. Una clave de API de cuenta puede omitirlo para usar su propia cuenta. Create Invoice enumera todos los campos de solicitud y respuesta.
Un borrador usa su número al crearlo, así que un borrador que descartas deja un hueco en tu secuencia. Para descartar un borrador, elimínalo. Para mantenerlo en tu lista, anúlalo en su lugar.
Añade artículos
items acepta de 1 a 50 artículos. Cada artículo recibe plan_id para una variante existente o plan para encontrar o crear una en línea, además de una quantity opcional.
Un plan en línea usa la misma entrada de búsqueda o creación que Create Payment, por ejemplo { "plan": { "product_id": "prod_xxxxxxxxxxxxx", "plan_type": "one_time", "initial_price": 250, "currency": "usd" } }. Necesita plan:create, y un product en línea también necesita el permiso de producto, access_pass:create o access_pass:update.
La creación y la actualización rechazan los artículos que incumplen estas reglas:
- Cada artículo es una variante de compra inmediata de tu cuenta. Una variante aparece una sola vez, así que usa
quantitypara más unidades. - Ninguna variante está archivada, y emitir o enviar un borrador lo vuelve a comprobar, así que desarchiva la variante o elige otra.
quantityestá entre 1 y 999,999, y es mayor que 1 solo para una variante que permite varias cantidades. Las variantes recurrentes no lo permiten, así que la cantidad de un artículo recurrente es 1.- Una variante recurrente debe pertenecer a un producto.
- Todos los artículos usan la misma moneda.
- En una factura con varios artículos, cada artículo que tenga un producto debe ser un producto regular (el tipo de producto estándar), no una app. Los artículos recurrentes comparten un mismo periodo de facturación, duración de prueba gratuita y
split_pay_required_payments, y todos los artículos necesitan ajustes de pago, impuestos y acceso compatibles. Las variantes con campos personalizados o contraseña no se pueden combinar. Los artículos sin producto, como una tarifa personalizada, pueden ir junto al resto.
label, que es el título del producto, o el título de la variante si la variante no tiene producto. El correo, el PDF y el checkout lo muestran.
El borrador conserva el precio que tenía cada variante cuando guardaste sus artículos, así que un cambio de precio posterior en la variante no altera la factura. Un artículo de pago único se cobra a su precio. A partir de la versión de la API 2026-11-11, crear o sustituir un artículo recurrente incluye su initial_price más su renewal_price en la primera factura. Las versiones fijadas anteriores usan solo el precio de renovación. Las ediciones que omiten items conservan los precios guardados.
Define el cliente y los datos de facturación
Envía
member_id o email_address, y billing_address o mailing_address_id, nunca ambos de un par. Una dirección de facturación necesita un cliente. El cliente es opcional en un borrador y obligatorio para emitirlo.
Whop calcula el impuesto cuando emites la factura, usando la dirección de facturación para ubicar al cliente. Cuando se aplican impuestos y Whop no puede saber dónde está el cliente, la emisión se rechaza, así que añade una dirección de facturación siempre que cobres impuestos.
Edita un borrador
Update Invoice modifica un borrador conPATCH /invoices/{id}. Envía solo los campos que cambias.
itemssustituye la lista completa y lee el precio actual de cada variante. Omítelo para conservar los artículos y precios guardados.- Cambiar
member_idelimina la dirección de facturación y el método de pago guardados, a menos que envíes otros nuevos. Conservarecipient_emails, así que envía también una lista nueva, o el cliente anterior seguirá recibiendo el correo de la factura. - No se aceptan
email_addressnicustomer_name. Envía unmember_iddiferente para facturar a otra persona. - Un borrador con un envío programado solo acepta un cambio en
recipient_emailshasta que canceles el envío. - Una vez emitida la factura, el único cambio que puedes hacer es
recipient_emails, enviado por sí solo, y solo mientras la factura estéopenouncollectible. Cualquier otra edición se rechaza con un400.
Elige cómo paga el cliente
Hay dos formas de cobrar una factura emitida. Elige una antes de emitirla, porque el método de pago guardado va en el borrador.
Una factura emitida recibe un
checkout_link aunque tenga un método de pago guardado. Si el cobro automático falla, el cliente puede seguir pagando a través del checkout.
Cobra un método de pago guardado
Añade un método de pago guardado al borrador conpayment_method_id. Debe ser uno de los métodos guardados del cliente. Guarda métodos de pago muestra cómo un cliente guarda uno, y List payment methods encuentra los que tiene un miembro.
Cuando emites o envías la factura y su total es mayor que cero, Whop:
- Ejecuta las mismas comprobaciones que Create Payment ejecuta sobre un método de pago guardado.
- Reserva stock para las cantidades facturadas y prepara las comisiones del pago.
- Devuelve la factura como
openy cobra el método fuera de sesión. El cobro se ejecuta en elcharge_atque pasas a Issue Invoice o Send Invoice; si no, endue_atmientras aún sea futuro; si no, de inmediato.scheduled_charge_atmuestra un cobro que aún está por llegar.
payment.succeeded para el ID pay_ de la factura. Una factura pagada completa la membresía, y tu metadata queda en el cobro y en la membresía. Reglas de pago en los pagos de facturas explica cómo tus reglas de pago filtran el cobro.
Si se rechaza el cobro automático
Un cobro rechazado deja la factura enopen y libera el stock reservado. Recupera la factura como un pago y lee failure_message para saber por qué falló el último intento.
Cuando el cobro se rechaza o requiere que el cliente actúe, Whop envía por correo el enlace de pago de la factura a sus destinatarios, para que el cliente pueda pagar a través del checkout. Es el único correo que Whop envía para una factura que emites sin enviarla. Necesita un checkout_link y al menos una entrada en recipient_emails, y no cuenta para el límite de envíos.
Emite la factura
Issue Invoice convierte un borrador en una factura abierta. Whop vuelve a comprobar la factura, calcula el impuesto final y establecestatus en open y totals_status en final. Cuando la factura tiene un método de pago guardado y un total mayor que cero, Whop lo cobra a continuación, como se describe en Cobra un método de pago guardado.
- El impuesto pasa a ser final.
tax_amountesnullen un borrador y se establece al emitirlo.totalyamount_duelo incluyen. - Whop crea la membresía del cliente cuando la factura cobra un producto. Permanece en borrador, sin acceso, hasta que se paga la factura. Una factura cuyos artículos no tienen ningún producto no recibe membresía.
payment.createdse dispara una vez para el IDpay_de la factura.- Volver a emitir es seguro. Emitir una factura que ya está
openvuelve a ejecutar las mismas comprobaciones y, si se superan, la devuelve sin cambios: sus totales se mantienen y no se vuelve a cobrar nada. - Emitir no envía la factura por correo, salvo el enlace de pago tras un cobro rechazado. Para enviar la factura por correo, envíala en su lugar, o entrega tú mismo el enlace de checkout.
Obtén el enlace de checkout
Una factura emitida yopen lleva un checkout_link, un valor firmado con el formato pay_xxxxxxxxxxxxx.<signature>. Abre la factura en el checkout alojado de Whop a su precio fijo.
1
Lee el enlace de la factura emitida
checkout_link es null a menos que la factura esté open, así que los borradores y las facturas pagadas, anuladas o incobrables no tienen ninguno. También es null para una factura emitida a un comprador empresarial, para una cuya membresía se canceló y cuando tu credencial no tiene payment:charge. Un comprador empresarial es un cliente que es otra cuenta de Whop en lugar de una persona.2
Construye la URL del checkout alojado
Divide el enlace por su primer
.: el ID pay_ de la factura va antes y el token después.3
Envíaselo al cliente
Envía la factura para que Whop mande el enlace por correo, o pon la URL en tu propio correo o página de factura. Solo el cliente de la factura puede pagar a través de él. Cualquier otra persona es rechazada y se le pide que inicie sesión como el cliente de la factura. El enlace deja de funcionar una vez que la factura se paga, se anula o se marca como incobrable.
4
Realiza el fulfillment desde el webhook
Escucha
payment.succeeded para el ID pay_ de la factura, igual que con el cobro automático. Webhooks muestra un handler.Envía, programa y recuerda
Send Invoice envía una factura por correo conPOST /invoices/{id}/send. Enviar un borrador primero lo emite, igual que Issue Invoice. Enviar una factura open la vuelve a mandar por correo.
open necesita un checkout_link para enviarse, y un borrador necesita un cliente que no sea un comprador empresarial. Un borrador facturado a un comprador empresarial aún puede enviarse cuando tiene un método de pago guardado, porque en su lugar se cobra.
Quién recibe el correo
Cada envío manda un correo a cada dirección una vez, como un correo separado, para que los destinatarios nunca vean las direcciones de los demás. Las direcciones son:- El correo de la cuenta de Whop del cliente, que el PDF de la factura imprime bajo Bill to.
- Cada entrada de
recipient_emails.
recipient_emails en minúsculas y elimina los duplicados de la lista, así que una dirección que aparece en ambos recibe un solo correo.
Un recipient_emails vacío significa que Whop no envía correos a nadie, incluido el cliente. Úsalo para evitar que Whop envíe una factura por correo:
- Send Invoice rechaza la factura, a menos que en su lugar cobre un método de pago guardado.
- No se envía ningún enlace de pago después de un cobro rechazado.
- No se envían recordatorios. Vaciar
recipient_emailsen una facturaopendetiene sus recordatorios restantes.
Cuándo Whop cobra en lugar de enviar el correo
Un borrador con unpayment_method_id y un total mayor que cero se cobra en lugar de enviarse por correo, igual que cuando lo emites. Si se rechaza el cobro automático explica qué ocurre cuando el cobro falla. Un borrador así puede enviarse con recipient_emails vacío, porque nadie necesita el correo.
Límite de envíos
Cada factura puede enviarse por correo tres veces en 24 horas, incluido el envío que la emitió. Un cuarto envío en ese intervalo se rechaza con un429 cuyo error.code es invoice_send_limit_reached. Los recordatorios, el enlace de pago tras un cobro rechazado y un envío que cobra en lugar de mandar un correo no cuentan para el límite.
Programa un envío
Para enviar un borrador más tarde, pasasend_at. El borrador sigue siendo un borrador y muestra la hora en scheduled_send_at. En ese momento, Whop lo envía como si hubieras llamado a Send Invoice entonces.
- Solo se puede programar un borrador, y
send_atdebe estar en el futuro. Whop comprueba los destinatarios y el enlace de pago al programarlo, igual que en un envío inmediato. - Vuelve a enviar con un nuevo
send_atpara cambiar la hora. - La edición queda bloqueada hasta que se produce el envío o lo cancelas. Una actualización que solo cambia
recipient_emailssigue funcionando, pero no puede eliminar el último destinatario de un borrador que no se va a cobrar. - Cancel Scheduled Send con
POST /invoices/{id}/unschedule.scheduled_send_atvuelve anully el borrador se puede editar de nuevo. Cancelar una factura sin envío programado la devuelve sin cambios. - Anular un borrador programado detiene su envío programado.
send_at. Si se rechaza, por ejemplo porque se eliminó una variante después de programarlo, la factura sigue siendo un borrador, scheduled_send_at vuelve a null y la API no devuelve el motivo. Cualquier otro fallo se reintenta aproximadamente cada 10 minutos, hasta 12 intentos en total. Hasta que un intento tiene éxito o Whop deja de reintentar, scheduled_send_at muestra la hora del siguiente intento en lugar de null. Lee la factura después de send_at para confirmar que está open.
Recordatorios
Cuando Send Invoice envía por correo una factura que tienedue_at, Whop también programa recordatorios 1, 3, 7, 14, 30 y 60 días después de due_at, omitiendo los que ya hayan pasado. Cada recordatorio va a las mismas direcciones que la factura e indica cuántos días lleva vencida.
Los recordatorios solo se envían mientras la factura está open, así que se detienen una vez que se paga, se anula o se marca como incobrable. Un recordatorio que vence mientras hay un pago en curso espera hasta que el pago termina. Una factura que emites sin enviar, o una que se cobra en lugar de enviarse por correo, no recibe recordatorios.
Historial de correos
List Invoice Sends devuelve los lotes de correo registrados conGET /invoices/{id}/sends, del más reciente al más antiguo. Incluye correos iniciales y repetidos, correos programados, recordatorios y seguimientos de pago tras un cobro fallido a un método de pago guardado. Usa la primera entrada para el envío registrado más reciente, y page_info.end_cursor como after para leer entradas más antiguas. Los lotes manuales usan send cuando la factura no tiene historial de correos completados anterior y resend en caso contrario. El tipo se selecciona cuando se registra el lote completado, así que las solicitudes encoladas juntas se clasifican por orden de finalización. Los correos anteriores no registrados siguen siendo desconocidos.
Cada entrada contiene kind, sent_at, recipient_count, recipients y actor. Leer el historial requiere payment:basic:read. Las direcciones también requieren member:email:read. Sin él, recipients está vacío. El remitente requiere además company:authorized_user:read. De lo contrario, actor es null. Los envíos automáticos y las claves de API de cuenta también tienen un actor null.
El worker añade una entrada después de enviar el lote completo para su entrega. Para un lote parcial, añade una entrada solo si un reintento completa el lote. La entrada conserva la lista original de destinatarios. Un lote registrado no confirma la entrega en la bandeja de entrada. El sistema de correo puede suprimir mensajes si la factura o los destinatarios cambian antes de la entrega. El historial excluye los correos enviados antes de que se introdujera esta función. Emitir una factura sin enviarla por correo no añade ninguna entrada al historial.
Descarga un PDF
Generate Invoice PDF genera la factura como PDF y devuelve un enlace de corta duración a ella. Necesitapayment:basic:read y funciona con cualquier estado.
url y expires_at. El enlace funciona durante 15 minutos, y cualquiera que lo tenga puede descargar el archivo. Genera uno nuevo cuando caduque.
El PDF destaca tu negocio: el nombre de tu cuenta encabeza la página, y el pie indica que Whop Inc emite la factura en tu nombre y por tu cuenta. Muestra el número de factura, su fecha y fecha de vencimiento, y los datos de Bill to. Cada artículo muestra su cantidad, precio unitario e importe, seguidos del subtotal, la tarifa de servicio, el impuesto y el importe adeudado. Una factura con un artículo recurrente también indica el importe de renovación y con qué frecuencia se renueva. El PDF de un borrador muestra sus totales estimados, con el impuesto en cero hasta que lo emitas.
Parte del contenido depende de los permisos de tu credencial:
Factura una suscripción
Añade una variante recurrente a una factura para iniciar una suscripción cuando el cliente la pague. Después, Whop la renueva una vez por periodo de facturación.- La factura cobra el primer periodo y cualquier tarifa inicial. Un artículo recurrente debe pertenecer a un producto y tiene una cantidad de 1. A partir de la versión de la API
2026-11-11, su primera factura cobrainitial_pricemásrenewal_price. El pago inicia de inmediato el primer periodo de facturación pagado, a menos que la variante tenga una prueba gratuita. En ese caso, la suscripción empieza con la prueba. En el panel, un artículo recurrente personalizado tiene un campo opcional Upfront fee. Elinitial_pricede la línea indica esa parte única deunit_amount, y la página de la factura, el correo y el PDF la muestran en su propia línea Upfront fee. - Pagar la factura inicia la suscripción, tanto si Whop cobra el método de pago guardado al emitirla como si el cliente paga a través del
checkout_link. El primer periodo empieza con el pago. El checkout abierto desde el enlace indica el importe de renovación, incluida la comisión del comprador de la factura, y con qué frecuencia se renueva. - Cada renovación se cobra de la forma que elegiste al emitir o enviar la factura. Solo cobra los artículos recurrentes, con la comisión del comprador de la factura, al precio de renovación que tenía cada variante cuando emitiste la factura. Puede diferir del precio guardado en el borrador si el precio de la variante cambió después de guardar los artículos. Los artículos de pago único se cobran una vez.
collection_method a Issue Invoice o Send Invoice para elegir cómo se cobran las renovaciones. Un envío programado aplica el collection_method con el que lo programaste, que el borrador muestra como scheduled_collection_method.
send_invoice necesita al menos una dirección en recipient_emails y no está disponible para facturas emitidas a una empresa. Mientras se aplique, no se puede eliminar el último destinatario de la factura. Una factura sin artículos recurrentes rechaza collection_method. Pagar la primera factura con tarjeta conserva send_invoice.
Cada renovación es su propio pago, con su propio ID pay_ y sus propios webhooks payment.*. Una renovación charge_automatically no es una factura numerada, así que no aparece en List Invoices. Una renovación send_invoice es una factura numerada en List Invoices, y Whop no la cobra automáticamente. La suscripción permanece en past_due hasta que el cliente paga a través del checkout_link de la factura. Mientras tanto, el cliente conserva el acceso. Cancela la membresía para detener las renovaciones. Una vez cancelada la membresía, el checkout_link de una factura de renovación abierta deja de funcionar.
Para encontrar la suscripción, recupera la factura como un pago y lee su membership_id, que necesita member:basic:read.
Empieza con una prueba gratuita
Una factura respeta eltrial_period_days de una variante recurrente, igual que el checkout. La primera factura cobra solo el initial_price de la variante. Pagarla inicia la prueba, y la primera renovación cobra renewal_price cuando termina la prueba. Las facturas creadas antes del 2026-11-16 a las 17:00 UTC cobran el primer periodo y omiten la prueba.
- Un cliente que ya tuvo una suscripción a la variante no recibe prueba. Su primera factura cobra
initial_pricemásrenewal_price. Las facturas de renovación nunca inician una prueba. - La prueba viene de la variante. Para un artículo recurrente personalizado, establece
variant.trial_period_days. Untrial_period_daysa nivel de artículo se rechaza. - Todos los artículos recurrentes de la factura necesitan la misma duración de prueba.
- Cuando la factura no cobra nada, emítela o envíala con un
payment_method_id, que inicia la prueba de inmediato, o concollection_method: "send_invoice". - En el panel, un artículo recurrente personalizado tiene un campo Free trial days. El plan de facturación de un producto muestra su propia prueba.
Detén la suscripción tras un número determinado de pagos
Para cobrar un plan de pagos fijo, como seis pagos mensuales, establecesplit_pay_required_payments en la variante recurrente, de 2 a 115. La factura es el primer pago, incluida cualquier tarifa inicial. Por ejemplo, una tarifa inicial de $75 con tres cuotas de $40 cobra $115, luego $40 y luego $40. Whop deja de renovar una vez realizados esos pagos, y la membresía sigue activa. El cliente no puede cancelar la suscripción por su cuenta antes de ese momento, pero tú sí. Déjalo sin definir para renovar hasta que se cancele la suscripción.
Estados y ciclo de vida
status toma sus valores de los pagos, así que una factura también puede mostrar un estado de pago como pending mientras hay un pago en curso. totals_status indica si los campos de dinero son finales: estimated mientras la factura es un borrador, final después de emitirla. overdue es true para una factura open o uncollectible cuyo due_at ya pasó.
Anula o marca como incobrable
Void Invoice cancela una facturadraft, open o uncollectible. Anular una factura que ya está anulada la devuelve sin cambios, y una factura pagada no se puede anular.
Marca una factura como incobrable para registrar que no esperas cobrarla. Solo se puede marcar una factura open, y volver a marcar una factura incobrable la devuelve sin cambios. Una factura incobrable no tiene checkout_link y no recibe recordatorios.
Este ejemplo marca una factura open como incobrable y luego la anula:
Elimina una factura
Delete Invoice elimina una facturadraft o void con DELETE /invoices/{id}. La respuesta es { id, deleted: true }. Una factura eliminada ya no aparece en List Invoices ni en List Payments, y su ID devuelve un 404. No puedes deshacer una eliminación.
Anula una factura open antes de eliminarla. Un borrador con un envío o cobro programado necesita primero Cancel Scheduled Send. Un borrador de factura de renovación no se puede eliminar mientras cobre una suscripción. Una factura anulada que recaudó dinero o que aún espera una transferencia bancaria no se puede eliminar, como tampoco una factura pagada, pendiente o incobrable. El campo deletable de una factura es true cuando se puede eliminar.
Eliminar necesita invoice:update o payment:charge. El número de un borrador eliminado no se reutiliza.
Lista y recupera facturas
List Invoices devuelve las facturas que tu credencial puede leer, de la más reciente a la más antigua. Una clave de API ve su propia cuenta, y un token de usuario ve todas las cuentas cuyos pagos puede leer el usuario. Acota la lista con estos parámetros de consulta:
Un borrador programado es uno con
scheduled_send_at. Una factura open nunca está programada, ni tampoco un borrador que se envía en su fecha de vencimiento.
Ordena con order (created_at, due_at o scheduled_send_at) y direction (asc o desc). Ordenar por due_at o scheduled_send_at coloca al final las facturas sin esa fecha. La respuesta es { data, page_info }. Mientras page_info.has_next_page sea true, pasa page_info.end_cursor como after para leer la página siguiente.
pay_. List Payments omite los borradores.
Para exportar facturas como archivo CSV, llama a Create Export con resource: "receipt_invoices". Necesita payment:basic:read y payment:basic:export. Las columnas del cliente solo aparecen cuando tu credencial también tiene member:basic:read o member:email:read.
Webhooks
Las facturas nativas envían webhooks de pago para su IDpay_. Los eventos invoice.* pertenecen a la API de facturas heredada, y las facturas nativas no los envían.
Otros eventos
payment.*, como payment.failed, también pueden llegar para el ID pay_ de la factura a medida que cambian sus intentos de pago. Suscríbete a ellos con la guía de webhooks.
Para realizar el fulfillment de un pedido, guarda el id de la factura con el pedido cuando crees el borrador. El data de un evento payment.succeeded es el pago, así que data.id es el ID pay_ de la factura. Después de verificar el evento, busca el pedido por ese ID. En este handler, orders representa tu propio almacén de pedidos:
fulfilled evita que un evento reenviado realice el fulfillment del pedido dos veces. Las renovaciones de suscripción tienen sus propios ID pay_, así que no coinciden con una factura.
Reglas de pago en los pagos de facturas
Tus reglas de pago se ejecutan sobre los pagos de facturas después del propio filtrado antifraude de Whop, como en cualquier checkout. Lo que pueden hacer depende de si el cliente está presente.- El cobro automático al emitir es fuera de sesión. Una regla
blocklo rechaza, y una reglaallowlo exime de tus demás reglas. Las reglasreviewyenforce_3dsse omiten porque el cobro es fuera de sesión. - Un pago a través del enlace de checkout es en sesión. Se aplican las cuatro acciones, con los límites de elegibilidad de Gestiona el fraude.
customer_email es el correo de la cuenta de Whop del cliente. El payment_rule_matches del pago enumera la regla que lo decidió. Una regla omitida no aparece.
Facturas en el panel
La página Invoices lista, crea y envía facturas nativas. Las facturas heredadas están en su pestaña Legacy invoices, que se explica en Envía una factura.Permisos
Toda escritura necesita
payment:charge, el mismo permiso que Create Payment, y toda lectura necesita payment:basic:read. Los permisos invoice:* pertenecen a la API de facturas heredada, y las facturas nativas no los usan. Una creación o actualización que envía un artículo plan en línea también necesita plan:create.
Algunos campos necesitan un permiso propio. Sin él, el campo vuelve como null, y recipient_emails vuelve vacío.
Si tu credencial pierde uno de estos permisos de lectura después de un
POST, repetirlo con la misma Idempotency-Key se rechaza con un 403 cuyo error.code es invoice_replay_permission_revoked cuando la respuesta almacenada muestra esos campos. En su lugar, obtén la factura con GET. Añade permisos desde la guía de permisos.
Errores
Los rechazos vuelven como{ error: { type, message, code } }. Todos los códigos siguientes son 400 salvo que se indique lo contrario. Un plan_id, member_id, mailing_address_id o payment_method_id desconocido es un 404, y una marca de tiempo que Whop no puede leer es un 400 con invalid_timestamp.
Estos rechazos son un 400 sin error.code, así que lee error.message para conocer el motivo:
- Un campo de nivel superior desconocido.
- Una
quantityfuera del rango de 1 a 999,999. - Una dirección no válida en
recipient_emails, o más de 50. - Una regla de varios artículos incumplida, como una discrepancia en el periodo de facturación.
Errores de creación y actualización
Errores de emisión
Errores de envío y programación
Enviar un borrador lo emite, así que un envío también puede rechazarse por cualquiera de los motivos de Errores de emisión.Otros errores
Anular una factura pagada es un
400 sin código.
Próximos pasos
Referencia de la API de facturas
Todos los endpoints, parámetros y campos de respuesta de las facturas.
Guarda métodos de pago
Recopila el método de pago guardado que una factura cobra al emitirse.
Gestiona el fraude
Escribe las reglas de pago que filtran los pagos de facturas.
Escucha webhooks
Supervisa
payment.created y payment.succeeded para tus facturas.
