Conceitos Básicos

O que é um PSP?

Um Payment Service Provider (PSP) ou Prestador de Serviços de Pagamento é uma empresa que oferece uma plataforma tecnológica para processar transações financeiras entre compradores e vendedores. A Autorizou atua como intermediária, facilitando:

✅ Processamento de pagamentos
✅ Roteamento para adquirentes
✅ Conciliação de transações
✅ Gestão de chargebacks e estornos

Fluxo de uma Transação

Iniciação

Cliente informa dados de pagamento em sua aplicação

Processamento

Sua aplicação envia dados para API Autorizou

Roteamento

Autorizou roteia para o melhor adquirente

Autorização

Adquirente consulta banco emissor via bandeira

Resposta

Resposta retorna pelo mesmo caminho

Notificação

Webhook notifica mudanças de status

Entidades Principais

👤 Cliente (Customer)

Representa o comprador final que realizará o pagamento.

{
  "name": "João Silva",
  "email": "joao@exemplo.com.br",
  "documents": [
    {
      "type": "CPF",
      "value": "12345678901"
    }
  ]
}

Características:

Obrigatório para processar pagamentos
Pode ter múltiplos cartões associados
Suporte a CPF e CNPJ
Endereços para cobrança e entrega

💳 Cartão (Card)

Representa um método de pagamento tokenizado do cliente.

{
  "customer_id": "cus_abc123",
  "encrypted": "aVIvMXIzTTlZck5iaXZrNGxCL25RWHR2K2MvQjVRc3BRRGdZqc3ViWnN4REpzMEtPQlNKQTgzcjJIWWxnNHRK..."
}

Características:

Tokenização segura dos dados
Detecção automática de duplicatas
Suporte a Network Tokens
Criptografia end-to-end

Confira a documentação do script de tokenização para aprender a gerar o token.

💰 Pagamento (Payment)

Representa uma transação financeira processada.

{
  "status": "authorized",
  "amount": 10000,
  "currency": "BRL",
  "payment_method": "credit_card",
  "created_at": "2024-01-15T10:30:00Z"
}

🏢 Recebedor (Recipient)

Representa um recebedor em transações de split.

{
  "legal_name": "Loja ABC Ltda",
  "email": "financeiro@lojaabc.com.br",
  "document": {
    "type": "CNPJ",
    "value": "12345678000190"
  }
}

Status de Pagamentos

Estados Principais

Status	Descrição	Ação Requerida
`authorized`	Autorizado pelo banco	Capture se necessário
`authentication_requested`	Aguardando autenticação 3DS	Aguardar
`chargeback`	Chargeback	Disputa
`disputed`	Notificação de chargeback	Disputa
`expired`	Pagamento expirado, normalmente boleto ou pix	Nenhuma
`refused`	Recusado pelo banco ou emissor	Tentar outro cartão dependendo do retorno
`processing`	Estado incial, sendo processado	Aguardar
`refunded`	Estornado	Nenhuma
`refunded_partially`	Estornado Parcialmente	Nenhuma
`sent_for_settle`	Enviando para liquidação	Aguardar
`settled`	Liquidado	Nenhuma
`waiting_payment`	Aguardando processamento	Nenhuma

Métodos de Pagamento

💳 Cartão de Crédito

Características:

Parcelamento: 1x a 12x
Captura: Automática ou manual
3D Secure: Autenticação adicional

Fluxo:

Cliente informa dados do cartão
Dados são criptografados e tokenizados
Autorização é solicitada ao banco
Resposta é retornada em tempo real

🍎 Apple Pay

Características:

Segurança: Biometria (Face ID/Touch ID)
Conversão: Até 70% maior que checkout tradicional
Tokenização: Dados do cartão nunca são expostos
Suporte: iPhone, iPad, Mac, Apple Watch

Fluxo:

Cliente clica no botão Apple Pay
Dispositivo valida identidade com biometria
Token criptografado é gerado
Pagamento é processado instantaneamente

Veja o guia completo de integração Apple Pay para implementar.

🏦 PIX

Características:

Instantâneo: Confirmação em até 10 segundos
24/7: Disponível todos os dias
QR Code: Geração automática
Expiração: Configurável

Fluxo:

Cliente solicita pagamento PIX
QR Code é gerado com dados da transação
Cliente escaneia e confirma no app bancário
Notificação instantânea via webhook

📄 Boleto Bancário

Características:

Vencimento: Configurável
Código de Barras: Padrão FEBRABAN
Conciliação: Automática
Impressão: PDF gerado automaticamente

