Primeiros passos

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.
• Credenciais client_id e client_secret, usadas para obter o token de acesso.

Obter o token

Chame 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.

Criar a primeira cobrança

Crie uma cobrança via POST /charges. Os campos obrigatórios são amount, customer, paymentType, cart, creditCardPayment e externalId. Schema completo na referência.

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.

Com authenticate: false o comprador não é direcionado ao emissor para autenticação. Para fluxos autenticados, veja 3D Secure.

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:

Se creditCardPayment.status retornou 2 (PaymentConfirmed), sua primeira cobrança está confirmada. A lista completa de códigos está em Status da transação.

Testar cenários e configurar webhooks

Para simular aprovações, negativas e time out no sandbox, use os cartões de teste: 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.