Contrato e caução
Contrato com assinatura eletrônica e caução no cartão, do aluguel ao check-out.
Em liberação
As rotas de contratos e de caução estão no contrato da API e são liberadas por produto, começando pelo sandbox. Peça os produtos contracts.signatures e payments.deposits ao seu contato na Kodano.
O caso típico é a locação por temporada: o hóspede assina o contrato e deixa uma caução no cartão, que a loja libera no check-out ou cobra se houver dano. Todas as rotas exigem X-Merchant-Id com credencial de organização, e os POST que criam ou encerram recursos exigem Idempotency-Key.
Escolha o modelo do contrato
GET /v1/contract-templates lista os modelos .docx da loja, com as tags que precisam ser preenchidas. Você também pode enviar um modelo (POST /v1/contract-templates, multipart/form-data) ou usar um PDF próprio (POST /v1/contract-files). O mesmo arquivo enviado de novo devolve o recurso existente.
Emita o contrato
POST /v1/contracts com contractTemplateId e tagValues (ou contractFileId) e os signatários. Exatamente um signatário é o payer.
{
"contractTemplateId": "ctt_0192f3a0b1c24d3e8f9a0b1c2d3e4f50",
"name": "Locação Villa Trancoso 21–28/11",
"signers": [
{ "name": "Ana Souza", "email": "ana@exemplo.com", "phone": { "areaCode": "71", "number": "999990000" }, "role": "payer" }
],
"tagValues": [
{ "tag": "imovel", "value": "Villa Trancoso" },
{ "tag": "inicio", "value": "21/11/2026" }
]
}Cada signatário recebe o pedido por e-mail e volta na resposta com signUrl, o link da Kodano para assinar, que você pode mandar no seu próprio fluxo. Signatários podem ser adicionados, alterados, removidos e notificados de novo enquanto não assinarem.
Abra a caução
POST /v1/deposits com o contractId do contrato, o valor em centavos e a cobertura. O contrato não precisa estar assinado, mas não pode estar recusado, expirado ou cancelado.
{
"contractId": "ctr_0192f3c1a7b84e2d9f0a1b2c3d4e5f60",
"payer": { "name": "Ana Souza", "document": "12345678909", "email": "ana@exemplo.com" },
"amount": 500000,
"currency": "BRL",
"coverageStartsAt": "2026-11-02T00:00:00Z",
"coverageEndsAt": "2026-12-05T00:00:00Z",
"autoRenew": true
}A caução nasce AWAITING_AUTHORIZATION com checkoutUrl. Mande o hóspede a esse endereço para autorizar o cartão; aprovada a autorização, ela fica ACTIVE.
Acompanhe
GET /v1/contracts/{id} mostra o andamento das assinaturas; com signed, o PDF sai em GET /v1/contracts/{id}/signed-file (URL temporária). GET /v1/deposits/{id} mostra a autorização vigente. Com autoRenew, a Kodano renova a autorização antes de vencer, até coverageEndsAt; renovação negada leva a RENEWAL_AT_RISK e, sem sucesso, a UNSECURED.
Encerre no check-out
Sem dano, POST /v1/deposits/{id}/release desfaz a autorização. Com dano, envie as fotos (POST /v1/deposits/{id}/evidence-uploads devolve URLs para PUT) e capture com POST /v1/deposits/{id}/capture, informando damageDescription, as evidências e, para cobrar só parte, amount.
- Modo e tarifa da caução seguem a configuração da loja na Kodano e aparecem em
modeefeeAmount. - Pagamentos de caução não aparecem em
/v1/paymentsnem geram eventospayment.*. - Os eventos de webhook de contrato e de caução ainda não são enviados; até lá, consulte os recursos.