Schemas

Referência completa de todos os tipos e objetos usados na API EvoPay.

Enums

TransactionStatus

Status de uma transação.

Valor	Descrição
`PENDING`	Aguardando processamento ou pagamento
`COMPLETED`	Concluída com sucesso
`CANCELED`	Cancelada — ver `cancellationReason` para o motivo
`WAITING_FOR_REFUND`	Aguardando estorno (infração identificada)
`REFUNDED`	Estornada com sucesso
`EXPIRED`	Cobrança Pix expirou sem pagamento
`ERROR`	Erro interno — contate o suporte se persistir

TransactionType

Tipo de movimentação financeira.

Valor	Descrição
`DEPOSIT`	Entrada de valor via cobrança Pix (cash-in)
`WITHDRAW`	Saída de valor para chave Pix (cash-out)
`COMMISSION`	Comissão interna da plataforma — não gerada pela API

PixType

Tipo de chave Pix usada em saques.

Valor	Descrição
`cpf`	CPF do titular (11 dígitos)
`cnpj`	CNPJ da empresa (14 dígitos)
`email`	Endereço de e-mail
`phone`	Número de telefone com DDD e código do país (ex: `+5511999999999`)
`evp`	Chave aleatória (EVP — Endereço Virtual de Pagamento)

RefundStatus

Status do processo de estorno de uma transação.

Valor	Descrição
`PENDING`	Estorno solicitado, aguardando processamento
`COMPLETED`	Estorno concluído com sucesso
`CANCELED`	Estorno cancelado (ex.: infração rejeitada)

RefundReason

Motivo pelo qual o estorno foi iniciado.

Valor	Descrição
`CUSTOMER_REQUEST`	Solicitação do cliente
`DENY_COMPANY_DEPOSIT`	Depósito recusado pela empresa (ex.: CNPJ bloqueado)
`INFRACTION`	Infração Pix identificada pelo Banco Central

TransactionSplitStatus

Status de execução de um split configurado numa transação.

Valor	Descrição
`PENDING`	Configurado na criação, ainda não processado — execução real só acontece na confirmação do pagamento
`EXECUTED`	Split executado com sucesso, valor creditado ao recebedor
`FAILED`	Split não executado — ver `failureReason`/`failureScope` no webhook para o motivo

InfractionStatus

Status de uma infração Pix no sistema do Banco Central.

Valor	Descrição
`WAITING_PSP`	Aguardando posicionamento do PSP participante
`OPEN`	Infração aberta e em análise
`ACKNOWLEDGED`	Infração reconhecida — o participante concordou com o estorno
`DEFENDED`	Defesa apresentada pelo participante debitado
`ANSWERED`	Infração respondida — análise em andamento
`WAITING_ADJUSTMENTS`	Aguardando ajustes adicionais
`CLOSED`	Infração encerrada com resolução
`CANCELLED`	Infração cancelada antes de resolução

InfractionType

Tipo de infração Pix reportada.

Valor	Descrição
`FRAUD`	Fraude detectada — transação não reconhecida pelo pagador
`REFUND_REQUEST`	Solicitação de devolução de valor
`REFUND_CANCELLED`	Cancelamento de uma solicitação de devolução

AnalysisResult

Resultado da análise de uma infração.

Valor	Descrição
`AGREED`	O participante concordou com o estorno
`DISAGREED`	O participante contestou a infração

ReportedType

Participante que reportou a infração.

Valor	Descrição
`DEBITED_PARTICIPANT`	O participante debitado (quem enviou o Pix) reportou a infração
`CREDITED_PARTICIPANT`	O participante creditado (quem recebeu o Pix) reportou a infração

Objetos

Transaction

Objeto principal retornado por operações de depósito e saque.

Campo	Tipo	Nullable	Descrição
`id`	`string`	não	ID da transação (prefixo `EP` + 24 hex)
`type`	`TransactionType`	não	`DEPOSIT` ou `WITHDRAW`
`status`	`TransactionStatus`	não	Status atual da transação
`amount`	`number`	não	Valor em reais (BRL)
`serviceFeeCharged`	`number`	sim	Taxa de serviço cobrada
`clientReference`	`string`	sim	Referência externa informada na criação
`qrCodeText`	`string`	sim	Payload Pix Copia e Cola (DEPOSIT)
`qrCodeUrl`	`string`	sim	URL do QR Code em imagem (DEPOSIT)
`qrCodeBase64`	`string`	sim	QR Code em base64 (DEPOSIT)
`generatedName`	`string`	sim	Nome do pagador esperado (DEPOSIT)
`generatedDocument`	`string`	sim	CPF/CNPJ do pagador esperado (DEPOSIT)
`generatedEmail`	`string`	sim	E-mail do pagador esperado (DEPOSIT)
`payerName`	`string`	sim	Nome de quem pagou (DEPOSIT, pós-pagamento)
`payerDocument`	`string`	sim	CPF/CNPJ de quem pagou (DEPOSIT, pós-pagamento)
`payerInstitutionIspb`	`string`	sim	ISPB da instituição do pagador
`payerInstitutionName`	`string`	sim	Nome da instituição do pagador
`receiverName`	`string`	sim	Nome do recebedor (WITHDRAW, pós-liquidação)
`receiverDocument`	`string`	sim	CPF/CNPJ do recebedor (WITHDRAW, pós-liquidação)
`receiverInstitutionIspb`	`string`	sim	ISPB da instituição do recebedor
`receiverInstitutionName`	`string`	sim	Nome da instituição do recebedor
`withdrawPixKey`	`string`	sim	Chave Pix de destino (WITHDRAW via chave)
`withdrawPixType`	`PixType`	sim	Tipo da chave Pix de destino (WITHDRAW via chave)
`withdrawQrCodeText`	`string`	sim	Payload EMV Pix Copia e Cola usado no saque (WITHDRAW via QR Code)
`endToEndId`	`string`	sim	ID fim a fim Pix (E2EID)
`cancellationReason`	`string`	sim	Motivo do cancelamento quando `status = CANCELED`
`paidAt`	`string`	sim	Timestamp ISO 8601 do pagamento
`refundEndToEndId`	`string`	sim	E2EID do estorno
`refundAmount`	`number`	sim	Valor estornado
`refundStatus`	`RefundStatus`	sim	Status do estorno
`refundReason`	`RefundReason`	sim	Motivo do estorno
`refundDescription`	`string`	sim	Descrição livre do estorno
`refundedAt`	`string`	sim	Timestamp ISO 8601 do estorno
`createdAt`	`string`	não	Timestamp ISO 8601 de criação
`updatedAt`	`string`	não	Timestamp ISO 8601 da última atualização
`splits`	`TransactionSplitItem[]`	sim	Splits configurados na venda. Ausente inteiramente (não aparece nem vazio) quando a transação não foi criada com o campo `splits` no request

