# Enviar PIX

Transfira saldo para uma chave PIX ou um código copia e cola.

POST`/transfer-pix/create`

Try it

## Corpo da requisição

[amount](#request-amount)numberrequired

Valor em reais, com até duas casas decimais. De R$ 5,00 a R$ 1.000,00 por operação.

[coverFee](#request-coverFee)boolean

Padrão true. A taxa é cobrada além do valor enviado; com false, é descontada do valor informado.

[pixKey](#request-pixKey)string

Chave do destinatário. Obrigatória quando não há pixCopyPaste.

[pixKeyType](#request-pixKeyType)string

CPF, CNPJ, EMAIL, TELEFONE ou ALEATORIA.

[pixCopyPaste](#request-pixCopyPaste)string

Alternativa à chave: conteúdo completo do QR Code PIX.

[description](#request-description)string

Descrição que identifica a operação.

[externalReference](#request-externalReference)string

Referência do seu sistema, até 120 caracteres. Deve ser única para o tipo da operação.

## Headers

[Idempotency-Key](#headers-Idempotency-Key)stringrequired

Identificador único de até 128 caracteres. Preserve a chave e o corpo ao repetir a operação.

## Autorização

[X-API-Key](#auth-X-API-Key)stringrequired

Chave VibeCash com permissão para esta operação.

## Resposta

201 application/json

[success](#response-success)booleanrequired

Indica se a operação foi concluída pela API.

[message](#response-message)stringrequired

Mensagem da operação.

[data](#response-data)objectrequired

Dados retornados pela operação.

Show child attributes[id](#response-data-id)string

Identificador da operação.

[status](#response-data-status)string

Situação atual do pagamento ou envio.

[amount](#response-data-amount)number

Valor bruto ou informado, em reais.

[feeAmount](#response-data-feeAmount)number

Taxa da operação, em reais.

[netAmount](#response-data-netAmount)number

Líquido da entrada ou total debitado de uma saída.

[recipientAmount](#response-data-recipientAmount)number

Valor entregue ao destinatário.

[totalDebit](#response-data-totalDebit)number

Total debitado da carteira.

[createdAt](#response-data-createdAt)string

Data e hora da criação em formato ISO.

[requestId](#response-requestId)string

Identificador da requisição.

`netAmount` mantém o total debitado da carteira por compatibilidade. Use `recipientAmount` para o valor recebido pelo destinatário e `totalDebit` para o custo total.

## Erros

As falhas retornam o envelope com `success: false`. Consulte [erros e códigos HTTP](/docs/api-reference/guides/errors) para interpretar validação, permissão, conflito e saldo insuficiente.

## Exemplo de requisição

```bash
curl --request POST \
  --url 'https://seu-dominio/v1/transfer-pix/create' \
  --header 'X-API-Key: tp_live_SUA_CHAVE' \
  --header 'Idempotency-Key: operacao-unica-123' \
  --header 'Content-Type: application/json' \
  --data '{"amount":5,"coverFee":true,"pixKey":"recebedor@exemplo.com","pixKeyType":"EMAIL","description":"Transferência"}'
```

## Exemplo de resposta

```json
{
  "success": true,
  "message": "Operação concluída",
  "data": {
    "id": "out_exemplo",
    "amount": 5,
    "feeAmount": 0.1,
    "netAmount": 5.1,
    "recipientAmount": 5,
    "totalDebit": 5.1,
    "status": "PROCESSING",
    "createdAt": "2026-11-10T15:00:00.000Z"
  },
  "requestId": "req_exemplo"
}
```
