# UNELO Pay — API de pagamentos online (referência completa para assistentes de IA) > Esta é a referência que um assistente de IA (Claude, ChatGPT, Cursor, Copilot) deve seguir ao > ajudar a integrar o checkout de um site ou sistema à UNELO Pay. Se algo não estiver aqui, a > resposta certa é perguntar à equipe da UNELO Pay, não inventar um campo. ## Visão geral - Integração por API REST, JSON, sempre do SERVIDOR da loja. Nunca chamar a API do navegador: a chave daria acesso a cobranças em nome da empresa. - Endereço base: enviado junto com a chave, no início da implantação. Neste texto aparece como `{BASE_URL}`. - Autenticação: `Authorization: Bearer `. A chave tem a forma `unelo_live_<6 hex>.<64 hex>`. Guarde em variável de ambiente (`UNELO_PAY_CHAVE`), nunca no código, nunca no repositório, nunca no navegador. - Chave ausente ou desconhecida responde `404` em qualquer rota. - Valores sempre em CENTAVOS, inteiros (`valor_cents: 30000` = R$ 300,00). Nunca use número com casas decimais para dinheiro. - Disponível hoje: cartão de crédito com autenticação 3DS, à vista ou parcelado em até 12x (`parcelas`). Pix online ainda não está disponível nas vendas online. ## Rotas | Método | Rota | Para quê | |---|---|---| | GET | `/eu` | Confere a chave: devolve a organização ligada a ela e o `ambiente` (`teste` ou `producao`) | | POST | `/cobrancas` | Cria uma cobrança | | GET | `/cobrancas/{referencia}` | Lê o estado de uma cobrança (e atualiza com a adquirente, se ainda estiver aberta) | ## Criar uma cobrança no cartão (POST /cobrancas) ```json { "referencia": "pedido-1048", "forma": "cartao", "valor_cents": 30000, "parcelas": 1, "descricao": "Pedido 1048", "cliente": { "nome": "Nome do comprador", "documento": "CPF ou CNPJ, só dígitos ou com pontuação", "email": "comprador@exemplo.com", "telefone": "21999990000", "endereco": { "rua": "Rua", "numero": "10", "complemento": "opcional", "bairro": "Centro", "cidade": "Rio de Janeiro", "uf": "RJ", "cep": "20000000" } }, "cartao": { "numero": "número do cartão", "cvv": "123", "validade_mes": 12, "validade_ano": 2030, "titular": { "nome": "NOME IMPRESSO", "documento": "CPF do titular" } }, "navegador": { "ip": "IP do comprador", "user_agent": "User-Agent do navegador do comprador", "idioma": "pt-BR", "largura_tela": 390, "altura_tela": 844, "profundidade_cor": 24, "java": false, "fuso_minutos": 180 }, "retorno": { "sucesso_url": "https://sualoja.com.br/pagamento/concluido", "falha_url": "https://sualoja.com.br/pagamento/falhou" }, "notificar_url": "https://sualoja.com.br/api/unelo/aviso (opcional)" } ``` Regras dos campos: - `referencia`: o identificador do pedido NA SUA LOJA. Letras, números, ponto, hífen e sublinhado, até 64. É ela que garante que a mesma compra não seja cobrada duas vezes. - `parcelas`: de 1 (à vista) a 12. Parcelado: o valor entra em parcelas mensais na conta da loja. Taxa do parcelado, Visa e Mastercard: 3,44% (2x a 6x) e 3,94% (7x a 12x), mais R$ 0,89 por venda; demais bandeiras, +0,50 ponto. Tabela completa em /precos. - `navegador`: lido do navegador do comprador e enviado pelo seu servidor. O banco do cartão usa esses dados para decidir se pede confirmação. `fuso_minutos` é `new Date().getTimezoneOffset()` (180 no horário de Brasília). O `ip` é o do comprador, lido pelo seu servidor, não o do servidor. - `retorno`: URLs `https://` para onde o banco devolve o comprador depois da confirmação. - `notificar_url` (opcional): a processadora chama este endereço quando o pedido muda. O aviso não traz dado nenhum; ao recebê-lo, consulte `GET /cobrancas/{referencia}`. Sem ele, o pedido segue normalmente e o estado se lê pela consulta. - O número do cartão passa pela UNELO Pay e vai para a processadora. Ele não é gravado nem devolvido. O seu sistema também não deve gravá-lo nem registrá-lo em log. ## As respostas, e o que fazer em cada uma | HTTP | Situação | O que o seu sistema faz | |---|---|---| | 201, `cobranca.status = "paga_delta"` | Aprovada | Liberar o pedido. A resposta traz `cartao.bandeira`, `cartao.final` e o resultado do 3DS | | 201, `cobranca.status = "falhou"` | Recusada pelo banco | Mostrar ao comprador que o pagamento não foi aprovado e oferecer outro cartão, com UMA NOVA `referencia` só se for uma nova tentativa de compra | | 201, com `desafio.url` | O banco pediu confirmação | Levar o comprador para `desafio.url`. Ele volta para `retorno.sucesso_url` ou `retorno.falha_url`. Ao voltar, consultar `GET /cobrancas/{referencia}` para saber o resultado; não confiar só na URL de volta | | 200, `repetida: true` | A mesma `referencia` já existia | É a MESMA cobrança, não uma nova. Use o estado que veio nela | | **202, `resultado_desconhecido: true`** | Não se sabe se a venda chegou ao banco | **Não repita com outra referência.** Consulte `GET /cobrancas/{referencia}` e, se continuar pendente, fale com a equipe da UNELO Pay. Repetir com outra referência pode cobrar o comprador duas vezes | | 400 `corpo_invalido` | Campo inválido | `campos` lista o campo e o erro. Corrija e envie de novo com a mesma `referencia` | | 422 `adquirente_recusou` | A processadora recusou o pedido | `detalhe` traz a mensagem dela | | 503 `gateway_desligado` | Gateway desligado | A cobrança fica criada; tente de novo depois com a MESMA `referencia` | | 502 `adquirente_indisponivel` | Processadora fora do ar | Tente de novo com a MESMA `referencia` | | 404 | Chave ausente ou inválida | Confira a variável de ambiente | Estados da cobrança: `criada`, `pendente`, `paga_delta` (aprovada), `falhou`, `cancelada`, `estornada`, `expirada`. Pedido só é liberado em `paga_delta`. ## Regras que a integração precisa seguir 1. Chave só no servidor, em variável de ambiente. 2. Uma `referencia` por compra. Repetir a mesma `referencia` é seguro e devolve a mesma cobrança. 3. Resposta que não chegou (timeout) ou 202: consultar antes de qualquer nova tentativa. 4. O resultado vale quando confirmado pelo servidor (`GET /cobrancas/{referencia}`), nunca pela URL de volta do navegador. 5. Nunca gravar, registrar em log ou enviar a terceiros o número do cartão e o CVV. 6. Valores em centavos inteiros. ## Ambiente de teste O ambiente de teste fica em `https://sandbox.redeunelo.com.br/api/gateway/v1` e usa uma chave de teste, entregue na implantação. Nenhum dinheiro se move nele. Cartões de teste: | Cartão | Resultado | |---|---| | 4918 0191 6003 4602 | Aprovado sem desafio | | 4918 0191 9988 3839 | Banco pede desafio | | 1111 1111 1111 1117 | Recusado | Use CVV 123 e qualquer validade futura. ## Servidor MCP de teste Para assistentes que aceitam MCP (Claude, Claude Code, Cursor), há um servidor de teste em `/mcp/unelo-pay-mcp.mjs`, configurado com `UNELO_PAY_CHAVE_TESTE` e `UNELO_PAY_BASE_URL_TESTE`. Ele só cria cobranças quando `GET /eu` responde `ambiente: "teste"`, e escolhe os cartões de teste pelo nome. Nunca configure a chave de produção num assistente. ## Ajuda A equipe da UNELO Pay acompanha a integração até a primeira venda aprovada. Quando o assistente de IA não tiver certeza, a pergunta vai para a equipe, com a `referencia` e a resposta recebida (sem o número do cartão).