Enviar PIX

Envia saldo para uma chave PIX externa; transferências internas continuam disponíveis no painel.

POST/v1/transfersChave de API

Criar transferência#

POST/v1/transfersX-API-Key ou painel

Há dois tipos. pix envia dinheiro para uma chave externa. subaccount move saldo entre a conta principal e uma subconta, sem sair da plataforma.

kindstringobrigatório

pix ou subaccount.

amount_centavosintegerobrigatório

Valor em centavos. Precisa haver saldo disponível.

descriptionstringopcional

Descrição da movimentação. Até 255 caracteres.

pix_keystringopcional

Chave de destino. Obrigatória quando kind é pix.

pix_key_typestringopcional

Um de cpf, cnpj, email, phone, random, evp ou copypaste.

subaccount_iduuidopcional

Subconta envolvida quando kind é subaccount.

directionstringopcional

to_subaccount ou from_subaccount. Padrão to_subaccount.

scheduled_fordatetimeopcional

Agenda a execução para uma data futura.

two_factor_code / passwordstringopcional

Somente no painel. Na API, use uma chave com escopo transfers:write e Idempotency-Key.

Operação sensível

Transferência PIX movimenta saldo real. Pelo painel, a KyvoPay exige confirmação por 2FA ou senha. Pela API, use uma chave com escopo transfers:write e envie sempre uma Idempotency-Key única por operação.

POST/v1/transfers

curl https://api.kyvopay.com.br/v1/transfers \
  -H "X-API-Key: $KYVO_API_KEY" \
  -H "Idempotency-Key: transf-4410" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "pix",
    "amount_centavos": 25000,
    "pix_key": "ana@exemplo.com",
    "pix_key_type": "email",
    "description": "Repasse do parceiro"
  }'

200 OKresposta

{
  "data": {
    "id": "trf_4Gh1Wq62",
    "kind": "pix",
    "status": "pending",
    "amount_centavos": 25000,
    "description": "Repasse do parceiro",
    "failed_reason": null,
    "created_at": "2026-08-11T21:02:00Z",
    "executed_at": null
  },
  "error": null,
  "request_id": "req_bb70c418"
}

Consultar chave PIX#

GET/v1/transfers/pix/lookupChave de API

Consulte o recebedor antes de enviar o PIX. A operação é somente leitura e não movimenta saldo.

keystringobrigatório

CPF, CNPJ, e-mail, telefone ou chave aleatória.

typestringopcional

Opcional: cpf, cnpj, email, phone ou random.

GETconsultar chave

curl -G https://api.kyvopay.com.br/v1/transfers/pix/lookup   -H "X-API-Key: $KYVO_API_KEY"   --data-urlencode "key=cliente@banco.com"   --data-urlencode "type=email"

Saque para conta bancária#

POST/v1/payoutsPainel

Saque é diferente de transferência: ele envia o saldo para uma conta bancária já cadastrada e verificada na sua conta KyvoPay, identificada por bank_account_id.

amount_centavosintegerobrigatório

Valor a sacar. Mínimo 1000 e máximo 100000 centavos (R$ 10,00 a R$ 1.000,00).

bank_account_iduuidobrigatório

Conta de recebimento cadastrada no painel.

two_factor_code / passwordstringopcional

Confirmação do usuário, obrigatória.

Saques acima de um determinado valor passam por aprovação manual antes de sair. O status reflete isso: requested → in_review → approved → processing → paid.