API v1 - PIX Cobranca e Saque

Documentacao direta para integracao com API key por usuario, cobranca PIX e saque PIX.

Base URL: https://aifampay.com.br/api/v1

Ambiente com prefixo /pay usa a mesma base quando APP_URL esta configurado como http://localhost/pay: https://aifampay.com.br/api/v1

Gerar API Key OpenAPI Postman

Inicio rapido

Gere uma API Key no painel: https://aifampay.com.br/painel/integracoes.
Headers para endpoints protegidos: Content-Type: application/json e X-Api-Key: SUA_CHAVE.
Compatibilidade: tambem aceitamos Authorization: Bearer SUA_CHAVE com o mesmo token, mas o header oficial e X-Api-Key.
Idempotencia (opcional): envie X-Idempotency-Key para evitar duplicidade em POST /charges e POST /withdrawals.
Rate limit: 60 req/min por API key (HTTP 429).
GET /api/v1/ping e publico (sem API key).

Autenticacao

Os endpoints protegidos exigem X-Api-Key. O endpoint /ping e publico.

Se a sua stack preferir Bearer token, o backend tambem aceita Authorization: Bearer SUA_CHAVE. Para integracao externa, a rota oficial continua sendo /api/v1.

curl -X GET https://aifampay.com.br/api/v1/ping

Criar uma cobranca

POST /api/v1/charges

Campos principais (JSON)

Campo	Descricao	Obrigatorio
valor	Valor em centavos (ex.: 1000 = R$10,00)	Obrigatorio
cliente	Objeto com nome, email e cpf do pagador	Obrigatorio
cliente.telefone	Telefone do pagador	Opcional
moeda	Padrao BRL quando omitido	Opcional
descricao	Texto livre (ate 255)	Opcional
callback	URL para callback imediato	Obrigatorio
metodos	Lista; atualmente use `["pix"]`	Opcional

Obs.: se metodos nao for enviado, o sistema usa pix como padrao. cliente.cpf deve ser um CPF valido com 11 digitos numericos e callback e obrigatorio.

curl -X POST https://aifampay.com.br/api/v1/charges \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: SUA_CHAVE" \
  -H "X-Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000" \
  -d '{
    "valor": 2500,
    "cliente": {
      "nome": "Maria Souza",
      "email": "maria@email.com",
      "cpf": "12345678909",
      "telefone": "11999999999"
    },
    "moeda": "BRL",
    "descricao": "Pedido #123",
    "callback": "https://sualoja.com/webhook/pagamento",
    "metodos": ["pix"]
  }'

Resposta (200/201)

{
  "id": 42,
  "status": "pendente",
  "valor": 2500,
  "moeda": "BRL",
  "metodo": "pix",
  "descricao": "Pedido #123",
  "cliente": {
    "nome": "Maria Souza",
    "email": "maria@email.com",
    "cpf": "12345678909"
  },
  "callback_url": "https://sualoja.com/webhook/pagamento",
  "idempotency": "123e4567-e89b-12d3-a456-426614174000",
  "referencia": "ch_a1b2c3d4",
  "gateway": {
    "qr_code": "00020101021226...6304C116",
    "qr_code_url": "https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=000201...",
    "expira_em": "2026-12-31 23:59:59"
  },
  "criado_em": "2026-03-26 10:00:00",
  "atualizado_em": "2026-03-26 10:00:00"
}

gateway.expira_em e retornado pela plataforma. A API publica nao recebe campo de vencimento na criacao da cobranca.

Exemplo em PHP

$body = [
  "valor" => 2500,
  "cliente" => [
    "nome" => "Maria Souza",
    "email" => "maria@email.com",
    "cpf" => "12345678909"
  ],
  "moeda" => "BRL",
  "descricao" => "Pedido #123",
  "callback" => "https://sualoja.com/webhook/pagamento",
  "metodos" => ["pix"]
];

$ch = curl_init("https://aifampay.com.br/api/v1/charges");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Api-Key: SUA_CHAVE",
    "X-Idempotency-Key: ch_".uniqid()
  ],
  CURLOPT_POSTFIELDS => json_encode($body)
]);
$resp = curl_exec($ch);
curl_close($ch);
echo $resp;

Consultar cobranca

GET /api/v1/charges/{id}

curl -X GET https://aifampay.com.br/api/v1/charges/42 \
  -H "X-Api-Key: SUA_CHAVE"

Resposta: mesma estrutura da criacao (inclui gateway e status atual).

Transferencia / Saque PIX

POST /api/v1/withdrawals

Campos principais (JSON)

Campo	Descricao	Obrigatorio
valor	Valor em centavos (ex.: 1000 = R$10,00)	Obrigatorio
pix_chave	Chave PIX do destinatario	Obrigatorio
pix_tipo	cpf, cnpj, email, celular, aleatoria	Obrigatorio
cliente	Objeto com nome, email e cpf do solicitante	Obrigatorio
descricao	Texto livre (ate 255)	Opcional

curl -X POST https://aifampay.com.br/api/v1/withdrawals \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: SUA_CHAVE" \
  -d '{
    "valor": 1000,
    "pix_chave": "12345678909",
    "pix_tipo": "cpf",
    "descricao": "Saque do cliente",
    "cliente": {
      "nome": "Maria Souza",
      "email": "maria@email.com",
      "cpf": "12345678909"
    }
  }'

Resposta (201)

{
  "id": 91,
  "status": "processando",
  "valor": 1000,
  "moeda": "BRL",
  "metodo": "pix",
  "tipo": "pix",
  "pix_chave": "12345678909",
  "pix_tipo": "cpf",
  "referencia": "wd_a1b2c3d4",
  "gateway": {
    "status": "PROCESSANDO"
  },
  "cliente": {
    "nome": "Maria Souza",
    "email": "maria@email.com",
    "cpf": "12345678909"
  }
}

Saldo da conta

Endpoint planejado para a API v1. No backend atual, o saldo pode ser consultado via API interna em /api/extrato.

Smoke test controlado

Para validar cobranca PIX real sem executar saque, use o comando abaixo com uma API key de teste.

Antes de rodar, configure as credenciais do ambiente de teste e uma API key de usuario de teste.

RUN_REAL_ACQUIRER_TESTS=true php artisan gateway:smoke-real --charge \
  --base-url=https://aifampay.com.br/api/v1 \
  --api-key=SUA_CHAVE \
  --amount-centavos=100

O comando cria cobranca, valida QR Code, consulta a cobranca e testa idempotencia. Saque real nao e executado por seguranca.

Webhooks

Configure sua URL de webhook no painel ou envie callback ao criar cobranca.

{
  "id": 42,
  "status": "pago",
  "valor": 2500,
  "moeda": "BRL",
  "metodo": "pix",
  "descricao": "Pedido #123",
  "referencia": "ch_a1b2c3d4",
  "pago_em": "2026-03-26 10:05:10",
  "falhou_em": null,
  "estornado_em": null
}

Erros comuns

401 API key invalida ou ausente (endpoints protegidos).
422 Validacao: campos obrigatorios, valor <= 0, URL invalida, CPF invalido.
429 Rate limit excedido.