# Primeiros passos (/docs/cartao/getting-started)



<QuickLinks>
  <QuickLink href="/docs/cartao/endpoints" title="Referência API" />

  <QuickLink href="/docs/cartao/authentication" title="Autenticação" />

  <QuickLink href="/docs/cartao/test-cards" title="Cartões de teste" />

  <QuickLink href="/docs/cartao/transaction-status" title="Status da transação" />

  <QuickLink href="/docs/cartao/webhooks" title="Webhooks" />
</QuickLinks>

<Mermaid
  chart="`
flowchart LR
  A[&#x22;Certificado + credenciais&#x22;] --> B[&#x22;Obter token&#x22;]
  B --> C[&#x22;Criar cobrança&#x22;]
  C --> D[&#x22;Ler a resposta&#x22;]
  D --> E[&#x22;Testar cenários&#x22;]

  click B &#x22;/docs/cartao/endpoints/token/post_token&#x22; &#x22;POST /token&#x22;
  click C &#x22;/docs/cartao/endpoints/charges/post_charges&#x22; &#x22;POST /charges&#x22;
  click D &#x22;/docs/cartao/transaction-status&#x22; &#x22;Status da transação&#x22;
  click E &#x22;/docs/cartao/test-cards&#x22; &#x22;Cartões de teste&#x22;

  style A fill:#f59e0b,stroke:#d97706,color:#ffffff
  style E fill:#14ce71,stroke:#0eb464,color:#ffffff
`"
/>

Neste guia usamos o **sandbox** (`https://api.sandbox.payzu.io/v1`). Em produção a base URL é `https://api.payzu.io/v1`.

<Steps>
  <Step>
    ### Pré-requisitos [#pré-requisitos]

    Antes da primeira chamada você precisa de dois itens, ambos fornecidos pela equipe PayZu:

    * **Certificado mTLS de cliente** (`cliente.crt`, `cliente.key` e `ca.pem`). Instale o certificado e configure seu sistema para utilizá-lo em **todas** as chamadas à API, sempre por HTTPS. Detalhes em [Autenticação](/docs/cartao/authentication).
    * **Credenciais** `client_id` e `client_secret`, usadas para obter o token de acesso.
  </Step>

  <Step>
    ### Obter o token [#obter-o-token]

    Chame [`POST /token`](/docs/cartao/endpoints/token/post_token) usando **Basic Auth** com `client_id` e `client_secret`, junto do certificado mTLS, e use o `access_token` retornado como Bearer token nas próximas chamadas. Para o exemplo completo de requisição e resposta, veja [Autenticação](/docs/cartao/authentication).
  </Step>

  <Step>
    ### Criar a primeira cobrança [#criar-a-primeira-cobrança]

    Crie uma cobrança via [`POST /charges`](/docs/cartao/endpoints/charges/post_charges). Os campos obrigatórios são `amount`, `customer`, `paymentType`, `cart`, `creditCardPayment` e `externalId`. Schema completo na referência.

    ```bash
    curl --request POST \
      --url https://api.sandbox.payzu.io/v1/charges \
      --header "Authorization: Bearer SEU_ACCESS_TOKEN" \
      --header 'Content-Type: application/json' \
      --cert cliente.crt \
      --key cliente.key \
      --cacert ca.pem \
      --data '{
        "amount": 10000,
        "externalId": "pedido-2026-0001",
        "paymentType": "creditcard",
        "customer": {
          "name": "João da Silva"
        },
        "cart": [
          {
            "name": "Plano mensal",
            "quantity": 1,
            "sku": "PLANO-01",
            "unitPrice": 10000
          }
        ],
        "creditCardPayment": {
          "installments": 1,
          "authenticate": false,
          "card": {
            "number": "4111111111111111",
            "holder": "JOAO DA SILVA",
            "expiration": "12/2030",
            "cvv": "123"
          }
        }
      }'
    ```

    Em produção, troque a base URL para `https://api.payzu.io/v1`.

    <Callout type="info">
      Valores monetários (`amount`, `unitPrice`) são sempre em **centavos**. `10000` equivale a R$ 100,00.
    </Callout>

    Com `authenticate: false` o comprador não é direcionado ao emissor para autenticação. Para fluxos autenticados, veja [3D Secure](/docs/cartao/three-d-secure).
  </Step>

  <Step>
    ### Ler a resposta [#ler-a-resposta]

    A resposta traz o `id` da cobrança, o `externalId` informado e o objeto `creditCardPayment` com `status`, `reasonCode` e `reasonMessage`. Os principais status:

    | Código | Status           | Significado                                                           |
    | ------ | ---------------- | --------------------------------------------------------------------- |
    | 1      | Authorized       | Aprovado pelo emissor, apto a ser capturado, mas ainda não concluído. |
    | 2      | PaymentConfirmed | Pagamento confirmado e finalizado.                                    |
    | 3      | Denied           | Pagamento negado por autorizador.                                     |

    Se `creditCardPayment.status` retornou `2` (PaymentConfirmed), sua primeira cobrança está confirmada. A lista completa de códigos está em [Status da transação](/docs/cartao/transaction-status).
  </Step>

  <Step>
    ### Testar cenários e configurar webhooks [#testar-cenários-e-configurar-webhooks]

    Para simular aprovações, negativas e time out no sandbox, use os [cartões de teste](/docs/cartao/test-cards): os últimos dígitos do número do cartão determinam o resultado da transação.

    Para receber notificações sobre o status da cobrança sem precisar consultar a API, informe uma `postbackUrl` na criação da cobrança. Estrutura do payload e validação em [Webhooks](/docs/cartao/webhooks).
  </Step>
</Steps>

## Próximos passos [#próximos-passos]

<QuickLinks>
  <QuickLink href="/docs/cartao/three-d-secure" title="3D Secure" />

  <QuickLink href="/docs/cartao/antifraud" title="Antifraude" />

  <QuickLink href="/docs/cartao/recurrence" title="Recorrência" />

  <QuickLink href="/docs/cartao/international" title="Cobranças internacionais" />
</QuickLinks>