> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autorizou.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Conceitos Básicos

> Entenda os conceitos fundamentais da plataforma Autorizou

## 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 pagamentos entre compradores e vendedores.

A Autorizou atua como intermediária, facilitando:

* **Processamento** de pagamentos
* **Roteamento** para adquirentes
* **Conciliação** de pagamentos
* **Gestão** de chargebacks e estornos

## Fluxo de um Pagamento

```mermaid theme={null}
graph LR
    A[Cliente] --> B[Sua Aplicação]
    B --> C[API Autorizou]
    C --> D[Adquirente]
    D --> E[Bandeira]
    E --> F[Banco Emissor]
    F --> E
    E --> D
    D --> C
    C --> B
    B --> A
```

<Steps>
  <Step title="Iniciação">
    Cliente informa dados de pagamento em sua aplicação
  </Step>

  <Step title="Processamento">
    Sua aplicação envia dados para API Autorizou
  </Step>

  <Step title="Roteamento">
    Autorizou roteia para o melhor adquirente
  </Step>

  <Step title="Autorização">
    Adquirente consulta banco emissor via bandeira
  </Step>

  <Step title="Resposta">
    Resposta retorna pelo mesmo caminho
  </Step>

  <Step title="Notificação">
    Webhook notifica mudanças de status
  </Step>
</Steps>

## Entidades Principais

### Cliente (Customer)

Representa o comprador final que realizará o pagamento.

```json theme={null}
{
  "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.

```json theme={null}
{
  "customer_id": "46e9d3d9-afb2-4d19-9a29-43b739f859a5",
  "encrypted": "aVIvMXIzTTlZck5iaXZrNGxCL25RWHR2K2MvQjVRc3BRRGdZqc3ViWnN4REpzMEtPQlNKQTgzcjJIWWxnNHRK..."
}
```

**Características:**

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

<Note>
  Confira a documentação do [SDK](/api-reference/cards/card-tokenization) para aprender a gerar o token.
</Note>

### Pagamento (Payment)

Representa um pagamento processado.

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

### Recebedor (Recipient)

Representa um recebedor em pagamentos com split.

```json theme={null}
{
  "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:**

1. Cliente informa dados do cartão
2. Dados são criptografados e tokenizados
3. Autorização é solicitada ao banco
4. 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:**

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

<Note>
  Veja o [guia completo de integração Apple Pay](/api-reference/payments/apple-pay-integration) para implementar.
</Note>

### 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:**

1. Cliente solicita pagamento PIX
2. QR Code é gerado com dados do pagamento
3. Cliente escaneia e confirma no app bancário
4. 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:**

1. Cliente escolhe pagamento por boleto
2. Boleto é gerado com dados do pagamento
3. Cliente paga em qualquer banco/lotérica
4. 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:

```json theme={null}
{
  "payment": {
    "amount": 10000,
    "split": [
      {
        "recipient_id": "8f3a91c2-4b5d-4c6e-9a70-2f1e3d4c5b6a",
        "amount": 1000,
        "type": "flat"
      },
      {
        "recipient_id": "c9d8e7f6-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
        "amount": 9000,
        "type": "flat"
      }
    ]
  }
}
```

### 3D Secure

Autenticação adicional para cartões:

```json theme={null}
{
  "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:

```json theme={null}
{
  "offer_id": "b9af7796-ac98-47f2-b921-46b0415d7473",
  "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.inactivated` - Assinatura inativada (cancelamento)

<Note>
  O webhook será enviando para a url informada no payload de pagamento (notification\_url) ou para a url cadastrada
  no webhook criado na dashboard.
</Note>

## 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:

```http theme={null}
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):

```json theme={null}
{
  "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 |