PHPackages vitorccs/maxipago-php-sdk - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. vitorccs/maxipago-php-sdk ActiveLibrary vitorccs/maxipago-php-sdk ========================= SDK em PHP para API Maxipago v1.4.1(2mo ago)0691GPL-3.0PHPPHP >=8.1CI passing Since Jun 26Pushed 2mo ago1 watchersCompare [ Source](https://github.com/vitorccs/maxipago-php-sdk)[ Packagist](https://packagist.org/packages/vitorccs/maxipago-php-sdk)[ Docs](https://github.com/vitorccs/maxipago-php-sdk)[ RSS](/packages/vitorccs-maxipago-php-sdk/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (6)Dependencies (8)Versions (7)Used By (0) Maxipago - SDK PHP ================== [](#maxipago---sdk-php) SDK em PHP para API Maxipago Requisitos ---------- [](#requisitos) - PHP >= 8.1 Descrição --------- [](#descrição) SDK em PHP para a [API Maxipago](https://www.maxipago.com/developers/apidocs/). Instalação ---------- [](#instalação) Via Composer ``` composer require vitorccs/maxipago-php-sdk ``` Parâmetros ---------- [](#parâmetros) ParâmetroObrigatórioPadrãoComentárioMAXIPAGO\_MERCHANT\_IDSimnullMerchant ID para autenticaçãoMAXIPAGO\_MERCHANT\_KEYSimnullMerchant Key para autenticaçãoMAXIPAGO\_SANDBOXNãofalseHabilita o modo SandboxMAXIPAGO\_TIMEOUTNão30Timeout em segundos para estabelecer conexão com a APIPodem ser definidos por variáveis de ambiente: ``` # Em um arquivo .env do seu projeto: MAXIPAGO_MERCHANT_ID=myMerchantId MAXIPAGO_MERCHANT_KEY=myMerchantKey MAXIPAGO_SANDBOX=true MAXIPAGO_TIMEOUT=60 ``` Ou passados como argumentos do serviço: ``` use Vitorccs\Maxipago\Entities\Parameters; use Vitorccs\Maxipago\Http\SaleService; $parameters = new Parameters( 'myMerchantId', 'myMerchantKey', true, // modo sandbox 60 // timeout ); $saleService = new SaleService($parameters); ``` Serviços implementados ---------------------- [](#serviços-implementados) ``` # inicia os serviços de transação e consulta use Vitorccs\Maxipago\Http\CustomerService; use Vitorccs\Maxipago\Http\QueryService; use Vitorccs\Maxipago\Http\SaleService; $customerService = new CustomerService(); $saleService = new SaleService(); $queryService = new QueryService(); ``` ### Criar Cliente [](#criar-cliente) ``` // Nota: utilize CustomerBuilder (descrito mais abaixo na documentação) // para gerar facilmente o objeto $customer $response = $customerService->create($customer); ``` ### Realizar Pedido [](#realizar-pedido) ``` // Nota: utilize os Builders (descrito mais abaixo na documentação) // para gerar facilmente o objeto $sale // para Pix $response = $saleService->createPixSale($sale); // para Boleto $response = $saleService->createBoletoSale($sale); // para Cartão de Crédito $response = $saleService->createCreditCardSale($sale); ``` ### Consultar Pedido [](#consultar-pedido) Pode-se obter a transação por qualquer um destes critérios ``` // retorna todas as transações do pedido (array) $response = $queryService->getByOrderId('0A0104AB:018FAAE5F66A:FE79:5318D453'); // retorna apenas a transação mais atual (object) $response = $queryService->getLastByOrderId('0A0104AB:018FAAE5F66A:FE79:5318D453'); // retorna todas as transações com este reference number (array) $response = $queryService->getByReferenceNumber(221342); // retorna a transação com este ID (objeto) $response = $queryService->getByTransactionId(18390209); ``` ### Cancelar Pedido [](#cancelar-pedido) ``` // Nota: somente disponível para pedidos em aberto e para algumas // formas de pagamento (ex: Boleto e PIX) $response = $saleService->cancelSale($transactionId); ``` ### Estornar Pedido [](#estornar-pedido) ``` // Nota: todos os campos são obrigatórios. $chargeTotal = 100.00; $response = $saleService->refundSale($orderId, $referenceNumber, $chargeTotal); ``` ### Gerenciar Cartões de Crédito [](#gerenciar-cartões-de-crédito) ``` // Cadastra um cartão de crédito para um cliente // utilize preferencialmente CreditCardBuilder para gerar $creditCard $cardToken = $customerService->saveCard($creditCard); // você poderá remover o cartão chamando esse serviço // Obs: em caso de qualquer erro, é lançado exceção $customerService->deleteCard($customerId, $cardToken); ``` Construtores (Builders) ----------------------- [](#construtores-builders) Para auxiliar a criar uma Transação, foram disponibilizados alguns construtores: ### Criar Cliente [](#criar-cliente-1) ``` use Vitorccs\Maxipago\Enums\CustomerGender; $customer = CustomerBuilder::create('227.732.755-78', 'Joao', 'Silva') ->setPhone('11 91234-5678') ->setEmail('email@email.com') ->setGender(CustomerGender::M) ->setBirthDate(\Datetime::createFromFormat('Y-m-d', '1991-02-10')) ->get(); ``` ### Criar Pedido Boleto [](#criar-pedido-boleto) ``` use Vitorccs\Maxipago\Enums\Processor; use Vitorccs\Maxipago\Builders\BoletoSaleBuilder; use Vitorccs\Maxipago\Enums\CustomerType; use Vitorccs\Maxipago\Enums\BoletoChargeType; // Demonstrando os campos mais essenciais $expirationDate = '2024-10-01'; $pixSale = BoletoSaleBuilder::create(50.00, 'COD1002', $expirationDate) ->setProcessorId(Processor::BOLETO_ITAU_V2) // opcional ->setCustomerIdExt('227.732.755-78') ->createBilling( name: 'João Silva', cpfCnpj: '227.732.755-78', email: 'joao.silva@email.com', // opcional birthdate: '1980-10-25', // opcional customerType: CustomerType::Individual // opcional ) ->setBillingAddressFields( 'Rua Teste, 123', '4o andar', 'Bairro Teste', 'São Paulo', 'SP', '03456-000' ) ->setDiscount('2024-10-01', 5.00) // opcional ->setCharge('2024-12-03', BoletoChargeType::AMOUNT, 2.50) // opcional ->setInterestRate('2024-12-03', 1.10) // opcional ->get(); ``` ### Criar Pedido Cartão de Crédito [](#criar-pedido-cartão-de-crédito) ``` use Vitorccs\Maxipago\Builders\CustomerBuilder; use Vitorccs\Maxipago\Builders\CreditCardTokenSaleBuilder; use Vitorccs\Maxipago\Enums\Processor; // primeiro você deve cadastrar o cliente (guarde o ID do cliente) $customer = CustomerBuilder::create('409.289.289-11', 'João', 'Silva') ->setPhone('11 91234-5678') ->setEmail('email@email.com') ->get(); $customerId = $customerService->create($customer); // depois, você deve cadastrar o cartão de crédito dele (guarde o token) $cardNumber = '5555 5555 5555 5557'; $expMonth = 5; $expYear = 2033; $creditCard = CreditCardBuilder::create($customerId, $cardNumber, $expMonth, $expYear) ->setBillingEmail('email@email.com') ->get(); $cardToken = $customerService->saveCard($creditCard); // agora você cria a venda em cartão de crédito $creditCardSale = CreditCardTokenSaleBuilder::create($customerId, $cardToken, 'COD1003', 100.00) ->setProcessorId(Processor::REDE) ->setFraudCheck(Answer::N) ->createBilling( name: 'João Silva', cpfCnpj: '227.732.755-78' ) ->get(); // você também pode fazer a venda sem tokenizar o cartão $cardNumber = '5555 5555 5555 5557'; $expMonth = 5; $expYear = 2033; $cvvNumber = '444'; $creditCardSale = CreditCardSaleBuilder::create($cardNumber, $expMonth, $expYear, $cvvNumber, 'COD1003', 100.00) ->setProcessorId(Processor::REDE) ->setFraudCheck(Answer::N) ->createBilling( name: 'João Silva', cpfCnpj: '227.732.755-78' ) ->get(); ``` ### Criar Pedido PIX [](#criar-pedido-pix) ``` use Vitorccs\Maxipago\Enums\Processor; use Vitorccs\Maxipago\Builders\PixSaleBuilder; // Demonstrando os campos mais essenciais $pixExpiration = 82400; // em segundos $pixSale = PixSaleBuilder::create(30.00, 'COD1001', $pixExpiration) ->setPixPaymentInfo('Mensagem de agradecimento') // opcional ->createBilling( name: 'João Silva', cpfCnpj: '373.067.250-92' ) ->get(); ``` Tratamento de erros ------------------- [](#tratamento-de-erros) Esta biblioteca lança as exceções abaixo: **Principais:** - `MaxipagoValidationException` para erros diversos detectados pela API Maxipago, inclusive erros que impediram a Transação de ser criada (`errorCode` diferente de 0). - `MaxipagoRequestException` para as demais falhas não tratadas pela API, incluindo erros de servidor (HTTP 4xx ou 5xx) e de conexão (ex: timeout). - `MaxipagoInvalidBodyException` quando a requisição possui status de sucesso (HTTP 2xx) mas o corpo da resposta da API não contém um XML válido (ex: corpo vazio, XML com erro, texto puro, etc.). Ela herda a classe `MaxipagoRequestException` pois é igualmente um erro não tratado, e pode estar relacionado a falhas de infraestrutura. **No serviço de Criar Transação:** - `MaxipagoProcessorException` quando a Transação conseguiu ser criada pela Maxipago, mas há um erro de "processor" (`responseCode` diferente de 0). **No serviço de Consultar Transação:** - `MaxipagoNotFoundException` ao tentar localizar uma Transação que não existe (ex: localizar por OrderId ou TransactionId). Exemplo de corpo da resposta onde será lançado uma exceção `MaxipagoValidationException` ``` 1 Descrição do erro]]> ``` Exemplo de corpo da resposta onde será lançado uma exceção `MaxipagoProcessorException` ``` 0B0214CB:018A9C5B6ACA:DBCC:0344E731 15d71318-71f3-4312-96f8-741f082dd6e7 623999551 1716315187 1 400 Descrição do erro PIXITAU Descrição do erro ``` Exemplo de implementação ------------------------ [](#exemplo-de-implementação) ``` error_reporting(E_ALL); ini_set('display_errors', 1); require __DIR__.'/vendor/autoload.php'; putenv('MAXIPAGO_MERCHANT_ID=myMerchantId'); putenv('MAXIPAGO_MERCHANT_KEY=myMerchantKey'); putenv('MAXIPAGO_SANDBOX=true'); use Vitorccs\Maxipago\Builders\BillingDataBuilder; use Vitorccs\Maxipago\Builders\PixSaleBuilder; use Vitorccs\Maxipago\Enums\Processor; use Vitorccs\Maxipago\Exceptions\MaxipagoProcessorException; use Vitorccs\Maxipago\Exceptions\MaxipagoRequestException; use Vitorccs\Maxipago\Exceptions\MaxipagoValidationException; use Vitorccs\Maxipago\Http\QueryService; use Vitorccs\Maxipago\Http\SaleService; try { $queryService = new QueryService(); $saleService = new SaleService(); // CRIANDO TRANSAÇÃO $pixSale = PixSaleBuilder::create(200.00, 'COD_10001', 82400) ->setIpAddress('200.201.202.203') ->createBilling( name: 'João Silva', cpfCnpj: '409.289.289-11', rg: '4.533.890-0', companyName: 'Company Name' ) ->get(); $checkSuccess = true; // Habilitar MaxipagoProcessorException $response = $saleService->createPixSale($pixSale, $checkSuccess); print_r($response); // CONSULTANDO UMA TRANSAÇÃO $checkSuccess = true; // Habilitar MaxipagoNotFoundException $response = $queryService->getLastByOrderId($response->orderID, $checkSuccess); print_r($response); // CANCELANDO UMA TRANSAÇÃO (EM ABERTO) $response = $saleService->cancelSale($response->transactionId); print_r($response); } catch (MaxipagoValidationException $e) { // erros de Validação da API echo sprintf('ValidationException: %s (ErrorCode: %s, ResponseCode: %s)', $e->getMessage(), $e->getErrorCode(), $e->getResponseCode()); } catch (MaxipagoProcessorException $e) { // erros de Processor da API echo sprintf('ProcessorException: %s (ProcessorCode: %s)', $e->getMessage(), $e->getProcessorCode()); } catch (MaxipagoRequestException $e) { // erros não tratados (servidor e conexão) echo sprintf('RequestException: %s (HTTP Status: %s)', $e->getMessage(), $e->getHttpCode()); } catch (\Exception $e) { // demais erros (runtime, etc) echo $e->getMessage(); } ``` Webhooks -------- [](#webhooks) Para processar os [webhooks da Maxipago](https://www.maxipago.com/developers/apidocs/notificacoes-webhook/), pode-se usar a biblioteca de conversão de XML para PHP. ``` use Vitorccs\Maxipago\Converters\SymfonyXmlConverter; // recebe os dados em post $xmlString = file_get_contents('php://input'); // prepara serviço de conversão de XML $converter = new SymfonyXmlConverter(); // converte o XML recebido em array PHP $phpArray = $converter->decodeArray($xmlString); echo $phpArray['transaction-event']['orderID']; // converte o XML recebido em array PHP $phpObject = $converter->decodeObject($xmlString); echo $phpArray->{'transaction-event'}->orderID; ``` Testes ------ [](#testes) Caso queira contribuir, por favor, implementar testes de unidade em PHPUnit. Para executar: ``` composer test ``` ### Health Score 44 — FairBetter than 92% of packages Maintenance88 Actively maintained with recent releases Popularity17 Limited adoption so far Community7 Small or concentrated contributor base Maturity53 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~126 days Recently: every ~153 days Total 6 Last Release 61d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/2d5d2e771a97ac9dc5a1a1c8a18ec3cf97b5ea7872bfbc0fd62b060545cf6dfa?d=identicon)[vitorccs](/maintainers/vitorccs) --- Top Contributors [![vitorccs](https://avatars.githubusercontent.com/u/9891961?v=4)](https://github.com/vitorccs "vitorccs (13 commits)") --- Tags sdkmaxipago ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/vitorccs-maxipago-php-sdk/health.svg) ``` [![Health](https://phpackages.com/badges/vitorccs-maxipago-php-sdk/health.svg)](https://phpackages.com/packages/vitorccs-maxipago-php-sdk) ``` ### Alternatives [openai-php/laravel OpenAI PHP for Laravel is a supercharged PHP API client that allows you to interact with the Open AI API 3.7k7.6M74](/packages/openai-php-laravel)[guanguans/notify Push notification SDK(AnPush、Bark、Chanify、DingTalk、Discord、Gitter、GoogleChat、IGot、Lark、Mattermost、MicrosoftTeams、NowPush、Ntfy、Push、Pushback、PushBullet、PushDeer、PushMe、Pushover、PushPlus、QQ、RocketChat、ServerChan、ShowdocPush、SimplePush、Slack、Telegram、WeWork、WPush、XiZhi、YiFengChuanHua、ZohoCliq、ZohoCliqWebHook、Zulip). 682104.9k7](/packages/guanguans-notify)[infobip/infobip-api-php-client PHP library for consuming Infobip's API 921.8M10](/packages/infobip-infobip-api-php-client)[thenbsp/wechat 微信公众平台第三方 SDK 开发包，优雅、健壮，可扩展，遵循 PSR 开发规范。 9408.2k](/packages/thenbsp-wechat)[azure-oss/storage Azure Blob Storage PHP SDK 37985.0k5](/packages/azure-oss-storage)[onesignal/onesignal-php-api A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com 34170.2k2](/packages/onesignal-onesignal-php-api) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)