Enviando Pagamentos PIX

Realize pagamentos PIX para qualquer chave com aprovação e rastreamento completo.

Resumo Rápido

Use o endpoint POST /api/v1/request-payments para criar uma solicitação de pagamento PIX. O sistema processa o pagamento e envia notificações via webhook.

1. Criando um Pagamento

Envie uma requisição POST para criar uma solicitação de pagamento:

Endpoint

POST /api/v1/request-payments

Request Body

{
  "payment_type": "pix",
  "amount": "500.00",
  "pix_key": "123.456.789-00",
  "pix_key_type": "cpf",
  "description": "Pagamento de fornecedor",
  "recipient_name": "Maria Santos",
  "split": [
    {
      "account_id": "uuid-da-conta-origem",
      "percentage": 100
    }
  ]
}

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`payment_type`	string	Sim	Tipo de pagamento: `pix` (para PIX OUT). Valores aceitos: `pix`, `pix_copypaste`, `boleto`, `crypto`, `internal_transfer`
`amount`	string	Sim	Valor do pagamento em BRL. Em `pix_copypaste` com valor fixo, deve ser igual ao valor do código
`pix_key`	string	Sim*	Chave PIX do destinatário. Não exigido quando `payment_type` é `pix_copypaste`
`pix_copy_paste`	string	Sim*	Código PIX Copia e Cola (BR Code/EMV). Obrigatório quando `payment_type` é `pix_copypaste`
`pix_copy_paste_validation`	object	Não	Opcional: resultado da consulta do código (ver seção 3). Se omitido, o sistema consulta por conta própria
`pix_key_type`	string	Não	Tipo: `cpf`, `cnpj`, `email`, `phone`, `evp`, `random` (se omitido, o sistema detecta automaticamente)
`description`	string	Não	Descrição do pagamento
`recipient_name`	string	Não	Nome do destinatário (o DICT sobrescreve com o nome real do titular)
`split`	array	Não	Conta de origem para o débito

Compatibilidade: o campo type também é aceito como alias de payment_type (mesmo padrão do endpoint POST /api/v1/deposits).

2. Consultando o Titular de uma Chave PIX (DICT)

Antes de enviar um pagamento, você pode consultar o DICT (Diretório de Identificadores de Contas Transacionais) para confirmar o titular da chave PIX de destino — nome, documento e banco. Isso evita erros de digitação e fraudes (pagamento para a pessoa errada).

Endpoint

POST /api/v1/pix/validate-key

Request Body

{
  "pix_key": "joao@email.com",
  "pix_key_type": "email"
}

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`pix_key`	string	Sim	Chave PIX do destinatário
`pix_key_type`	string	Sim	Tipo: `cpf`, `cnpj`, `email`, `phone`, `random`

Response 200 OK

{
  "success": true,
  "pix_key": "joao@email.com",
  "pix_key_type": "email",
  "recipient_name": "João da Silva",
  "recipient_document": "123.***.***-00",
  "bank_name": "Banco Exemplo S.A.",
  "bank_code": "00000000",
  "account_type": "corrente"
}

Privacidade (LGPD): o documento do titular é retornado mascarado. Use a consulta apenas para confirmar o destinatário antes do pagamento — não para coletar dados de terceiros.

Custo e cache: a consulta DICT é realizada no provedor BaaS e pode gerar custo por chamada conforme o seu plano. Consultas repetidas para a mesma chave dentro de 5 minutos são servidas de cache — sem nova chamada ao provedor e sem custo adicional.

Dica: ao criar o pagamento (POST /api/v1/request-payments), o sistema consulta o DICT automaticamente e reaproveita a validação na transferência — você não precisa chamar este endpoint manualmente se já confia no destinatário.

3. Exemplo Completo

Exemplo com cURL

curl -X POST "https://ajnapay.com.br/api/v1/request-payments" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "payment_type": "pix",
    "amount": "250.00",
    "pix_key": "joao@exemplo.com",
    "pix_key_type": "email",
    "description": "Pagamento de serviço",
    "recipient_name": "João Silva"
  }'

3. Pagando com PIX Copia e Cola (QR Code)

Use o PIX Copia e Cola quando o destinatário fornecer um QR Code em texto (BR Code / EMV) em vez de uma chave. É o caso de QR Codes de lojas, faturas e cobranças geradas por outros bancos.

Uma chamada é suficiente

