Transferir entre contas PayZu
Mande saldo para outra conta PayZu pela agência e pelo número dela. A tarifa é debitada só da sua conta, além do valor.
Faça a transferência
| Campo | Regra |
|---|---|
Idempotency-Key | Cabeçalho. Gere uma por transferência. |
amount | Valor em centavos. |
destinationAccount.branch | Agência da outra conta PayZu, com até 4 dígitos. |
destinationAccount.number | Número da conta, com o verificador opcional depois do hífen. |
comment | Opcional. Aparece no comprovante. |
A sua conta precisa ter uma chave Pix ativa para enviar; veja Chaves Pix. Na resposta, counterparty.account traz a conta como está cadastrada, com os zeros à esquerda.
IDEMPOTENCY_KEY=$(uuidgen)
curl --request POST \
--url 'https://api.sandbox.payzu.dev/api/v1/transactions/internal-transfer' \
--header 'Authorization: Bearer SEU_TOKEN' \
--header "Idempotency-Key: $IDEMPOTENCY_KEY" \
--header 'Content-Type: application/json' \
--data '{
"amount": 10000,
"destinationAccount": { "branch": "0001", "number": "998812" },
"comment": "Repasse do mês"
}'{
"id": "P20261005120244L9G3VH6KMAC127431",
"status": "CONFIRMED",
"side": "SENT",
"amount": 10000,
"serviceFee": 100,
"totalDebited": 10100,
"counterparty": {
"name": "Loja Parceira Ltda",
"document": "12.345.678/0001-95",
"bank": { "name": "Banco Exemplo S.A.", "ispb": "99999999" },
"account": { "branch": "0001", "number": "998812" }
},
"comment": "Repasse do mês",
"failureReason": null,
"callbackUrl": null,
"createdAt": "2026-10-05T15:02:44.010Z",
"confirmedAt": "2026-10-05T15:02:44.418Z",
"failedAt": null
}Referência: Transferir para outra conta PayZu
Trate o 502
O estado da transferência depende da resposta do banco parceiro.
| O banco parceiro | Status | Valor |
|---|---|---|
Recusou a transferência, com o código PROVIDER_REFUSED. | FAILED | De volta ao saldo. |
| Ficou indisponível ou não respondeu a tempo. | REQUESTED | Reservado até o suporte da PayZu confirmar com o banco parceiro o desfecho. |
De REQUESTED, a transferência passa a CONFIRMED, com o valor creditado no destino e os avisos de sempre, ou a FAILED, com o valor de volta ao saldo. Se ela terminar FAILED, mostre ao usuário o texto de failureReason.
Repetir com a mesma Idempotency-Key retorna essa transferência, sem enviar outra.
Uma Idempotency-Key nova cria outra transferência. A cota é de 5 transferências por minuto por credencial e 10 por conta.
Confirme a transferência
O resultado já vem na resposta da criação. Com CONFIRMED, o valor está na outra conta; use esse status para liberar o que depende do repasse.
| Aviso | Quem recebe |
|---|---|
INTERNAL_TRANSFER_SENT | Os webhooks da sua conta e a callbackUrl informada na operação. |
INTERNAL_TRANSFER_RECEIVED | Os webhooks da conta de destino. |
Os corpos estão em Transferência enviada e Transferência recebida. No extrato, a linha da transferência traz a agência e o número da outra conta em counterparty.account.
A transferência não tem externalRef.
Guarde o id da resposta com o seu pedido para casar os avisos: ele é o mesmo transferId dos webhooks, igual nas duas contas.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
TRANSFER_DISABLED | 403 | Transferência entre contas desabilitada para esta conta. |
TRANSFER_DESTINATION | 404 | Nenhuma conta do hub tem esta agência e este número. |
TRANSFER_ABOVE_TICKET_MAX | 422 | O valor excede o máximo permitido para transferência entre contas. |
TRANSFER_AMBIGUOUS_DESTINATION | 422 | Esta agência e este número estão em mais de uma conta; não dá para decidir o destino. |
TRANSFER_BELOW_TICKET_MIN | 422 | O valor é inferior ao mínimo permitido para transferência entre contas. |
TRANSFER_DAILY_LIMIT | 422 | O limite diário de transferência desta conta foi atingido. |
TRANSFER_DESTINATION_NOT_ACTIVE | 422 | A conta de destino não está ativa. |
TRANSFER_DIFFERENT_PROVIDER | 422 | A conta de destino está em outra instituição; use um PIX. |
TRANSFER_INSUFFICIENT_BALANCE | 422 | Saldo insuficiente para esta transferência. |
TRANSFER_MAIN_ACCOUNT_DESTINATION | 422 | A conta principal da PayZu não recebe transferência entre contas; para pagar a PayZu, use uma cobrança. |
TRANSFER_NOT_SUPPORTED | 422 | Esta conta não faz transferência entre contas. |
TRANSFER_NO_DESTINATION_KEY | 422 | A conta de destino não tem chave PIX ativa para receber a transferência. |
TRANSFER_NO_ORIGIN_KEY | 422 | Esta conta não tem chave PIX ativa para enviar a transferência. |
TRANSFER_SAME_ACCOUNT | 422 | A conta de destino é a própria conta de origem. |
PROVIDER_REFUSED | 502 | Esta operação foi recusada. Confira os dados enviados. |
PROVIDER_UNAVAILABLE | 502 | Não houve resposta a tempo. Tente de novo em instantes. |
Todos os códigos do PayZu Conta Hub estão no Catálogo de erros.