Criar Ordem PIX

Criar ordem de PIX

POST /api/v1/pix

Cria uma nova ordem de PIX a partir do fluxo CNAB. A requisicao passa por validacao antifraude de limites antes de ser aceita.

Este endpoint exige autenticacao HMAC-SHA256. Veja Autenticacao HMAC para detalhes.

Request

Headers

Header	Obrigatorio	Descricao
`Content-Type`	sim	`application/json`
`Idempotency-Key`	sim	UUID v4 unico por requisicao
`X-Client-Id`	sim	Identificador do cliente
`X-Timestamp`	sim	ISO-8601 UTC (`2026-04-26T14:30:00Z`)
`X-Signature`	sim	`hmac-sha256=<hex>`

Body

{
  "dataLancamento": "2026-04-26",
  "valor": 150.00,
  "tipoChave": "CHAVE_PIX_EMAIL",
  "chavePix": "favorecido@empresa.com",
  "favorecido": {
    "nome": "João da Silva",
    "tipoInscricao": "CPF",
    "numeroInscricao": "12345678901",
    "codigoBanco": "001",
    "agencia": "1234",
    "digitoAgencia": "0",
    "conta": "123456",
    "digitoConta": "7"
  },
  "identificacaoPagamento": "PAG-2026-001"
}

Campos do request

Campo	Tipo	Obrigatorio	Validacao	Descricao
`dataLancamento`	date	sim	Formato `YYYY-MM-DD`	Data de lancamento do pagamento
`valor`	number	sim	Minimo `0.01`	Valor do PIX em reais
`tipoChave`	enum	sim	Ver tabela abaixo	Tipo da chave PIX
`chavePix`	string	sim	Max 99 caracteres	Chave PIX do favorecido
`favorecido`	objeto	sim	—	Dados do favorecido
`identificacaoPagamento`	string	nao	Max 60 caracteres	Identificador livre do pagamento

Tipos de chave (`tipoChave`)

Valor	Descricao
`CHAVE_PIX_TELEFONE`	Numero de telefone
`CHAVE_PIX_EMAIL`	Endereco de email
`CHAVE_PIX_CPF_CNPJ`	CPF ou CNPJ
`CHAVE_ALEATORIA`	Chave aleatoria (EVP)
`DADOS_BANCARIOS`	Dados bancarios (agencia + conta)

Dados do favorecido (`favorecido`)

Campo	Tipo	Obrigatorio	Validacao	Descricao
`nome`	string	sim	Max 30 caracteres	Nome do favorecido
`tipoInscricao`	enum	sim	`CPF` ou `CNPJ`	Tipo do documento
`numeroInscricao`	string	sim	11 digitos (CPF) ou 14 digitos (CNPJ)	Numero do documento
`codigoBanco`	string	nao	Max 3 caracteres	Codigo do banco (ISPB)
`agencia`	string	nao	Max 5 caracteres	Numero da agencia
`digitoAgencia`	string	nao	Max 5 caracteres	Digito da agencia
`conta`	string	nao	Max 12 caracteres	Numero da conta
`digitoConta`	string	nao	Max 5 caracteres	Digito da conta

Os campos bancarios (codigoBanco, agencia, conta, etc.) sao obrigatorios quando tipoChave for DADOS_BANCARIOS.

Response

`201 Created`

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "numeroDocumento": "12345678901",
  "tipoMovimento": "PIX",
  "status": "PENDING",
  "dataLancamento": "2026-04-26",
  "valor": 150.00,
  "tipoChave": "CHAVE_PIX_EMAIL",
  "chavePix": "favorecido@empresa.com",
  "favorecido": {
    "nome": "João da Silva",
    "tipoInscricao": "CPF",
    "numeroInscricao": "12345678901",
    "codigoBanco": "001",
    "agencia": "1234",
    "digitoAgencia": "0",
    "conta": "123456",
    "digitoConta": "7"
  },
  "identificacaoPagamento": "PAG-2026-001",
  "criadoEm": "2026-04-26T14:30:01.234Z",
  "atualizadoEm": "2026-04-26T14:30:01.234Z"
}

Campos da response

Campo	Tipo	Descricao
`id`	UUID	Identificador unico da ordem PIX
`numeroDocumento`	string	Numero do documento do favorecido
`tipoMovimento`	string	Tipo do movimento
`status`	string	Status da ordem
`dataLancamento`	date	Data de lancamento
`valor`	number	Valor em reais
`tipoChave`	string	Tipo da chave PIX usada
`chavePix`	string	Chave PIX do favorecido
`favorecido`	objeto	Dados completos do favorecido
`identificacaoPagamento`	string	Identificador do pagamento
`criadoEm`	datetime	Timestamp de criacao
`atualizadoEm`	datetime	Timestamp da ultima atualizacao

Erros

`400 Bad Request`

Erro de validacao ou header obrigatorio ausente.

{
  "code": "VALIDATION_ERROR",
  "message": "Falha de validacao",
  "details": [
    { "campo": "valor", "erro": "must be greater than or equal to 0.01" },
    { "campo": "chavePix", "erro": "must not be blank" }
  ],
  "traceId": "abc123def456",
  "timestamp": "2026-04-26T14:30:01.234Z"
}

`409 Conflict`

Idempotency-Key ja utilizada com body diferente.

{
  "code": "CONFLICT",
  "message": "Idempotency-Key ja utilizada",
  "traceId": "abc123def456",
  "timestamp": "2026-04-26T14:30:01.234Z"
}

`422 Unprocessable Entity`

Limite antifraude excedido.

{
  "code": "LIMIT_EXCEEDED",
  "message": "Limite antifraude excedido",
  "traceId": "abc123def456",
  "timestamp": "2026-04-26T14:30:01.234Z"
}

`401 / 403`

Falha de autenticacao HMAC. Veja codigos de erro da autenticacao.

`500 Internal Server Error`

Erro interno. Inclua o traceId ao reportar.

Formato de erro

Todas as respostas de erro seguem o formato:

Campo	Tipo	Descricao
`code`	string	Codigo do erro
`message`	string	Mensagem legivel
`details`	array	Lista de erros de campo (apenas em validacao)
`traceId`	string	ID de rastreamento
`timestamp`	datetime	Timestamp ISO-8601

Criar Ordem PIX

On this page