Repository navigation
Décimo gateway, e o primeiro de um banco.
Inter
A API Pix do Inter é a especificação do BACEN quase literal: mesmos
caminhos, mesmos schemas, mesma taxonomia de erro. Isso encolheu o trabalho — é
o mesmo terreno da API Pix da Efí.
use PHPay\Http\Certificate;
use PHPay\Inter\InterGateway;
use PHPay\Support\{Customer, Money};
$gateway = new InterGateway(
CLIENT_ID,
CLIENT_SECRET,
certificate: Certificate::pair('/caminho/certificado.crt', '/caminho/chave.key'),
);
$cobranca = $gateway->charge()
->setKey(PIX_KEY)
->setAmount(Money::reais('110,00'))
->setCustomer(Customer::make('Fulano de Teste', '12345678901'))
->create();| Capacidade | |
|---|---|
SupportsCharges |
cobrança Pix, imediata (cob) e com vencimento (cobv) |
SupportsWebhooks |
um por chave Pix, como a Efí |
SupportsWebhookEvents |
leitura da notificação |
charge() é a cobrança Pix — na Efí charge() é o boleto —, porque o
boleto do Inter é outra API (/cobranca/v3) que esta versão não fala.
A notificação diverge do padrão em dois pontos
E os dois falham em silêncio, por isso vale saber antes de integrar.
O corpo é um array na raiz, não o {"pix": [...]} que o BACEN manda e que a
Efí entrega:
[{ "endToEndId": "E876...", "txid": "9711...", "valor": "110.00", "horario": "..." }]Um parser escrito pela especificação não acharia a chave pix e devolveria
zero eventos para todo pagamento de verdade, sem erro nenhum. O
webhookEvents() lê as duas formas.
devolucoes é um objeto, onde o padrão manda array. Pode ser erro de
documentação deles, então as duas leituras passam: lista continua lista, objeto
vira lista de um.
Correção, publicada depois: estas notas diziam que o Inter acrescenta
/pixà URL do webhook. Não acrescenta — a notificação chega na URL que
você cadastrou. A afirmação veio de uma leitura errada da expressão
{$request.body#/webhookUrl/pix}que o Redoc mostra na referência: o callback
se chamapixna especificação e o renderizador juntou o nome à expressão.
O sufixo/pixé quirk documentado do Itaú, não do Inter. O código nunca
esteve errado — a biblioteca manda a URL como você passou.
O certificado vem em dois arquivos
O Inter entrega um .crt e um .key, e a documentação dele manda juntar com
openssl pkcs12 -export antes de usar. Não precisa: o cURL aceita as
metades como vêm.
Certificate::pair($crt, $key, $senha); // de arquivo
Certificate::pairFromBase64($crtB64, $keyB64, $senha); // de variável de ambienteA opção "sem mudança no core" custava mais do que parecia: o .pfx que aquele
comando gera era recusado pelo próprio Certificate, porque o Guzzle não
reconhece essa extensão — então o usuário convertia e ainda precisava renomear.
Num par a senha vai na chave, nunca no certificado. O Guzzle transforma o
segundo elemento de cert em CURLOPT_SSLCERTPASSWD, e o .crt é público:
não tem o que decifrar. Verificado contra um servidor que exige certificado de
cliente, nos três caminhos do par e no .p12 de controle.
O .gitignore passou a cobrir *.crt, *.cer e *.key. Chave privada
commitada não se desfaz com um revert.
O token é emitido por escopo
Primeiro gateway assim. scope é obrigatório e não existe token que carregue
todas as permissões, então o gateway pede a união do que as capacidades usam —
pedir escopo que a aplicação não tem reprova a requisição inteira.
O cache não é otimização: gerar token é limitado a 5 chamadas por minuto,
e a documentação manda reaproveitar pela hora de validade. Pedir por requisição
levaria 429 na sexta.
O que o Inter não declara, e por quê
- estorno existe na API, mas o schema exige
valorenquanto a capacidade
promete que valor ausente estorna integral, e a chamada é endereçada pelo
endToEndIddo pagamento — mesma razão da Efí, então fica em
charge()->refund(); - assinatura de webhook: a notificação vem por mTLS, que o certificado já
cobre. Não existe esquema para verificar; - chaves Pix: a API não tem endpoint de DICT. A chave que endereça o webhook
é uma que você já tem; - clientes e assinaturas não existem na API.
Três coisas que a referência descreve e o gateway não serve, conferidas na
lista de operações: gestão de chave Pix, /loc/{id}/qrcode — o copia-e-cola
volta na própria cobrança — e a listagem de webhooks. A taxonomia de erros
menciona um GET /webhook, mas aquela seção é o texto do BACEN copiado inteiro.
Compatibilidade
Só entraram métodos novos; nenhuma assinatura existente mudou. A tabela de
capacidades do README ganhou as colunas de estorno e leitura de webhook, que
faltavam desde que as duas entraram.
Nada do Inter foi exercitado contra o sandbox dele: a forma dos payloads veio da
referência, e a suíte não sai para a rede.
Documentação: Inter ·
Certificado e mTLS