Fluxo:

Cliente escolhe pagamento por boleto
Boleto é gerado com dados da transação
Cliente paga em qualquer banco/lotérica
Conciliação automática via arquivo de retorno

Conceitos Avançados

🤝 Split de Pagamento

Distribuição automática de valores entre múltiplos destinatários:

{
  "payment": {
    "amount": 10000,
    "split": [
      {
        "recipient_id": "rec_marketplace",
        "amount": 1000,
        "type": "flat"
      },
      {
        "recipient_id": "rec_seller", 
        "amount": 9000,
        "type": "flat"
      }
    ]
  }
}

🔒 3D Secure

Autenticação adicional para cartões:

{
  "authentication_data": {
    "attempt_authentication": "always",
    "browser_info": {
      "accept_header": "text/html,application/xhtml+xml",
      "color_depth": "",
      "user_agent": "Mozilla/5.0...",
      "java_enabled": false,
      "language": "pt-BR",
      "screen_height": "",
      "screen_width": "",
      "timezone_offset": "",
      "origin": "",
      "ip_address": ""
    }
  }
}

🔄 Assinaturas (Recorrência)

Cobrança automática em intervalos regulares:

{
  "plan_id": "plan_mensal",
  "interval": "monthly",
  "trial_days": 7,
  "start_at": "2024-02-01T00:00:00Z"
}

Webhooks e Notificações

O que são Webhooks?

Webhooks são notificações HTTP enviadas pela Autorizou para sua aplicação sempre que um evento importante ocorre (mudança de status de pagamento, etc.).

Eventos Principais

payment.authorized - Pagamento autorizado
payment.refused - Pagamento recusado
payment.refunded - Pagamento estornado
subscription.created - Assinatura criada
subscription.cancelled - Assinatura cancelada

O webhook será enviando para a url informada no payload de pagamento (notification_url) ou para a url cadastrada no webhook criado na dashboard.

Idempotência

O que é?

Idempotência garante que múltiplas execuções da mesma operação produzam o mesmo resultado, evitando duplicatas.

Como Usar

Envie o header Idempotency-Key com um identificador único:

POST /v1/charges/orders
Authorization: Bearer ...
Idempotency-Key: order_123_attempt_1
Content-Type: application/json

{
  "customer": {...},
  "payment": {...}
}

Comportamento

Primeira requisição: Processa normalmente
Requisições subsequentes: Retorna o mesmo resultado
Escopo: Por merchant

Valores e Moedas

Formato de Valores

Todos os valores monetários são expressos em centavos (menor unidade da moeda):

{
  "amount": 10000,    // R$ 100,00
  "currency": "BRL"   // Real Brasileiro
}

Exemplos

Valor Real	Valor API	Descrição
R$ 1,00	`100`	Um real
R$ 10,50	`1050`	Dez reais e cinquenta centavos
R$ 999,99	`99999`	Novecentos reais e noventa e nove centavos

​O que é um PSP?

​Fluxo de uma Transação

​Entidades Principais

​👤 Cliente (Customer)

​💳 Cartão (Card)

​💰 Pagamento (Payment)

​🏢 Recebedor (Recipient)

​Status de Pagamentos

​Estados Principais

​Métodos de Pagamento

​💳 Cartão de Crédito

​🍎 Apple Pay

​🏦 PIX

​📄 Boleto Bancário

​Conceitos Avançados

​🤝 Split de Pagamento

​🔒 3D Secure

​🔄 Assinaturas (Recorrência)

​Webhooks e Notificações

​O que são Webhooks?

​Eventos Principais

​Idempotência

​O que é?

​Como Usar

​Comportamento

​Valores e Moedas

​Formato de Valores

​Exemplos

O que é um PSP?

Fluxo de uma Transação

Entidades Principais

👤 Cliente (Customer)

💳 Cartão (Card)

💰 Pagamento (Payment)

🏢 Recebedor (Recipient)

Status de Pagamentos

Estados Principais

Métodos de Pagamento

💳 Cartão de Crédito

🍎 Apple Pay

🏦 PIX

📄 Boleto Bancário

Conceitos Avançados

🤝 Split de Pagamento

🔒 3D Secure

🔄 Assinaturas (Recorrência)

Webhooks e Notificações

O que são Webhooks?

Eventos Principais

Idempotência

O que é?

Como Usar

Comportamento

Valores e Moedas

Formato de Valores

Exemplos