Requer escopo
payments:create para criar e payments:read para consultar.Requisitos
Antes de criar uma cobranca, confirme que:- A conta esta ativa e habilitada financeiramente.
- O servidor esta com
PAYMENTS_ENABLED=true. - A carteira informada pertence a propria conta.
- O valor esta dentro do limite por pagamento da conta (consulte
/v1/account/fees-limits). - A provedora esta configurada.
Criar cobranca
EnviePOST /v1/payments com Idempotency-Key obrigatorio no header. O corpo exige amountCents, walletId e description.
Status de uma cobranca
Uma cobranca pode estar em uma das seguintes situacoes:Expiracao
Novas cobrancas tem prazo maximo de 1 hora desde a intencao persistida. O prazo pode ser menor se a provedora indicar outro valor. Apos expirar, o copia e cola deixa de ser retornado. Confirmacoes tardias da provedora ainda podem ser conciliadas uma vez.Consultar cobranca
UseGET /v1/payments/{id} para sincronizar a situacao com a provedora. A rota consulta a provedora diretamente, mesmo sem webhook configurado.
curl
Consultar Pix (copia e cola)
UseGET /v1/payments/{id}/pix para obter o copia e cola original e sincronizar a situacao.
curl
Tarifas
As tarifas de recebimento dependem da operacao da conta:- White (Wyze): fixa de 40 centavos.
- Black (Kyvo): 399 pontos-base (3,99%) mais 70 centavos.
/v1/account/fees-limits para os valores exatos da sua conta.
Idempotencia
Sempre envieIdempotency-Key ao criar. Se houver falha de comunicacao, repita a requisicao com a mesma chave, mesmo corpo e mesma credencial. Nao crie outra chave para tentar resolver um resultado incerto. Conflitos retornam HTTP 409.