Criar uma cobrança
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
| Campo | Regra |
|---|---|
amount | Em centavos, a partir de 100 e dentro dos limites da conta. |
externalId | O seu identificador. |
creditCardPayment.installments | De 1 a 12. Em recorrência e em moeda estrangeira, só 1. |
customer.phone | Opcional. 55 + DDD + 9 dígitos, sem +, com até 13 caracteres. |
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"
}
}
}'{
"id": "e3b7a1f2-8c4d-4a09-9f1e-2b6c8d5a7e90",
"externalId": "pedido-1234",
"postbackUrl": "https://seusite.com.br/webhooks/payzu",
"amount": 10000,
"paymentType": "creditcard",
"createdAt": "2026-06-12T14:35:22.000Z",
"updatedAt": "2026-06-12T14:35:24.000Z",
"customer": {
"name": "Maria Souza",
"identity": "11144477735",
"identityType": "CPF",
"email": "maria.souza@example.com",
"birthdate": "1990-04-15",
"phone": "5511999998888",
"address": {
"street": "Avenida Paulista",
"number": "1000",
"zipCode": "01310100",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"district": "Bela Vista",
"complement": "Conjunto 101"
}
},
"cart": [
{ "name": "Plano Pro", "quantity": 1, "sku": "PRO", "unitPrice": 10000 }
],
"creditCardPayment": {
"installments": 1,
"authenticate": false,
"currency": "BRL",
"acquirerTransactionId": "1049329871283a5d2b8e",
"authorizationCode": "128734",
"reasonCode": 0,
"reasonMessage": "Successful",
"status": 2,
"returnCode": "6",
"returnMessage": "Operação realizada com sucesso",
"externalAuthentication": {},
"reversedAmount": null,
"reversedDate": null,
"card": {
"number": "411111******1111",
"holder": "MARIA SOUZA",
"expiration": "12/2030",
"brand": "Visa"
},
"chargebacks": []
},
"pixPayment": null
}// npm i undici
import { readFileSync } from 'node:fs'
import { Agent, fetch } from 'undici'
const agent = new Agent({
connect: {
cert: readFileSync(process.env.PAYZU_CLIENT_CERT),
key: readFileSync(process.env.PAYZU_CLIENT_KEY)
}
})
const response = await fetch('https://api.sandbox.payzu.dev/v1/charges', {
method: 'POST',
dispatcher: agent,
headers: {
authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
'content-type': 'application/json'
},
body: JSON.stringify({
amount: 10000,
paymentType: 'creditcard',
externalId: 'pedido-1234',
postbackUrl: 'https://seusite.com.br/webhooks/payzu',
customer: { name: 'Maria Souza', identity: '11144477735', identityType: 'CPF', 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' }
}
})
})
const charge = await response.json()
if (!response.ok) throw new Error(`${charge.statusCode}: ${charge.message}`)
const status = charge.creditCardPayment.status
console.log(charge.id, status === 2 ? 'confirmada' : `não aprovada (${status})`)Referência: Criar uma cobrança
A criação responde 201 com a cobrança. Decida por creditCardPayment.status:
status | Resultado |
|---|---|
2 | Venda confirmada. |
3 | Recusa. |
| Outros | Veja 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.
| Evento | Quando chega |
|---|---|
charge.update | Estorno, cancelamento, retorno de uma cobrança pendente ou chargeback. |
chargeback | Chargeback, 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ódigo | HTTP | Mensagem |
|---|---|---|
PZ010 | 403 | Produto não habilitado |
PZ101 | 422 | Valor mínimo por cobrança não atingido |
PZ102 | 422 | Valor máximo por cobrança excedido |
PZ103 | 422 | Conta sem limites de cobrança configurados |
PZ104 | 422 | Conta sem provedor de pagamento configurado |
PZ105 | 422 | Provedor de pagamento desabilitado |
PZ106 | 422 | Cobrança avulsa não disponível para esta conta |
PZ107 | 422 | Não foi possível criar a cobrança |
PZ108 | 422 | Configuração de pagamento da conta incompleta |
PZ200 | 422 | Cartão indisponível para cobrança internacional |
PZ201 | 422 | Apenas cartões estrangeiros são aceitos quando currency é diferente de BRL |
PZ202 | 422 | O emissor recusou este cartão em definitivo. Não é possível retentar. |
PZ203 | 422 | O emissor pediu para não retentar com este cartão até 09/11/2026 às 15:40. |
PZ700 | 422 | Conta sem configuração de taxas definidas para este meio de pagamento |
PZ900 | 422 | O provedor de pagamento recusou a operação |
| - | 422 | Cannot get currency rate |
PZ109 | 502 | Nã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. |
PZ901 | 503 | Nã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.