Primeiros passos
Nesta página
Autorize a conta de serviçoPeça o tokenCrie a primeira propostaPercorra a jornadaO que vem depoisChegue à primeira proposta no sandbox com um token válido e o link da jornada pronto para o cliente.
Autorize a conta de serviço
A API não usa segredo compartilhado. Envie à PayZu o e-mail e o uniqueId da conta de serviço Google do seu backend, e ela cadastra a autorização dessa conta no seu tenant, uma para o sandbox e outra para a produção.
De cada ambiente você recebe dois valores:
- Audiência do ID token: a conta de serviço pede o ID token ao Google com ela.
- Id do seu tenant: vai em
audiencena troca do token.
| Ambiente | Servidor |
|---|---|
| Sandbox | https://api.sandbox.payzu.dev |
| Produção | https://api.payzu.dev |
O servidor não leva prefixo: as rotas da API começam em /v1, e o token fica na raiz, em /oauth/token.
As rotas e os corpos são os mesmos nos dois ambientes.
Para ir à produção, troque o servidor e use a autorização, a audience e o destino dos callbacks cadastrados para ela.
Peça o token
Gere o ID token no seu backend com a biblioteca de autenticação do Google e mande-o em subject_token, sem o cabeçalho Authorization, que a rota não aceita.
curl --request POST \
--url 'https://api.sandbox.payzu.dev/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
"grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
"subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
"subject_token": "eyJhbGciOiJSUzI1NiIs...",
"audience": "payzu"
}'{
"access_token": "eyJhbGciOiJFZERTQSIs...",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"token_type": "Bearer",
"expires_in": 900
}Referência: Gerar um token de acesso
O token vale expires_in segundos, 15 minutos no exemplo. Nas outras rotas, mande Authorization: Bearer SEU_TOKEN e reaproveite o mesmo token até perto de vencer, como explica Autenticação.
Crie a primeira proposta
Identifique a proposta com um código seu em clientCode e informe o tipo de titular e o documento. O cliente confirma o contact na jornada e tem expiresInHours horas para concluir.
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
}'{
"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
A proposta nasce CREATED, com version 0. Entregue o journeyUrl ao cliente pelo seu canal.
Guarde o link que a criação retorna.
Guarde também o id. Nenhuma consulta retorna o link, e repetir a criação responde com journeyUrl nulo. Se ele se perder, emita outro em Gerar um link da jornada.
Para testar sem escrever código, abra a rota na referência, cole o token e use o Try It!.
Percorra a jornada
Abra o journeyUrl no navegador, confirme o contato com o código 000000, preencha as telas e envie. Depois, veja o status em Consultar uma proposta.
No sandbox, a consulta cadastral responde com dados de teste.
| Documento | Resultado da análise |
|---|---|
000.000.001-91 | Reprova. |
390.533.447-05 | Fica em IN_ANALYSIS até a decisão. |
| Os demais | Aprovam quando o nome e o nascimento batem com os dados de teste. |