Skip to content
Guía del Centro de ayuda · Facturación y pagos
3 min de lecturaVerificado 2026-11-16

Métodos de pago

Actualiza tarjetas bancarias o mandatos SEPA con seguridad en el Portal de clientes de Stripe.

En esta guía

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

FLUJO DE ARQUITECTURA
ARQUITECTURA INTERACTIVA
ORQUESTACIÓN DE MÉTODOS DE PAGO MULTIPROVEEDOR
ETAPA 01 ADMINISTRADOR DE FACTURACIÓN DEL ESPACIO (CLIENTE)
Elige vía de pago: Tarjeta Stripe (3DS2) | Acuerdo PayPal | Mobile Money
ETAPA 02 ENDPOINTS DE ORQUESTACIÓN DE PAGOS (Billing API)
Stripe 3D-Secure
`POST/payment-methods
/stripe/setup-intent`
Cliente completa 3DS2`POST/payment-methods
/stripe/confirm`
PayPal Saved Billing
`POST/payment-methods
/paypal/setup-token`
Comprador aprueba mand.`POST/payment-methods
/paypal/confirm`
Mobile Money Reg.
POST/payment- methods/mobile- money
Verificación móvil/
OTP del mandato
ETAPA 03 REGISTRO DE MÉTODOS GUARDADOS (GET/payment-methods)
Solo almacena metadatos no sensibles (Marca, Last4, Caducidad, Correo, Defecto)
Usado automáticamente en renovaciones y POST/invoices/:id/pay

Importante: Passinstance nunca toca numeraciones brutas de tarjeta ni códigos CVV. Todos los flujos de captura usan secretos de cliente SetupIntent de Stripe con Autenticación Reforzada de Clientes (3D-Secure 2 / PSD2 SCA) ejecutada en el navegador antes de confirmar paymentMethodId en la API.

Vías de pago y endpoints admitidos

Vía de pagoEndpointsInstrumentos y divisas admitidos
Listar métodos guardadosGET /api/v1/billing/payment-methodsDevuelve 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 SEPAPOST /api/v1/billing/payment-methods/stripe/setup-intentPOST /api/v1/billing/payment-methods/stripe/confirmMandatos Visa, Mastercard, American Express y Adeudo Directo SEPA con autenticación completa 3D-Secure 2 (SCA) en EUR y USD.
Acuerdos de facturación PayPalPOST /api/v1/billing/payment-methods/paypal/setup-tokenPOST /api/v1/billing/payment-methods/paypal/confirmCuentas PayPal corporativas o de empresa autorizadas para cobros recurrentes.
Mobile MoneyPOST /api/v1/billing/payment-methods/mobile-moneyVí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)

HTTP
GET /api/v1/billing/payment-methods HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>

Payload de respuesta (200 OK)

JSON
{
  "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)

HTTP
POST /api/v1/billing/payment-methods/stripe/setup-intent HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
JSON
{
  "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:

HTTP
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"
}
JSON
{
  "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/confirm con { setupTokenId } (request payload).
  • Mobile Money (POST /api/v1/billing/payment-methods/mobile-money): Registra una línea de dinero móvil con request payload ({ provider, phoneNumber, currency?, note? }):
HTTP
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

¿Listo para lanzar su primer programa de tarjetas Wallet?

Cree su espacio de trabajo, configure su plantilla y pruebe una tarjeta real en Apple Wallet y Google Wallet antes de escalar.