EvoPay
POST/pix/DEPOSIT

Criar cobrança Pix

Requer permissão DEPOSIT no token.

Cria uma cobrança Pix (cash-in). Retorna QR Code para pagamento.

Splits configuráveis (campo splits)

Cada depósito pode opcionalmente distribuir parte do valor pra outros usuários já cadastrados e ativos na EvoPay. O array é validado e persistido na criação, mas executado só na confirmação do pagamento — quando o webhook de status é disparado.

Regra de cálculo: no tipo fixed, o recebedor sempre recebe o valor cheio informado em value, em reais — não existe variante protected para fixed. No tipo percent com protected true, o percentual incide sobre o valor bruto da transação, e o seller absorve a taxa EvoPay sozinho. No tipo percent com protected false (padrão), o percentual incide sobre o valor líquido, já descontada a taxa EvoPay. Splits fixed e percent podem coexistir na mesma transação — cada um calcula sobre sua própria base, em paralelo, não em cascata.

Exemplo: depósito de R$5,00, taxa EvoPay de R$0,50 (líquido R$4,50), um split percent de 10%. Com protected true, o split incide sobre o bruto (R$5,00): valor do split R$0,50, seller recebe R$4,00. Com protected false, o split incide sobre o líquido (R$4,50): valor do split R$0,45, seller recebe R$4,05.

Validação e comportamento de erro: a única validação de split que bloqueia a criação da cobrança é estrutural do payload — enviar protected junto com type fixed retorna 400 antes da cobrança existir. Nenhuma outra validação de split bloqueia a venda: tudo o resto é resolvido na confirmação do pagamento, sem afetar a cobrança.

Falha de identidade (recipientId inexistente ou inativo): só aquele split específico falha. Os demais splits válidos executam normalmente e o repasse ao seller acontece normalmente.

Falha estrutural (soma dos splits percent da transação acima de 100%, ou soma dos splits fixed acima do valor líquido disponível): todo o array de splits é rejeitado — tudo ou nada, diferente da falha de identidade, que é parcial. Nenhum split executa, e o valor líquido cheio é creditado ao seller. Em ambos os casos a venda nunca é bloqueada, cancelada ou afetada.

Risco aceito, não é bug: com protected true e percentual alto (até 100%), o seller pode ficar com saldo negativo naquela transação específica — o split incide sobre o bruto e a taxa EvoPay é descontada por fora, independente do split. Quem configura o split assume essa consequência.

O array splits retornado nesta resposta é um eco do que foi persistido — todo item vem com status PENDING, já que a execução real acontece na confirmação do pagamento. Consulte GET /pix/ depois do webhook processar para ver o status final (EXECUTED ou FAILED).

Headers

AuthorizationBearer <seu_token>
Content-Typeapplication/json

Body da requisiçãoobrigatório

CampoTipoDescrição
amount*
number—
callbackUrl
stringuri—
generatedName
stringNome do pagador esperado — apenas letras, espaços e acentos
generatedDocument
stringCPF (11 dígitos) ou CNPJ (14 dígitos) do pagador esperado
generatedEmail
string—
expiresIn
integerTempo de expiração em segundos
clientReference
stringID externo para correlação no seu sistema
splits
object[]Splits configuráveis da venda. Ver detalhes de cálculo e comportamento de erro na descrição do endpoint acima.

Respostas

Cobrança criada com sucesso

CampoTipoDescrição
id
string—
type
TransactionType
DEPOSITWITHDRAWCOMMISSION
status
TransactionStatus
PENDINGCOMPLETEDCANCELEDWAITING_FOR_REFUNDREFUNDEDEXPIREDERROR
amount
number—
serviceFeeCharged
number?—
clientReference
string?—
qrCodeText
string?—
qrCodeUrl
string?—
qrCodeBase64
string?—
generatedName
string?—
generatedDocument
string?—
generatedEmail
string?—
payerName
string?—
payerDocument
string?—
payerInstitutionIspb
string?—
payerInstitutionName
string?—
receiverName
string?—
receiverDocument
string?—
receiverInstitutionIspb
string?—
receiverInstitutionName
string?—
withdrawPixKey
string?Chave PIX usada no saque (preenchido em saque via chave)
withdrawPixType
PixType?Tipo da chave PIX (preenchido em saque via chave)
cpfcnpjemailphoneevp
withdrawQrCodeText
string?Payload EMV Pix Copia e Cola usado no saque (preenchido em saque via QR Code)
endToEndId
string?—
cancellationReason
string?—
paidAt
string?date-time—
refundEndToEndId
string?—
refundAmount
number?—
refundStatus
RefundStatus?
PENDINGCOMPLETEDCANCELED
refundReason
RefundReason?
CUSTOMER_REQUESTDENY_COMPANY_DEPOSITINFRACTION
refundDescription
string?—
refundedAt
string?date-time—
createdAt
stringdate-time—
updatedAt
stringdate-time—
splits
TransactionSplitItem[]Splits configurados na venda, ecoando exatamente o que foi persistido. Na criação (POST /pix/) todo item vem com status PENDING — a execução real só acontece na confirmação do pagamento. Consulte novamente via GET /pix/ depois do webhook processar para ver EXECUTED ou FAILED. Ausente inteiramente (não aparece nem vazio) quando a transação não foi criada com o campo splits no request. Veja detalhes de cálculo e comportamento de erro em POST /pix/.

Exemplos

curl "https://api.evopay.cash/v1/pix/" \
  -X POST \
  -H "Authorization: Bearer <seu_token>" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "amount": 100,
  "callbackUrl": "https://seu-servidor.com/webhook",
  "generatedName": "exemplo",
  "generatedDocument": "12345678901",
  "generatedEmail": "usuario@email.com",
  "expiresIn": 30,
  "clientReference": "exemplo",
  "splits": [
    {
      "recipientId": "EPB1694C2C35E94053874D53B1",
      "type": "fixed",
      "value": 100,
      "protected": true
    }
  ]
}'
EvoPay API Documentation