Voltar ao site
Caução

Abrir caução

POST/v1/deposits

Abre uma caução no cartão do pagador, amarrada a um contrato do merchant, com Location: /v1/deposits/{id}.

  • A caução nasce AWAITING_AUTHORIZATION com checkoutUrl: mande o pagador a esse endereço para autorizar o cartão (com 3DS). Aprovada a autorização, vira ACTIVE.
  • contractId precisa ser um contrato (ctr_) do merchant que não esteja refused, expired nem canceled (não precisa estar assinado) → senão 422 DEPOSIT.CONTRACT_NOT_USABLE.
  • Informe customerId (cus_) ou payer; com customerId, o cartão autorizado precisa ser desse cliente.
  • Modo e tarifa seguem a configuração do merchant na Kodano: mode e feeAmount voltam na caução.
  • Com autoRenew, a Kodano renova a autorização antes de ela vencer, até coverageEndsAt.
  • Merchant sem caução habilitada → 422 DEPOSIT.NOT_ENABLED.
  • Sem payments:deposits:write → 403 AUTH.ENTITLEMENT_MISSING.

Authorization

kodanoOAuth payments:deposits:write
headerAuthorizationBearer <token>

Token obtido no Zitadel do ambiente (POST /oauth/v2/token), fora do host da API, e enviado em Authorization: Bearer <access_token>.

  • Sandbox: https://kodano-uat-p55zt6.us1.zitadel.cloud/oauth/v2/token
  • Produção: https://kodano-prod-qe8hbt.us1.zitadel.cloud/oauth/v2/token

Use sempre o tokenUrl devolvido na emissão da credencial. Duas variantes: private_key_jwt (preferida; grant urn:ietf:params:oauth:grant-type:jwt-bearer com assertion RS256 assinada pela chave da credencial, iss = sub = userId, aud = authority do Zitadel, kid = keyId) e client_secret (grant client_credentials). O OpenAPI só modela a segunda.

O parâmetro scope do token é OIDC, não os escopos da API: openid urn:zitadel:iam:org:project:id:<projectId da API>:aud urn:zitadel:iam:user:resourceowner. Sem o :aud a API responde 401 AUTH.TOKEN_INVALID; sem resourceowner, 403 AUTH.TENANT_MISMATCH.

Os 28 escopos abaixo são os entitlements concedidos à credencial pelos produtos de integração (produto:recurso:ação; write não implica read), avaliados a cada requisição; não são pedidos no token. O tenant vem da organização do token; o merchant, de X-Merchant-Id. Revogar a credencial nega os tokens já emitidos em até 60 s.

Scope: payments:deposits:write

Header Parameters

X-Merchant-Id*string

Merchant da operação (mrc_ + Guid sem hífens, minúsculo). Obrigatório com credencial de organização (ausente → 400 MERCHANT.HEADER_REQUIRED); com credencial de merchant é opcional (ausente = o próprio merchant). Malformado, repetido, inexistente ou de outro tenant → 403 MERCHANT.FORBIDDEN (nunca 404). Vazio = ausente.

Match^mrc_[0-9a-f]{32}$
Idempotency-Key*string

UUID, retido por 24 h a partir da primeira chamada. Escopo: (tenant, merchant, rota-template, chave). Mesma chave e mesmo corpo → resposta original (2xx ou 4xx) com X-Idempotent-Replay: true; corpo ou path concreto diferente → 409 IDEMPOTENCY.CONFLICT; em execução ou desfecho desconhecido → 409 IDEMPOTENCY.IN_PROGRESS com resourceId e Retry-After: 2. Ausente ou não-UUID → 422 IDEMPOTENCY.KEY_REQUIRED.

Formatuuid
X-Correlation-Id?string

Opcional, sempre ecoado na resposta e repetido em correlationId do Problem. Ausente ou inválido → o serviço gera UUID v7.

Match^[A-Za-z0-9._-]{1,64}$

Request Body

application/json
  1. body
contractId*string

ctr_ do contrato do merchant.

customerId?string

cus_; sem ele, payer é obrigatório.

payer?
name?string
Lengthlength <= 255
description?string
Lengthlength <= 255
amount*integer

Centavos.

Formatint64
Range1 <= value
currency*"BRL"

Único valor na v1.

Value in"BRL"
coverageStartsAt*string
Formatdate-time
coverageEndsAt*string

