Sua primeira cobrança PIX em 5 minutos

Obtenha um token de acessoCopiar link da seção

Troque a credencial por um token no tokenUrl. O scope precisa ter os três valores abaixo, com o projectId da sua credencial:

curl -X POST "$KODANO_TOKEN_URL" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=$KODANO_CLIENT_ID" \
  --data-urlencode "client_secret=$KODANO_CLIENT_SECRET" \
  --data-urlencode "scope=openid urn:zitadel:iam:org:project:id:$KODANO_PROJECT_ID:aud urn:zitadel:iam:user:resourceowner"

{
  "access_token": "Ml8bQkR0ZVV3dXg2UjN5Q2V6dEN1d0pXbEJ4cG9GVnJ5a1F6",
  "token_type": "Bearer",
  "expires_in": 43199
}

O token vale expires_in segundos (cerca de 12 horas). Reaproveite-o até perto de expirar em vez de pedir um novo a cada chamada. Se a sua credencial for private_key_jwt, o pedido muda; veja Credenciais e autenticação.

Crie a cobrança PIXCopiar link da seção

Chame POST /v1/payments/pix com o valor em centavos, a moeda e os dados do pagador. Gere um Idempotency-Key novo (UUID) para cada cobrança: se a rede cair e você repetir a chamada com a mesma chave, a API devolve a mesma cobrança em vez de criar outra.

curl -X POST https://api.sandbox.kodano.com.br/v1/payments/pix \
  -H "Authorization: Bearer $KODANO_ACCESS_TOKEN" \
  -H "X-Merchant-Id: mrc_dbd3bd9cd2ae463997022ee37a888b7a" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15990,
    "currency": "BRL",
    "description": "Pedido 123",
    "customer": {
      "name": "Ana Souza",
      "document": "12345678909",
      "email": "ana@exemplo.com.br"
    },
    "expiresIn": 3600,
    "metadata": { "orderRef": "123" }
  }'

Mostre o QR Code ao pagadorCopiar link da seção

A resposta é 201 Created com a cobrança em PENDING e o bloco pix preenchido:

{
  "id": "pay_OhbVrpoiVgRV5IfLBcbfnoGMbJmT",
  "status": "PENDING",
  "statusReason": null,
  "method": "PIX",
  "amount": 15990,
  "currency": "BRL",
  "description": "Pedido 123",
  "customer": { "id": "cus_iGFfWd3hjOkYRBMe", "name": "Ana Souza", "document": "123******09" },
  "pix": {
    "qrCode": "00020101021226870014br.gov.bcb.pix2565...6304B14A",
    "copyPaste": "00020101021226870014br.gov.bcb.pix2565...6304B14A",
    "expiresAt": "2026-10-16T14:00:00Z",
    "endToEndId": null
  },
  "boleto": null,
  "card": null,
  "nextAction": null,
  "failure": null,
  "refundedAmount": 0,
  "refundedAt": null,
  "paymentLinkId": null,
  "metadata": { "orderRef": "123" },
  "createdAt": "2026-10-16T13:00:00Z",
  "updatedAt": "2026-10-16T13:00:01Z"
}

• pix.copyPaste é o código "copia e cola". pix.qrCode traz o mesmo conteúdo (EMV) para você desenhar o QR Code com a biblioteca que preferir; a API não devolve imagem.
• Guarde o id (pay_…): é com ele que você consulta, estorna ou cancela a cobrança.
• O header Location aponta para /v1/payments/{id}.

Saiba quando foi pagaCopiar link da seção

Quando o pagador paga, a cobrança vai para SUCCEEDED e pix.endToEndId passa a trazer o identificador do PIX recebido. Você fica sabendo de duas formas:

• Webhook (recomendado). Cadastre um endpoint para o evento payment.succeeded e a Kodano envia a cobrança atualizada assim que o pagamento cai. Veja Configurar endpoints e não deixe de verificar a assinatura.
• Consulta. GET /v1/payments/{id} devolve o mesmo objeto com o status atual.

curl https://api.sandbox.kodano.com.br/v1/payments/pay_OhbVrpoiVgRV5IfLBcbfnoGMbJmT \
  -H "Authorization: Bearer $KODANO_ACCESS_TOKEN" \
  -H "X-Merchant-Id: mrc_dbd3bd9cd2ae463997022ee37a888b7a"

Se ninguém pagar até pix.expiresAt, a cobrança vai para CANCELED com statusReason: "EXPIRED". Para simular o pagamento no sandbox, veja Sandbox e simuladores.