README

SDK PHP server-side para criar links do Checkout Integrado e confirmar pagamentos da InfinitePay sem receber dados de cartão no seu sistema.

Este projeto é um SDK comunitário e não oficial. A integração usa o checkout hospedado da InfinitePay.

Por que este package existe?

A API do Checkout Integrado da InfinitePay é simples, mas uma integração de pagamento segura envolve mais do que enviar uma requisição HTTP. Cada projeto precisaria implementar novamente validação de valores, serialização do payload, tratamento de erros, timeouts, verificação TLS e confirmação de webhooks.

Este package concentra essas responsabilidades em uma API PHP pequena e tipada. A aplicação cria o pedido no backend, envia somente os dados necessários para a InfinitePay e recebe uma URL de checkout hospedado. Os dados de cartão são preenchidos diretamente no ambiente da InfinitePay e nunca passam pelo servidor ou pelo frontend da loja.

Ele também resolve um ponto importante da integração: um webhook ou os parâmetros recebidos na URL de retorno não devem ser considerados prova de pagamento. O SDK permite reconciliar a notificação com o pedido salvo e consultar o endpoint payment_check antes de liberar um produto ou serviço.

Por que usar?

• Menos código repetido: criação de links, consulta de pagamentos e leitura de webhooks usam objetos prontos e reutilizáveis.
• Valores monetários seguros: os preços são inteiros em centavos, evitando erros de arredondamento causados por float.
• Validação antes da requisição: itens, InfiniteTag, cliente, endereço, URLs e identificadores são validados antes de chegar à API.
• Webhook reconciliado: pedido e valor são comparados com os dados locais e o pagamento é confirmado server-to-server.
• Transporte protegido: TLS é verificado, redirects não são seguidos e existem limites de tempo e tamanho de resposta.
• Erros previsíveis: falhas de validação, comunicação e respostas da API possuem exceções separadas.
• Fácil de testar: o transporte HTTP pode ser substituído por uma implementação simulada, sem criar cobranças reais nos testes.
• Independente de framework: pode ser usado em PHP puro, Laravel, Symfony ou qualquer projeto com Composer.

O package reduz erros comuns e oferece uma base consistente, mas não substitui as responsabilidades da aplicação. O sistema consumidor ainda deve autenticar o comprador, carregar produtos e preços do banco, proteger a rota contra abuso e processar cada transaction_nsu de forma idempotente.

Requisitos

• PHP 8.1 ou superior
• extensoes curl, json e mbstring
• Checkout Integrado habilitado na conta InfinitePay

Instalacao

Enquanto o pacote ainda nao estiver publicado no Packagist, adicione o repositorio ao projeto consumidor:

{
  "repositories": [
    { "type": "vcs", "url": "https://github.com/odinizfilho/infinitepay-php" }
  ],
  "require": {
    "odinizfilho/infinitepay-php": "dev-main"
  }
}

Depois execute composer update odinizfilho/infinitepay-php.

Criar um checkout

Este codigo deve rodar em uma rota do backend. O frontend recebe somente a URL pronta do checkout; valores e itens devem sempre vir do banco de dados, nunca do corpo enviado pelo navegador.

<?php

use InfinitePay\CheckoutRequest;
use InfinitePay\InfinitePayClient;
use InfinitePay\Value\Customer;
use InfinitePay\Value\Item;

require __DIR__ . '/vendor/autoload.php';

// Pode vir de INFINITEPAY_HANDLE no ambiente. Nunca aceite a handle do request.
$client = new InfinitePayClient($_ENV['INFINITEPAY_HANDLE']);

// Busque o pedido autenticado no banco e recalcule o total no servidor.
$order = $orders->findForCustomer($orderId, $authenticatedCustomerId);

$checkout = new CheckoutRequest(
    items: array_map(
        fn ($line) => new Item($line->name, $line->unitPriceInCents, $line->quantity),
        $order->lines,
    ),
    orderNsu: (string) $order->publicId,
    redirectUrl: 'https://loja.example.com/pagamento/retorno',
    webhookUrl: 'https://loja.example.com/webhooks/infinitepay',
    customer: new Customer($order->customerName, $order->customerEmail, $order->customerPhone),
);

$link = $client->createPaymentLink($checkout);

// Em uma API JSON: devolva $link->url. Em MVC: emita um redirect 303.
header('Location: ' . $link->url, true, 303);

price e sempre um inteiro em centavos: R$ 10,00 deve ser 1000. Nao use float para dinheiro.

Webhook seguro

A documentacao publica da InfinitePay nao informa uma assinatura criptografica para o webhook. Por isso, receber um POST nao e prova de pagamento. O metodo verifyWebhook() compara pedido e valor locais e confirma a transacao diretamente na API antes de retornar sucesso.

<?php

use InfinitePay\InfinitePayClient;
use InfinitePay\WebhookEvent;

$rawBody = file_get_contents('php://input');
$event = WebhookEvent::fromJson($rawBody === false ? '' : $rawBody);

// Localize o pedido somente pelo identificador; ainda nao altere seu status.
$order = $orders->findByPublicId($event->reference->orderNsu);
if ($order === null) {
    http_response_code(400);
    exit;
}

// Consulta /payment_check e exige paid=true e o mesmo valor do pedido local.
$status = $client->verifyWebhook(
    event: $event,
    expectedOrderNsu: (string) $order->publicId,
    expectedAmount: $order->totalInCents,
);

// Use transaction_nsu como chave UNIQUE e atualize de forma idempotente/transacional.
$orders->markPaidOnce($order->id, $event->reference->transactionNsu, $status);

http_response_code(200);

Capture ValidationException, ApiException e TransportException no controller. Responda 400 para payload invalido e 500/503 quando a confirmacao remota falhar, para que a InfinitePay possa tentar novamente.

Conferir o retorno do navegador

Parametros de redirect_url tambem nao sao prova de pagamento. Construa uma PaymentReference e consulte a API no backend:

use InfinitePay\PaymentReference;

$reference = new PaymentReference(
    orderNsu: (string) $_GET['order_nsu'],
    transactionNsu: (string) $_GET['transaction_nsu'],
    slug: (string) $_GET['slug'],
);

$status = $client->checkPayment($reference);

Antes de exibir o resultado, confira que order_nsu pertence ao usuario autenticado e que paid, success e amount correspondem ao pedido salvo.

Checklist de producao

• Nunca envie handle, itens internos, logica de preco ou chamada a payment_check pelo JavaScript do navegador.
• Nunca colete numero, CVV ou validade de cartao; redirecione ao checkout hospedado.
• Derive itens e total do banco no backend; nao confie em preco enviado pelo cliente.
• Use HTTPS, CSRF e autenticacao na rota que cria o checkout.
• Use um order_nsu aleatorio ou nao enumeravel e limite tentativas por IP/usuario.
• Torne transaction_nsu unico no banco e processe webhooks de forma idempotente.
• Nao registre dados pessoais, payload completo de cliente ou respostas integrais em logs.
• Responda rapidamente ao webhook; se o processamento posterior for pesado, confirme e enfileire-o.
• Mantenha dependencias atualizadas e rode composer audit no CI.

Testes

composer install
composer test

Os testes nao fazem chamadas reais nem geram cobrancas.

Referencia da API

• Documentacao do Checkout Integrado
• Central de Ajuda InfinitePay