Skip to content
Guia da Central de Ajuda · Faturação e pagamentos
3 min de leituraVerificado 2026-11-16

Métodos de pagamento

Atualize cartões bancários ou débitos SEPA em segurança através do Portal de Clientes Stripe.

Neste guia

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

FLUXO DE ARQUITETURA
ARQUITETURA INTERATIVA
ORQUESTRAÇÃO DE MÉTODOS DE PAGAMENTO MULTIPROVIDEDOR
ETAPA 01 ADMINISTRADOR DE FATURAÇÃO DO ESPAÇO (CLIENTE)
Seleciona Via: Cartão Stripe (3DS2) | Acordo PayPal | Mobile Money
ETAPA 02 ENDPOINTS DE ORQUESTRAÇÃO DE PAGAMENTOS (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 aprova mand.`POST/payment-methods
/paypal/confirm`
Mobile Money Reg.
POST/payment- methods/mobile- money
Verificação OTP /
Mandato Telemóvel
ETAPA 03 REGISTO DE MÉTODOS EM COFRE (GET/payment-methods)
Guarda Apenas Metadados Não Sensíveis (Rede, Last4, Validade, E-mail, Padrão)
Usado Automaticamente em Renovações e POST/invoices/:id/pay

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 SetupIntent do Stripe com Autenticação Forte do Cliente (3D-Secure 2 / PSD2 SCA) executada no browser antes de confirmar o paymentMethodId na API.

Vias de Pagamento e Endpoints Suportados

Via de PagamentoEndpointsInstrumentos e Moedas Suportados
Listar Métodos GuardadosGET /api/v1/billing/payment-methodsDevolve 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 SEPAPOST /api/v1/billing/payment-methods/stripe/setup-intentPOST /api/v1/billing/payment-methods/stripe/confirmCartõ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 PayPalPOST /api/v1/billing/payment-methods/paypal/setup-tokenPOST /api/v1/billing/payment-methods/paypal/confirmContas empresariais PayPal autorizadas para faturação recorrente de subscrições.
Mobile MoneyPOST /api/v1/billing/payment-methods/mobile-moneyCarteiras 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)

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

Payload de Resposta (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. 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)

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..."
}

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:

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. 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/confirm com { setupTokenId } (request payload).
  • Mobile Money (POST /api/v1/billing/payment-methods/mobile-money): Regista uma conta de carteira móvel com 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"
}

Documentação Relacionada

Pronto para lançar o seu primeiro programa de cartões Wallet?

Crie o seu espaço de trabalho, configure o seu modelo e teste um cartão real na Apple Wallet e Google Wallet antes de escalar.