# Transferir para outra conta PayZu (/docs/conta-digital/endpoints/internal-transfers/post_internal_transfer)

## POST /transactions/internal-transfer

`POST https://api.hub.payzu.com.br/api/v1/transactions/internal-transfer`

Escopo: `INTERNAL_TRANSFER`. Envia dinheiro da sua conta para outra conta PayZu, identificada pela chave Pix dela. O valor não passa pelo Pix, e a resposta já traz o resultado: `CONFIRMED` é dinheiro entregue. A tarifa é somada por cima. Num `502` em que o banco não respondeu ou recusou temporariamente, a transferência fica `REQUESTED` e só a mesma `Idempotency-Key` devolve a original; recusa definitiva deixa a transferência `FAILED`. Limite de requisições: 5 por minuto por credencial e 10 por conta.

### Header params

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | no | Valor único por operação, de 1 a 255 caracteres ASCII visíveis, sem espaço. Repetir a chave com o mesmo valor e destino devolve a operação original; com outro valor ou destino, `409`. Vale por conta, sem expiração. — minLength: 1; maxLength: 255 |

### Body params

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `amount` | integer | yes | Valor que chega ao destino. A tarifa é somada por cima. Em centavos. — minimum: 1 |
| `toPixKey` | string | yes | Chave Pix de outra conta PayZu. — minLength: 1; maxLength: 77 |
| `comment` | string | no | Texto que aparece no comprovante. — maxLength: 140 |
| `callbackUrl` | string | no | URL HTTPS pública que recebe todos os webhooks desta operação, além dos endpoints cadastrados. Até 2048 caracteres. Exige o segredo de callback da conta. O webhook `INTERNAL_TRANSFER_RECEIVED`, da conta de destino, não vai para ela. — format: uri; maxLength: 2048 |

### Responses

**201** Transferência registrada.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `id` | string | yes | Identificador da transferência. A consulta aceita este `id` e o `transferId` dos webhooks. |
| `status` | string | yes | `REQUESTED`: ainda sem resultado, depois de um `502` em que o banco não respondeu ou recusou temporariamente. `CONFIRMED`: o valor está na outra conta. `FAILED`: não saiu. — `REQUESTED`, `CONFIRMED`, `FAILED` |
| `side` | string | yes | Ponta em que a sua conta está: `SENT` (enviou) ou `RECEIVED` (recebeu). — `SENT`, `RECEIVED` |
| `amount` | integer | yes | Valor que chegou ao destino. Em centavos. |
| `serviceFee` | integer | yes | Tarifa. `0` do lado de quem recebe. Em centavos. |
| `totalDebited` | integer | yes | `amount + serviceFee`. `0` do lado de quem recebe. Em centavos. |
| `counterparty` | object | yes | A outra conta. |
| `counterparty.name` | string | yes | Nome da outra conta. |
| `counterparty.document` | string | yes | Documento da outra conta: CPF mascarado ou CNPJ formatado. Vazio quando não é conhecido. |
| `counterparty.pixKey` | string | yes | Chave da outra conta. Inteira na resposta do `POST`; na consulta e na listagem, CPF, e-mail e telefone saem mascarados. |
| `comment` | string | null | yes | Texto do comprovante. |
| `providerRejectedReason` | string | null | yes | Mensagem pronta para exibir, preenchida quando `FAILED`. |
| `callbackUrl` | string | null | yes | A `callbackUrl` enviada na criação. `null` quando não foi enviada. `null` do lado de quem recebeu. |
| `createdAt` | string | yes | Data e hora em ISO 8601, UTC. — format: date-time |
| `confirmedAt` | string | null | yes | Quando foi concluída. `null` até concluir. — format: date-time |
| `failedAt` | string | null | yes | Quando falhou. `null` se não falhou. — format: date-time |

**400** Requisição inválida.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Descrição em português, pronta para exibir. Pode mudar a qualquer momento. |
| `code` | string | yes | Código estável do erro. É por ele que o seu sistema decide o que fazer. |
| `details` | object | no | Contexto estruturado do erro, quando existe. |

**401** Credencial ausente, inválida ou expirada.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Descrição em português, pronta para exibir. Pode mudar a qualquer momento. |
| `code` | string | yes | Código estável do erro. É por ele que o seu sistema decide o que fazer. |
| `details` | object | no | Contexto estruturado do erro, quando existe. |

**403** Sem permissão: escopo, IP ou operação desabilitada.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Descrição em português, pronta para exibir. Pode mudar a qualquer momento. |
| `code` | string | yes | Código estável do erro. É por ele que o seu sistema decide o que fazer. |
| `details` | object | no | Contexto estruturado do erro, quando existe. |

**404** Não encontrado, ou de outra conta.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Descrição em português, pronta para exibir. Pode mudar a qualquer momento. |
| `code` | string | yes | Código estável do erro. É por ele que o seu sistema decide o que fazer. |
| `details` | object | no | Contexto estruturado do erro, quando existe. |

**409** Conflito com o estado atual.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Descrição em português, pronta para exibir. Pode mudar a qualquer momento. |
| `code` | string | yes | Código estável do erro. É por ele que o seu sistema decide o que fazer. |
| `details` | object | no | Contexto estruturado do erro, quando existe. |

**412** Falta um passo antes desta operação.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Descrição em português, pronta para exibir. Pode mudar a qualquer momento. |
| `code` | string | yes | Código estável do erro. É por ele que o seu sistema decide o que fazer. |
| `details` | object | no | Contexto estruturado do erro, quando existe. |

**422** Recusa de regra de negócio.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Descrição em português, pronta para exibir. Pode mudar a qualquer momento. |
| `code` | string | yes | Código estável do erro. É por ele que o seu sistema decide o que fazer. |
| `details` | object | no | Contexto estruturado do erro, quando existe. |

**429** Limite de requisições excedido.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Descrição em português, pronta para exibir. Pode mudar a qualquer momento. |
| `code` | string | yes | Código estável do erro. É por ele que o seu sistema decide o que fazer. |
| `details` | object | no | Contexto estruturado do erro, quando existe. |

**502** O banco não respondeu ou recusou.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Descrição em português, pronta para exibir. Pode mudar a qualquer momento. |
| `code` | string | yes | Código estável do erro. É por ele que o seu sistema decide o que fazer. |
| `details` | object | no | Contexto estruturado do erro, quando existe. |

**503** Serviço de consulta ou limitador indisponível; nada foi feito.

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `message` | string | yes | Descrição em português, pronta para exibir. Pode mudar a qualquer momento. |
| `code` | string | yes | Código estável do erro. É por ele que o seu sistema decide o que fazer. |
| `details` | object | no | Contexto estruturado do erro, quando existe. |