Skip to content

v2.8.0 — Inter, o primeiro banco

Latest

Choose a tag to compare

@mariolucasdev mariolucasdev released this 25 Oct 01:45
· 11 commits to develop since this release
60160b4

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 chama pix na 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 ambiente

A 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 valor enquanto a capacidade
    promete que valor ausente estorna integral, e a chamada é endereçada pelo
    endToEndId do 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