TransactionSplitItem

Split configurado numa venda, no formato retornado por POST/GET /pix/. Todo item vem com status: PENDING na criação — a execução real só acontece na confirmação do pagamento.

Campo	Tipo	Nullable	Descrição
`recipientId`	`string`	não	ID do usuário recebedor, cadastrado e ativo na EvoPay
`type`	`"fixed" \| "percent"`	não	Tipo do split
`value`	`number`	não	Valor configurado, sempre em reais (nunca centavos). Para `fixed`, o valor cheio recebido; para `percent`, o percentual de 0 a 100
`protected`	`boolean`	sim	Null quando `type` é `fixed` — só se aplica a `percent`
`status`	`TransactionSplitStatus`	não	Status de execução do split

TransactionSplitBreakdown

Estado final de um split depois que o webhook de confirmação de pagamento processa a transação. Só aparece no payload do webhook — POST/GET de /pix/ retornam o formato mais enxuto de TransactionSplitItem.

Campo	Tipo	Nullable	Descrição
`recipientId`	`string`	não	ID do usuário recebedor
`recipientName`	`string`	sim	Nome do recebedor. Null quando o split falhou antes de resolver quem é o recebedor
`type`	`"fixed" \| "percent"`	não	Tipo do split
`value`	`number`	não	Valor configurado (reais para `fixed`, percentual 0–100 para `percent`)
`protected`	`boolean`	sim	Null quando `type` é `fixed`
`status`	`TransactionSplitStatus`	não	Status de execução do split
`executedAmount`	`number`	sim	Valor efetivamente creditado ao recebedor. Null quando o split não foi executado
`failureReason`	`string`	sim	Motivo textual da falha. Null quando o split foi executado com sucesso
`failureScope`	`"structural" \| "recipient"`	sim	`structural` quando a falha derrubou o array de splits inteiro (config errada); `recipient` quando é específica daquele recebedor (inexistente/inativo); null quando o split foi executado

SplitWarning

Aviso de que um split configurado não foi aplicado. Só aparece no webhook, junto com splits.

Campo	Tipo	Nullable	Descrição
`recipientId`	`string`	sim	ID do recebedor daquele split. Null em falha estrutural — nesse caso a entrada cobre o array de splits inteiro, não um recebedor específico
`reason`	`string`	não	Motivo da falha

Infraction

Infração Pix associada a uma transação.

Campo	Tipo	Nullable	Descrição
`id`	`string`	não	ID da infração
`protocol`	`string`	não	Protocolo fornecido pelo Banco Central
`status`	`InfractionStatus`	não	Status atual da infração
`type`	`InfractionType`	não	Tipo da infração
`reportedBy`	`ReportedType`	não	Quem abriu a infração
`reportDetails`	`string \| null`	sim	Descrição do motivo da infração
`analysisResult`	`AnalysisResult`	sim	Resultado da análise (disponível após decisão)
`analysisDetails`	`string`	sim	Justificativa da decisão
`reportedAt`	`string`	não	Timestamp ISO 8601 do reporte
`expiresAt`	`string`	sim	Prazo de resolução (ISO 8601)
`createdAt`	`string`	não	Timestamp ISO 8601 de criação
`updatedAt`	`string`	não	Timestamp ISO 8601 da última atualização
`transaction`	`object`	não	Dados resumidos da transação vinculada
`defenseHistory`	`array`	não	Histórico de defesas apresentadas

AutoWithdraw

Configuração de saque automático da conta. Retornado dentro de GET /v1/user/ quando ativo.

Campo	Tipo	Nullable	Descrição
`amount`	`number`	não	Valor mínimo de saldo para disparar o saque automático
`pixKey`	`string`	não	Chave Pix de destino do saque automático
`pixType`	`PixType`	não	Tipo da chave Pix
`active`	`boolean`	não	Se o saque automático está habilitado

DailyWithdrawLimit

Limite diário de saques da conta. Retornado dentro de GET /v1/user/ quando configurado.

Campo	Tipo	Nullable	Descrição
`limit`	`number`	não	Limite diário em reais
`used`	`number`	não	Valor já sacado no dia corrente
`updatedAt`	`string`	não	Timestamp ISO 8601 da última atualização do limite
`lastReset`	`string`	sim	Timestamp ISO 8601 do último reset do contador diário