Depois de coverageStartsAt.

Formatdate-time
autoRenew?boolean
Defaultfalse

Response Body

Caução aberta, aguardando a autorização do pagador.

application/json
  1. response
id*string

dpst_ + 27 letras e dígitos.

status*DepositStatus

AWAITING_AUTHORIZATION: aguardando o pagador autorizar o cartão no checkoutUrl. ACTIVE: valor reservado no cartão. RENEWAL_AT_RISK: a renovação automática falhou e será tentada de novo. UNSECURED: sem autorização válida (renovação negada ou cobertura encerrada sem renovar). RELEASED, CAPTURED e REFUNDED são finais.

Value in"AWAITING_AUTHORIZATION""ACTIVE""RENEWAL_AT_RISK""UNSECURED""RELEASED""CAPTURED""REFUNDED"
mode*DepositMode

PREAUTH_RENEWAL: reserva renovada no cartão, tarifa depois. PREAUTH_FEE_UPFRONT: reserva renovada, tarifa cobrada na abertura. IMMEDIATE_CHARGE: o valor é cobrado na abertura e devolvido no encerramento.

Value in"PREAUTH_RENEWAL""PREAUTH_FEE_UPFRONT""IMMEDIATE_CHARGE"
autoRenew*boolean
contractId*string
customerId*|

null até a autorização, quando a caução foi aberta com payer.

name*string|null
description*string|null
amount*integer
Formatint64
currency*"BRL"

Único valor na v1.

Value in"BRL"
coverageStartsAt*string
Formatdate-time
coverageEndsAt*string
Formatdate-time
guaranteeEndsAt*|

Até quando a autorização vigente cobre a caução.

Formatdate-time
checkoutUrl*|

Só em AWAITING_AUTHORIZATION.

Formaturi
card*|null
authorizationExpiresAt*|
Formatdate-time
nextRenewalAttemptAt*|
Formatdate-time
unsecuredReason*|
Value in"RENEWAL_DENIED""EXPIRED_AS_PLANNED"null
feeAmount*|
Formatint64
capturedAmount*|
Formatint64
refundAmount*|
Formatint64
damageDescription*string|null
createdAt*string
Formatdate-time
updatedAt*string
Formatdate-time
Example Request
curl -X POST 'https://api.sandbox.kodano.com.br/v1/deposits' \  -H 'X-Merchant-Id: mrc_0f8fad5bd9cb469fa16570867728950e' \  -H 'Idempotency-Key: 4b2e8c1a-9d7f-4e3b-a6c5-0f1e2d3c4b5a' \  -H 'X-Correlation-Id: erp-7f3a-0010' \  -H 'Content-Type: application/json' \  -d '{  "contractId": "ctr_0192f3c1a7b84e2d9f0a1b2c3d4e5f60",  "payer": {    "name": "Ana Souza",    "document": "12345678909",    "email": "ana@exemplo.com"  },  "name": "Caução Villa Trancoso",  "amount": 500000,  "currency": "BRL",  "coverageStartsAt": "2026-11-02T00:00:00Z",  "coverageEndsAt": "2026-12-05T00:00:00Z",  "autoRenew": true}'
Example Response
{  "id": "dpst_7Hq2LmX9vB4nR8sT1wK6yZ3cP0a",  "status": "AWAITING_AUTHORIZATION",  "mode": "PREAUTH_RENEWAL",  "autoRenew": true,  "contractId": "ctr_0192f3c1a7b84e2d9f0a1b2c3d4e5f60",  "customerId": null,  "name": "Caução Villa Trancoso",  "description": null,  "amount": 500000,  "currency": "BRL",  "coverageStartsAt": "2026-11-02T00:00:00Z",  "coverageEndsAt": "2026-12-05T00:00:00Z",  "guaranteeEndsAt": null,  "checkoutUrl": "https://pay.kodano.com.br/ord_0192f3c2d4e5f6a7b8c9d0e1f2a3b4c6",  "card": null,  "authorizationExpiresAt": null,  "nextRenewalAttemptAt": null,  "unsecuredReason": null,  "feeAmount": null,  "capturedAmount": null,  "refundAmount": null,  "damageDescription": null,  "createdAt": "2026-10-28T15:05:00Z",  "updatedAt": "2026-10-28T15:05:00Z"}

Listar cauções GET

Anterior

Consultar caução GET

Próxima