PayZu Conta HubPagar com Pix

Transferir entre contas PayZu


Nesta páginaFaça a transferênciaTrate o 502Confirme a transferênciaErros desta operação

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

CampoRegra
Idempotency-KeyCabeçalho. Gere uma por transferência.
amountValor em centavos.
destinationAccount.branchAgência da outra conta PayZu, com até 4 dígitos.
destinationAccount.numberNúmero da conta, com o verificador opcional depois do hífen.
commentOpcional. 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.

bash
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"
  }'

Referência: Transferir para outra conta PayZu

Trate o 502

O estado da transferência depende da resposta do banco parceiro.

O banco parceiroStatusValor
Recusou a transferência, com o código PROVIDER_REFUSED.FAILEDDe volta ao saldo.
Ficou indisponível ou não respondeu a tempo.REQUESTEDReservado 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.

AvisoQuem recebe
INTERNAL_TRANSFER_SENTOs webhooks da sua conta e a callbackUrl informada na operação.
INTERNAL_TRANSFER_RECEIVEDOs 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ódigoHTTPMensagem
TRANSFER_DISABLED403Transferência entre contas desabilitada para esta conta.
TRANSFER_DESTINATION404Nenhuma conta do hub tem esta agência e este número.
TRANSFER_ABOVE_TICKET_MAX422O valor excede o máximo permitido para transferência entre contas.
TRANSFER_AMBIGUOUS_DESTINATION422Esta agência e este número estão em mais de uma conta; não dá para decidir o destino.
TRANSFER_BELOW_TICKET_MIN422O valor é inferior ao mínimo permitido para transferência entre contas.
TRANSFER_DAILY_LIMIT422O limite diário de transferência desta conta foi atingido.
TRANSFER_DESTINATION_NOT_ACTIVE422A conta de destino não está ativa.
TRANSFER_DIFFERENT_PROVIDER422A conta de destino está em outra instituição; use um PIX.
TRANSFER_INSUFFICIENT_BALANCE422Saldo insuficiente para esta transferência.
TRANSFER_MAIN_ACCOUNT_DESTINATION422A conta principal da PayZu não recebe transferência entre contas; para pagar a PayZu, use uma cobrança.
TRANSFER_NOT_SUPPORTED422Esta conta não faz transferência entre contas.
TRANSFER_NO_DESTINATION_KEY422A conta de destino não tem chave PIX ativa para receber a transferência.
TRANSFER_NO_ORIGIN_KEY422Esta conta não tem chave PIX ativa para enviar a transferência.
TRANSFER_SAME_ACCOUNT422A conta de destino é a própria conta de origem.
PROVIDER_REFUSED502Esta operação foi recusada. Confira os dados enviados.
PROVIDER_UNAVAILABLE502Nã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.