README

用于Maxipago API的PHP SDK

要求

• PHP >= 8.1

描述

用于Maxipago API的PHP SDK。

安装

通过Composer

composer require vitorccs/maxipago-php-sdk

参数

可以通过环境变量定义

# Em um arquivo .env do seu projeto:
MAXIPAGO_MERCHANT_ID=myMerchantId
MAXIPAGO_MERCHANT_KEY=myMerchantKey
MAXIPAGO_SANDBOX=true
MAXIPAGO_TIMEOUT=60

或作为服务参数传递

use Vitorccs\Maxipago\Entities\Parameters;
use Vitorccs\Maxipago\Http\SaleService;

$parameters = new Parameters(
    'myMerchantId',
    'myMerchantKey', 
    true, // modo sandbox
    60 // timeout
);

$saleService = new SaleService($parameters);

实现的服务

# 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();

创建客户

// Nota: utilize CustomerBuilder (descrito mais abaixo na documentação)
// para gerar facilmente o objeto $customer
$response = $customerService->create($customer);

执行订单

// 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);

查询订单

可以通过任何这些标准获取交易

// 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);

取消订单

// Nota: somente disponível para pedidos em aberto e para algumas 
// formas de pagamento (ex: Boleto e PIX)
$response = $saleService->cancelSale($transactionId);

退款订单

// Nota: todos os campos são obrigatórios.
$chargeTotal = 100.00;
$response = $saleService->refundSale($orderId, $referenceNumber, $chargeTotal);

管理信用卡

// 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);

构建器（Builders）

为了帮助创建交易，提供了一些构建器

创建客户

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();

创建支票订单

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();

创建信用卡订单

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();

创建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();

错误处理

该库抛出以下异常

主要

• MaxipagoValidationException 用于Maxipago API检测到的各种错误，包括阻止交易创建的错误（errorCode 不为0）。
• MaxipagoRequestException 用于API未处理的其余错误，包括服务器错误（HTTP 4xx或5xx）和连接错误（例如超时）。

在创建交易服务中

• MaxipagoProcessorException 当交易成功由Maxipago创建，但存在“处理器”错误时（responseCode 不为0）。

在查询交易服务中

• MaxipagoNotFoundException 在尝试定位不存在的交易时（例如通过OrderId或TransactionId定位）。

将抛出MaxipagoValidationException的响应体示例

<root>
    <header>
        <errorCode>1</errorCode>
        <errorMsg><![CDATA[Descrição do erro]]></errorMsg>
    </header>
</root>

将抛出MaxipagoProcessorException的响应体示例

<root>
  <orderID>0B0214CB:018A9C5B6ACA:DBCC:0344E731</orderID>
  <referenceNum>15d71318-71f3-4312-96f8-741f082dd6e7</referenceNum>
  <transactionID>623999551</transactionID>
  <transactionTimestamp>1716315187</transactionTimestamp>
  <responseCode>1</responseCode>
  <responseMessage/>
  <processorCode>400</processorCode>
  <processorMessage>Descrição do erro</processorMessage>
  <processorName>PIXITAU</processorName>
  <errorMessage>Descrição do erro</errorMessage>
</root>

实现示例

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

为了处理Maxipago的webhooks，可以使用PHP的XML转换库。

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;

测试

如果您想贡献，请实现PHPUnit的单元测试。

执行

composer test