README

SDK de integração com Vindi (Bills, Pix, Cartão de Crédito e Boleto) seguindo padrão do pacote eRede OAuth.

Funcionalidades

Este SDK possui as seguintes funcionalidades:

Criação de faturas (Bills) com item de produto
Pix: geração de cobrança, renderização de QR Code, consulta de status
Cartão de crédito: tokenização (public API), criação de perfil e cobrança
Boleto: emissão, extração de linha digitável/código de barras e consulta
Mapeamento de status de pagamento e parser de webhook de liquidação

Requisitos

PHP >= 8.1
Guzzle HTTP

Instalação

Via Composer

O pacote será publicado no Packagist. Por enquanto, utilize o repositório local ou Git.

composer require devsitarget/sdk-vindi-php

Configuração

Credenciais e Ambiente

Configure a loja com chave pública/privada da Vindi e ambiente:

<?php
use VindiSdk\Environment;
use VindiSdk\Store;
use VindiSdk\Vindi;

$env = Environment::sandbox(); // ou Environment::production()
$store = new Store('PUBLIC_KEY', 'PRIVATE_KEY', $env);

// ID do produto configurado no painel Vindi
$productId = 363801;

$vindi = new Vindi($store, $productId);

Uso Básico

Pix: gerar cobrança

<?php
use VindiSdk\Customer;
use VindiSdk\Address;
use VindiSdk\Pix\PixRequest;

$customer = new Customer(
  id: '123', name: 'Cliente', email: 'cliente@ex.com',
  document: '12345678900', phone: '11999999999',
  address: new Address('Rua A', '100', '01234-567', 'Centro', 'São Paulo', 'SP')
);

$req = new PixRequest(amount: 100.0, currency: 'BRL', customer: $customer, description: 'PIX Pedido 123');
$res = $vindi->createPixCharge($req);

// $res->qrCode contém SVG, $res->pixCopyPaste contém payload COPIA E COLA

Cartão de Crédito

<?php
use VindiSdk\CreditCard\CreditCard;
use VindiSdk\CreditCard\CreditCardRequest;

$card = new CreditCard(
  number: '4111111111111111', holderName: 'Cliente', expirationMonth: '12', expirationYear: '2028', securityCode: '123', brand: 'visa'
);

$ccReq = new CreditCardRequest(
  amount: 150.0,
  currency: 'BRL',
  customer: $customer,
  creditCard: $card,
  installments: 1,
  description: 'Pedido 456'
);

$ccRes = $vindi->createCreditCardPayment($ccReq);

Boleto

<?php
use DateTime;
use VindiSdk\Bank\BankRequest;

$due = new DateTime('+3 days');
$bankReq = new BankRequest(
  amount: 200.0,
  currency: 'BRL',
  customer: $customer,
  description: 'Pedido 789',
  dueDate: $due,
  number: 'BOL789'
);

$bankRes = $vindi->generateBank($bankReq);
// $bankRes->digitableLine, $bankRes->barCode, $bankRes->url

Consultar Status

<?php
$status = $vindi->checkPaymentStatus($res->tid);

Webhook de Liquidação

<?php
$parsed = Vindi::parseSettlementWebhook($payload);
// ['tid', 'transactionId', 'paymentMethodCode', 'statusCode', 'lowDate', 'occurrenceDate']

Split de Pagamento (bill_affiliates)

Para dividir o valor da fatura entre afiliados, adicione bill_affiliates ao payload automaticamente via objetos BillAffiliate nas requisições.

amount_type: 2 = porcentagem, 1 = valor fixo

<?php
use VindiSdk\BillAffiliate;

$affiliates = [
    new BillAffiliate(affiliateId: 2425, amount: 50.0, amountType: 2), // 50%
    new BillAffiliate(affiliateId: 3000, amount: 10.0, amountType: 1), // R$ 10,00
];

// PIX
$pixReq = new \VindiSdk\Pix\PixRequest(
    amount: 100.0,
    currency: 'BRL',
    customer: $customer,
    description: 'PIX com split',
    affiliates: $affiliates
);
$pixRes = $vindi->createPixCharge($pixReq);

// Cartão
$ccReq = new \VindiSdk\CreditCard\CreditCardRequest(
    amount: 150.0,
    currency: 'BRL',
    customer: $customer,
    creditCard: $card,
    installments: 1,
    description: 'Cartão com split',
    affiliates: $affiliates
);
$ccRes = $vindi->createCreditCardPayment($ccReq);

// Boleto
$bankReq = new \VindiSdk\Bank\BankRequest(
    amount: 200.0,
    currency: 'BRL',
    customer: $customer,
    description: 'Boleto com split',
    dueDate: new DateTime('+3 days'),
    number: 'BOL123',
    affiliates: $affiliates
);
$bankRes = $vindi->generateBank($bankReq);

Observações:

O SDK não valida somatórios; garanta que percentuais/valores respeitam as regras do seu negócio.
processInstallmentPayment preserva affiliates do pedido original.
processTokenPayment também aceita affiliates e description.

Testes

Crie o arquivo .env a partir do exemplo:

cp env.example .env

Edite o arquivo .env com suas credenciais de sandbox:

VINDI_PUBLIC_KEY=seu_public_key
VINDI_PRIVATE_KEY=seu_private_key
VINDI_ENVIRONMENT=sandbox
VINDI_PRODUCT_ID=363801

Execute os testes:

composer install
composer test

Nota: O arquivo .env é utilizado apenas nos testes de integração.

Comandos Disponíveis

composer test - Executa os testes
composer phpstan - Análise estática
composer cs-check - Verificação PSR-12
composer cs-fix - Correções PSR-12

Desenvolvimento

Estrutura do Projeto

vindi-sdk/
├── src/
│   └── Vindi/
│       ├── Environment.php
│       ├── Store.php
│       ├── PaymentStatus.php
│       ├── VindiBaseClient.php
│       ├── Vindi.php
│       ├── Pix/
│       ├── CreditCard/
│       └── Bank/
├── tests/
│   └── Unit/
├── composer.json
├── phpunit.xml
├── env.example
└── README.md

Padrões de Código

PSR-4 para autoload
Injeção de dependência (Guzzle Client)
Testes unitários com mock de HTTP

Licença

MIT

devsitarget / sdk-vindi-php

Maintainers

Details