Visão geral
O Passinstance suporta orquestração multiprovidedor de métodos de pagamento (Billing API em /api/v1/billing/payment-methods* e Definições -> Faturação -> Método de Pagamento em /settings/billing/payment-method), permitindo aos espaços de trabalho liquidar subscrições e extras através de payment method (CREDIT_CARD | PAYPAL | BANK_TRANSFER | GOOGLE_PAY | APPLE_PAY | STRIPE | CRYPTO | GIFT_CARD | MOBILE_MONEY) e acompanhar cobranças com payment status (PENDING | COMPLETED | FAILED | CANCELLED | REFUNDED | PARTIALLY_REFUNDED | DISPUTED).
Para manter conformidade rigorosa com PCI-DSS, o Passinstance nunca transmite nem armazena números completos de cartão (PAN) ou códigos de segurança CVV nos servidores da plataforma—todas as credenciais de pagamento sensíveis são tokenizadas diretamente junto do processador através de handshakes SetupIntent / Setup-Token em duas etapas.
Arquitetura de Tokenização Multiprovidedor
Importante: O Passinstance nunca acede a números brutos de cartão de crédito nem valores CVV. Todos os fluxos de registo utilizam segredos de cliente
SetupIntentdo Stripe com Autenticação Forte do Cliente (3D-Secure 2 / PSD2 SCA) executada no browser antes de confirmar opaymentMethodIdna API.
Vias de Pagamento e Endpoints Suportados
| Via de Pagamento | Endpoints | Instrumentos e Moedas Suportados |
|---|---|---|
| Listar Métodos Guardados | GET /api/v1/billing/payment-methods | Devolve todos os métodos de pagamento em cofre associados ao espaço, indicando isDefault, marca/últimos 4 dígitos, validade ou identificador PayPal/Mobile Money. |
| Cartões Stripe e SEPA | POST /api/v1/billing/payment-methods/stripe/setup-intentPOST /api/v1/billing/payment-methods/stripe/confirm | Cartões Visa, Mastercard, American Express e mandatos de Débito Direto SEPA com autenticação completa 3D-Secure 2 (SCA) em EUR e USD. |
| Acordos PayPal | POST /api/v1/billing/payment-methods/paypal/setup-tokenPOST /api/v1/billing/payment-methods/paypal/confirm | Contas empresariais PayPal autorizadas para faturação recorrente de subscrições. |
| Mobile Money | POST /api/v1/billing/payment-methods/mobile-money | Carteiras móveis regionais (ex.: M-Pesa, MTN Mobile Money, Orange Money, Airtel Money) para espaços nos mercados suportados. |
Guia da API: Registar e Confirmar Métodos de Pagamento
1. Listar Métodos de Pagamento Guardados (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 Resposta (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. Registo de Cartão Stripe 3D-Secure em Duas Etapas
Etapa A: Criar um SetupIntent 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..."
}
Etapa B: Confirmar o Cartão Tokenizado (POST /api/v1/billing/payment-methods/stripe/confirm)
Depois de o Stripe Elements concluir o desafio 3D-Secure 2 necessário no browser, envie request payload ({ setupIntentId, paymentMethodId }) para associar o cartão ao espaço:
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. Acordo PayPal e Registo Mobile Money
-
PayPal (
POST /api/v1/billing/payment-methods/paypal/setup-token->/confirm): Submete{ returnUrl, cancelUrl }(request payload) para gerar um token PayPal encrypted storage e de seguida chama/paypal/confirmcom{ setupTokenId }(request payload). -
Mobile Money (
POST /api/v1/billing/payment-methods/mobile-money): Regista uma conta de carteira móvel comrequest 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"
}
Documentação Relacionada
-
Tente novamente faturas em aberto e transfira recibos PDF em Faturas e Histórico de Faturação.
-
Faça upgrade de planos ou altere ciclos de faturação em Alterações de Plano e Cancelamento.
-
Atualize moradas fiscais e NIF/IVA em Definições da Empresa.
