Descripción general
Passinstance admite orquestación de métodos de pago multiproveedor (Billing API en /api/v1/billing/payment-methods* y Configuración -> Facturación -> Método de pago en /settings/billing/payment-method), lo que permite a los espacios liquidar suscripciones y complementos mediante payment method (CREDIT_CARD | PAYPAL | BANK_TRANSFER | GOOGLE_PAY | APPLE_PAY | STRIPE | CRYPTO | GIFT_CARD | MOBILE_MONEY) y seguir el estado de liquidación con payment status (PENDING | COMPLETED | FAILED | CANCELLED | REFUNDED | PARTIALLY_REFUNDED | DISPUTED).
Para mantener un cumplimiento estricto de PCI-DSS, Passinstance nunca transmite ni almacena numeraciones completas de tarjeta (PAN) ni códigos CVV en los servidores de la plataforma; todas las credenciales sensibles se tokenizan directamente en el procesador de pagos mediante intercambios de dos pasos con SetupIntent o Setup-Token.
Arquitectura de tokenización multiproveedor
Importante: Passinstance nunca toca numeraciones brutas de tarjeta ni códigos CVV. Todos los flujos de captura usan secretos de cliente
SetupIntentde Stripe con Autenticación Reforzada de Clientes (3D-Secure 2 / PSD2 SCA) ejecutada en el navegador antes de confirmarpaymentMethodIden la API.
Vías de pago y endpoints admitidos
| Vía de pago | Endpoints | Instrumentos y divisas admitidos |
|---|---|---|
| Listar métodos guardados | GET /api/v1/billing/payment-methods | Devuelve todos los métodos de pago en bóveda vinculados al espacio, indicando isDefault, marca/last4, caducidad o identificador PayPal/Mobile Money. |
| Tarjetas Stripe y SEPA | POST /api/v1/billing/payment-methods/stripe/setup-intentPOST /api/v1/billing/payment-methods/stripe/confirm | Mandatos Visa, Mastercard, American Express y Adeudo Directo SEPA con autenticación completa 3D-Secure 2 (SCA) en EUR y USD. |
| Acuerdos de facturación PayPal | POST /api/v1/billing/payment-methods/paypal/setup-tokenPOST /api/v1/billing/payment-methods/paypal/confirm | Cuentas PayPal corporativas o de empresa autorizadas para cobros recurrentes. |
| Mobile Money | POST /api/v1/billing/payment-methods/mobile-money | Vías de monedero móvil regionales (p. ej., M-Pesa, MTN Mobile Money, Orange Money, Airtel Money) para espacios en mercados compatibles. |
Recorrido por la API: registrar y confirmar métodos de pago
1. Listar métodos de pago en bóveda (GET /api/v1/billing/payment-methods)
GET /api/v1/billing/payment-methods HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Payload de respuesta (200 OK)
{
"paymentMethods": [
{
"id": "pm_019331f0-9988-7a11-8b22-334455667788",
"provider": "STRIPE",
"type": "CARD",
"brand": "visa",
"last4": "4242",
"expMonth": 8,
"expYear": 2029,
"isDefault": true,
"createdAt": "2026-01-15T10:12:00.000Z"
},
{
"id": "pm_01933205-4411-7c22-9d33-556677889900",
"provider": "PAYPAL",
"type": "PAYPAL_AGREEMENT",
"email": "billing@phenix-hospitality.example.com",
"isDefault": false,
"createdAt": "2026-06-20T14:05:11.000Z"
}
]
}
2. Registro de tarjeta Stripe 3D-Secure en dos pasos
Paso A: Crear un SetupIntent de Stripe (POST /api/v1/billing/payment-methods/stripe/setup-intent)
POST /api/v1/billing/payment-methods/stripe/setup-intent HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
{
"setupIntentId": "seti_1Q9xYz2eZvKYlo2C99887766",
"clientSecret": "seti_1Q9xYz2eZvKYlo2C99887766_secret_R1a2B3c4D5e6F7g8",
"publishableKey": "pk_live_51H..."
}
Paso B: Confirmar la tarjeta tokenizada (POST /api/v1/billing/payment-methods/stripe/confirm)
Cuando Stripe Elements complete cualquier verificación 3D-Secure 2 en el navegador, envíe request payload ({ setupIntentId, paymentMethodId }) para guardar la tarjeta en su espacio:
POST /api/v1/billing/payment-methods/stripe/confirm HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"setupIntentId": "seti_1Q9xYz2eZvKYlo2C99887766",
"paymentMethodId": "pm_1Q9xZa2eZvKYlo2C11223344"
}
{
"id": "pm_01933240-7766-7b00-8c11-990011223344",
"provider": "STRIPE",
"type": "CARD",
"brand": "mastercard",
"last4": "8819",
"expMonth": 11,
"expYear": 2030,
"isDefault": true
}
3. Acuerdo PayPal y alta de Mobile Money
-
PayPal (
POST /api/v1/billing/payment-methods/paypal/setup-token->/confirm): Envía{ returnUrl, cancelUrl }(request payload) para obtener un token de bóveda PayPal y llama después a/paypal/confirmcon{ setupTokenId }(request payload). -
Mobile Money (
POST /api/v1/billing/payment-methods/mobile-money): Registra una línea de dinero móvil conrequest payload({ provider, phoneNumber, currency?, note? }):
POST /api/v1/billing/payment-methods/mobile-money HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"provider": "MPESA",
"phoneNumber": "+254712345678",
"currency": "KES",
"note": "Primary Kenya operations billing number"
}
Documentación relacionada
-
Reintente facturas abiertas y descargue recibos PDF en Facturas e historial de facturación.
-
Mejore planes o cambie intervalos de suscripción en Cambios de plan y cancelación.
-
Actualice direcciones fiscales y NIF/IVA en Configuración de empresa.
