Idempotência

Nas operações que criam algo ou movimentam dinheiro, envie uma chave estável por operação no campo idempotency_key do corpo:

{ "idempotency_key": "pedido-4821" }

Repetir a chamada com a mesma chave — depois de um timeout, por exemplo — devolve a operação que já foi criada, em vez de criar outra. A chave vale por empresa: duas empresas podem usar o mesmo valor sem conflito.

const resposta = await fetch("https://integrate.api.kyvopay.com.br/v1/payments", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.KYVO_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount_centavos: 4990,
    description: `Pedido ${pedido.id}`,
    idempotency_key: `pedido-${pedido.id}`,
    customer: { name: cliente.nome, email: cliente.email, document: cliente.cpf },
  }),
});

O campo aceito é idempotency_key em POST /v1/payments, /v1/payouts, /v1/refunds e /v1/transfers. A única rota que recebe a chave como header, Idempotency-Key, é a abertura de checkout de um link público (POST /v1/public/links/{slug}/checkout).