PayZu OnboardingPropostas
Criar uma proposta
Abra pela sua aplicação o pedido de abertura de conta de um CPF ou CNPJ e receba o link da jornada para entregar ao cliente.
Crie a proposta
bash
curl --request POST \
--url 'https://api.sandbox.payzu.dev/v1/proposals' \
--header 'Authorization: Bearer SEU_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
"clientCode": "crm-8812",
"type": "PERSON",
"taxId": "123.456.789-09",
"contact": "+55 73 99169-9000",
"expiresInHours": 72
}'json
{
"id": "cmf0p8x1a0001qk08prop0001",
"clientCode": "crm-8812",
"type": "PERSON",
"taxId": "12345678909",
"contact": "5573991699000",
"status": "CREATED",
"delivery": "LINK",
"expiresAt": "2026-09-20T12:00:00.000Z",
"submittedAt": null,
"decidedAt": null,
"version": 0,
"createdAt": "2026-09-17T12:00:00.000Z",
"updatedAt": "2026-09-17T12:00:00.000Z",
"journeyUrl": "https://jornada.sandbox.payzu.dev/Qm9hIHZpYWdlbSBkZSB0ZXN0ZSBkbyBsaW5r",
"embedUrl": null
}Referência: Criar uma proposta de abertura de conta
Guarde o link que a criação retorna.
Ele vem em journeyUrl uma vez só, e você o entrega ao cliente pelo seu canal, como mostra Links da jornada.
Campos
| Campo | Regra |
|---|---|
clientCode | Obrigatório. Um identificador seu, com até 120 caracteres e único no tenant. |
type | Obrigatório. PERSON ou COMPANY. |
taxId | Obrigatório. CPF em PERSON e CNPJ em COMPANY; documento que não combina com o tipo responde validation_failed. |
contact | Celular ou e-mail do cliente, que ele confirma na jornada. |
expiresInHours | Prazo para o cliente concluir. |
prefill | Dados do cliente que você já tem. A jornada abre com eles preenchidos, como em Cenários práticos. |
embed | Mostra a jornada na sua página ou no seu app, e o link vem em embedUrl. Veja Jornada embutida. |
callbackUrl | Só é aceita depois que a PayZu cadastrou o segredo dos callbacks do seu tenant. |
Repita depois de uma falha de rede
Mande de novo o mesmo clientCode com o mesmo corpo. A resposta é 200 com a proposta existente, e journeyUrl e embedUrl vêm nulos.
- Corpo diferente: a criação é recusada com
client_code_conflict.expiresInHoursnão entra nessa comparação. - Link novo: use Gerar um link da jornada.
- Nova tentativa do mesmo cliente: gere outro
clientCode.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
callback_url_invalid | 400 | A URL de callback precisa ser https, pública e sem credenciais. |
embed_origin_not_allowed | 400 | A origem não está entre as páginas autorizadas a embutir a jornada deste tenant. |
embed_return_url_not_allowed | 400 | A URL de retorno não está entre as cadastradas para o app deste tenant. |
client_code_conflict | 409 | O clientCode já foi usado com outro conteúdo. |
journey_incomplete | 409 | conclua COMPANY_DATA antes de MEMBERS |
journey_step_not_open | 409 | Esta etapa não está aberta para envio. |
write_conflict | 409 | Outra requisição gravou o mesmo recurso ao mesmo tempo. Releia e tente de novo. |
contact_channel_unsupported | 422 | O tenant confirma o contato por celular ou por e-mail; informe um contato desse tipo. |
embed_unavailable | 503 | O serviço não consegue assinar links embutidos neste ambiente. |
Autenticação e validação estão no Catálogo de erros.