O código é enviado direto para a liquidação — o sistema decodifica e paga. Não é necessário consultar o código antes: a consulta (seção 3.2) é opcional, útil apenas para conferir os dados antes de pagar.

3.1 Pagando

Request Body

{
  "payment_type": "pix_copypaste",
  "amount": "2.02",
  "pix_copy_paste": "00020126580014br.gov.bcb.pix0136f56850d7-3ef7-442c-bbd8-aadf13735cfc27600016BR.COM.PAGSEGURO...63043C8A",
  "description": "Pagamento de fatura"
}

Regra do valor

O código BR Code pode ou não trazer o valor embutido:

Código	Comportamento
Com valor fixo (ex.: R$ 2,02)	O campo `amount` deve ser igual ao valor do código. Se divergir, a API retorna `422`
Com valor livre (sem valor)	Você escolhe o valor no campo `amount`

Atenção: o valor informado é o que será debitado da sua conta. Se o código tiver valor fixo, confira antes de enviar para evitar o erro 422.

3.2 Consultando o Código (opcional)

Se quiser conferir o destinatário e o valor antes de pagar, consulte o código. A consulta retorna o recebedor, a cidade, a chave PIX, o valor e o status do QR.

Endpoint

POST /api/v1/pix/parse-copypaste

Request Body

{
  "emv": "00020126580014br.gov.bcb.pix0136f56850d7-...63043C8A"
}

Resposta

Response 200 OK

{
  "success": true,
  "type": "ESTATICO",
  "amount": "2.02",
  "amount_change_mode": null,
  "is_amount_fixed": true,
  "pix_key": "f56850d7-3ef7-442c-bbd8-aadf13735cfc",
  "pix_key_type": "random",
  "txid": "PAGS000000202260921174390",
  "recipient_name": "ALOIS ROTHERMEL JUNIOR",
  "recipient_city": "PORTO ALEGRE",
  "psp_gui": "BR.COM.PAGSEGURO",
  "psp_name": "PagSeguro (PagBank)",
  "status": "ATIVA",
  "expires_at": null,
  "charges": {
    "amount": "2.02",
    "fine": null,
    "interest": null,
    "discount": null,
    "abatement": null
  }
}

Como interpretar

Campo	Significado
`amount`	Valor a pagar. Em cobranças com vencimento já inclui juros, multa e descontos
`is_amount_fixed`	`true` = o valor não pode ser alterado. `false` = você escolhe o valor
`recipient_name` / `recipient_city`	Quem vai receber — confira antes de pagar
`psp_name`	Banco/instituição de destino, extraído do próprio código (tag 27). Ex.: `PagSeguro (PagBank)`. Se a instituição não for conhecida, o nome é derivado da própria identificação do código — nunca inventamos um banco
`txid`	Identificador da cobrança (útil para conciliação)
`status`	`ATIVA` = pagável. Outros valores indicam QR já pago, removido ou expirado
`type`	`ESTATICO`, `COBRANCA_IMEDIATA` ou `COBRANCA_COM_VENCIMENTO`

Exemplo completo com cURL

cURL

# 1. (Opcional) Consultar o código para conferir
curl -X POST "https://ajnapay.com.br/api/v1/pix/parse-copypaste" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"emv": "00020126580014br.gov.bcb.pix..."}'

# 2. Pagar (o código vai direto para a liquidação)
curl -X POST "https://ajnapay.com.br/api/v1/request-payments" \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "payment_type": "pix_copypaste",
    "amount": "2.02",
    "pix_copy_paste": "00020126580014br.gov.bcb.pix...",
    "description": "Pagamento de fatura"
  }'

4. Resposta

A API retorna os dados do pagamento criado:

Response 201 Created

{
  "success": true,
  "data": {
    "id": "uuid-do-pagamento",
    "amount": "250.00",
    "status": "pending_approval",
    "pix_key": "joao@exemplo.com",
    "description": "Pagamento de serviço",
    "created_at": "2026-07-21T10:30:00Z"
  }
}

5. Status do Pagamento

Status	Descrição
pending_approval	Aguardando aprovação
processing	Em processamento
completed	Pagamento realizado com sucesso
failed	Pagamento falhou
cancelled	Pagamento cancelado

6. Consultando Pagamentos

Listar Pagamentos

POST /api/v1/request-payments/list

Ver Detalhes

GET /api/v1/request-payments/{id}

Anterior: PIX Automático Próximo: Webhooks