PayZu PaymentsCobranças

Criar uma cobrança


Nesta páginaCrie a cobrançaReceba os avisosErros desta operação

Autorize e capture o valor no cartão de crédito numa única chamada, à vista ou em até 12 parcelas, com o resultado na própria resposta.

Crie a cobrança

CampoRegra
amountEm centavos, a partir de 100 e dentro dos limites da conta.
externalIdO seu identificador.
creditCardPayment.installmentsDe 1 a 12. Em recorrência e em moeda estrangeira, só 1.
customer.phoneOpcional. 55 + DDD + 9 dígitos, sem +, com até 13 caracteres.
bash
curl --request POST \
  --url 'https://api.sandbox.payzu.dev/v1/charges' \
  --header "Authorization: Bearer $PAYZU_TOKEN" \
  --cert "$PAYZU_CLIENT_CERT" --key "$PAYZU_CLIENT_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 10000,
    "paymentType": "creditcard",
    "externalId": "pedido-1234",
    "postbackUrl": "https://seusite.com.br/webhooks/payzu",
    "customer": {
      "name": "Maria Souza",
      "identity": "11144477735",
      "identityType": "CPF",
      "email": "maria.souza@example.com",
      "phone": "5511999998888"
    },
    "cart": [
      { "name": "Plano Pro", "quantity": 1, "sku": "PRO", "unitPrice": 10000 }
    ],
    "creditCardPayment": {
      "installments": 1,
      "authenticate": false,
      "card": {
        "number": "4111111111111111",
        "holder": "MARIA SOUZA",
        "expiration": "12/2030",
        "cvv": "123"
      }
    }
  }'

Referência: Criar uma cobrança

A criação responde 201 com a cobrança. Decida por creditCardPayment.status:

statusResultado
2Venda confirmada.
3Recusa.
OutrosVeja Status da transação.

Só esta resposta traz reasonMessage, returnCode e returnMessage.

Guarde os três junto do pedido.

A rota não deduplica por externalId.

Repetir a chamada cria outra cobrança. Num timeout, liste com GET /charges usando startDate um pouco antes do envio e endDate igual ao instante atual, e procure o seu externalId. Só crie de novo se ela não estiver lá.

Para enviar a autenticação do portador ou os dados de antifraude na mesma chamada, veja Cobrança com 3D Secure e Cobrança com antifraude.

Receba os avisos

A criação não gera aviso. Quando o status muda depois dela, a PayZu envia um POST assinado para a postbackUrl, com a cobrança completa em data.

EventoQuando chega
charge.updateEstorno, cancelamento, retorno de uma cobrança pendente ou chargeback.
chargebackChargeback, junto do charge.update.

O aviso é o canal recomendado; veja Webhooks. Para conferir ou recuperar o estado se o seu endpoint ficou fora do ar, use Consultar uma cobrança.

Erros desta operação

CódigoHTTPMensagem
PZ010403Produto não habilitado
PZ101422Valor mínimo por cobrança não atingido
PZ102422Valor máximo por cobrança excedido
PZ103422Conta sem limites de cobrança configurados
PZ104422Conta sem provedor de pagamento configurado
PZ105422Provedor de pagamento desabilitado
PZ106422Cobrança avulsa não disponível para esta conta
PZ107422Não foi possível criar a cobrança
PZ108422Configuração de pagamento da conta incompleta
PZ200422Cartão indisponível para cobrança internacional
PZ201422Apenas cartões estrangeiros são aceitos quando currency é diferente de BRL
PZ202422O emissor recusou este cartão em definitivo. Não é possível retentar.
PZ203422O emissor pediu para não retentar com este cartão até 09/11/2026 às 15:40.
PZ700422Conta sem configuração de taxas definidas para este meio de pagamento
PZ900422O provedor de pagamento recusou a operação
-422Cannot get currency rate
PZ109502Não foi possível confirmar a criação da cobrança com o provedor de pagamento. Verifique com o suporte antes de repetir o pedido.
PZ901503Não foi possível estabelecer comunicação com o provedor de pagamento. Tente novamente em instantes.

Os erros de autenticação e de validação e os demais códigos estão no Catálogo de erros.