jhernandes/ipag-sdk-php

Pacote de integração para o iPag 1.0 em PHP

v1.1.26 2024-09-17 14:12 UTC

README

AVISO - SDK Abandonado

Este SDK foi abandonado e não será mais mantido. Para utilizar o iPag em sua loja, utilize através do projeto oficial do iPag: ipag-sdk-php.

Não há necessidade de migrar seu projeto atual para o novo SDK, pois este ainda ficará disponível para uso. Mas se for iniciar um novo projeto, utilize o SDK oficial.

SDK Status

Scrutinizer Code Quality Maintainability

Build Status

Índice

Dependências

require

  • [PHP >= 5.6]

require-dev

  • [phpunit/phpunit]
  • [codacy/coverage]

Instalação

Execute em seu shell:

composer require jhernandes/ipag-sdk-php

Autenticação

Por Basic Auth

require 'vendor/autoload.php';

use Ipag\Ipag;
use Ipag\Classes\Authentication;
use Ipag\Classes\Endpoint;

$ipag = new Ipag(new Authentication('my_id_ipag', 'my_ipag_key'), Endpoint::SANDBOX);

Cliente

Dados do Cliente

$customer = $ipag->customer()
    ->setName('Fulano da Silva')
    ->setTaxpayerId('799.993.388-01')
    ->setPhone('11', '98888-3333')
    ->setEmail('fulanodasilva@gmail.com')
    ->setBirthdate('1989-03-28')
    ->setAddress($ipag->address()
        ->setStreet('Rua Júlio Gonzalez')
        ->setNumber('1000')
        ->setNeighborhood('Barra Funda')
        ->setCity('São Paulo')
        ->setState('SP')
        ->setZipCode('01156-060')
);

Cartão de Crédito/Débito

Dados do Cartão de Crédito/Débito

$creditCard = $ipag->creditCard()
    ->setNumber('4066553613548107')
    ->setHolder('FULANO')
    ->setExpiryMonth('10')
    ->setExpiryYear('2025')
    ->setCvc('123')
    ->setSave(true); //True para gerar o token do cartão (one-click-buy)

Carrinho

Adicionando Produtos

// ...

$products = [
    // Nome do Produto, Valor Unitário, Quantidade, SKU (Código do Produto)
    ['Produto 1', 5.00, 1, 'ABDC1'],
    ['Produto 2', 3.50, 2, 'ABDC2'],
    ['Produto 3', 5.50, 1, 'ABDC3'],
    ['Produto 4', 8.50, 5, 'ABDC4']
];

// Deve-se usar o `splat operator`
$cart = $ipag->cart(...$products);

// ...

Transação (Pagamento)

Transação com Cartão de Crédito

$transaction = $ipag->transaction();

$transaction->getOrder()
    ->setOrderId($orderId)
    ->setCallbackUrl('https://minha_loja.com.br/ipag/callback')
    ->setAmount(10.00)
    ->setInstallments(1)
    ->setPayment($ipag->payment()
        ->setMethod(Method::VISA)
        ->setCreditCard($creditCard)
    )->setCustomer($customer)
);

$response = $transaction->execute();

Transação com Token de Cartão de Crédito

$transaction = $ipag->transaction();

$transaction->getOrder()
    ->setOrderId($orderId)
    ->setCallbackUrl('https://minha_loja.com.br/ipag/callback')
    ->setAmount(10.00)
    ->setInstallments(1)
    ->setPayment($ipag->payment()
        ->setMethod(Method::VISA)
        ->setCreditCard($ipag->creditCard()
            ->setToken('ABDC-ABCD-ABCD-ABDC')
        )
    )->setCustomer($customer)
);

$response = $transaction->execute();

Transação com Boleto

$transaction = $ipag->transaction();

$transaction->getOrder()
    ->setOrderId($orderId)
    ->setCallbackUrl('https://minha_loja.com.br/ipag/callback')
    ->setAmount(10.00)
    ->setInstallments(1)
    ->setExpiry('10/10/2017')
    ->setPayment($ipag->payment()
        ->setMethod(Method::BANKSLIP_ZOOP)
    )->setCustomer($customer)
);

$response = $transaction->execute();

Transação com Pix

$transaction = $ipag->transaction();

$transaction->getOrder()
    ->setOrderId($orderId)
    ->setCallbackUrl('https://minha_loja.com.br/ipag/callback')
    ->setAmount(10.00)
    ->setInstallments(1)
    ->setPayment($ipag->payment()
        ->setMethod(Method::PIX)
        ->setPixExpiresIn(60)
    )->setCustomer($customer)
);

$response = $transaction->execute();

// PIX LINK DE PAGAMENTO (Usando o Checkout do iPag para finalizar)
$linkDePagamento = $response->pix->link;

// PIX Copia e Cola | QRCode (Utilizar a string retornada ou gerar um QrCode)
$qrCodeString = $response->pix->qrCode;

Consulta

$response = $ipag->transaction()->setTid('123456789')->consult();

Captura

$response = $ipag->transaction()->setTid('123456789')->capture();

Captura Parcial

$response = $ipag->transaction()->setTid('123456789')->setAmount(1.00)->capture();

Cancelamento

$response = $ipag->transaction()->setTid('123456789')->cancel();

Cancelamento Parcial

$response = $ipag->transaction()->setTid('123456789')->setAmount(1.00)->cancel();

Assinatura

Criando uma Assinatura

$transaction = $ipag->transaction();

$transaction->getOrder()
    ->setOrderId($orderId)
    ->setCallbackUrl(getenv('CALLBACK_URL'))
    ->setAmount(10.00)
    ->setInstallments(1)
    ->setPayment($ipag->payment()
        ->setMethod(Method::VISA)
        ->setCreditCard($creditCard)
    )->setCustomer($customer)
)->setSubscription($ipag->subscription()
    ->setProfileId('1000000')
    ->setFrequency(1)
    ->setInterval('month')
    ->setStart('10/10/2018')
);

$response = $transaction->execute();

Exemplo de Transação Completa

Exemplo via Cartão de Crédito

<?php

require 'vendor/autoload.php';

use Ipag\Ipag;
use Ipag\Classes\Authentication;
use Ipag\Classes\Endpoint;
use Ipag\Classes\Enum\PaymentStatus;

try {
    $ipag = new Ipag(new Authentication('my_id_ipag', 'my_ipag_key'), Endpoint::SANDBOX);

    $customer = $ipag->customer()
        ->setName('Fulano da Silva')
        ->setTaxpayerId('799.993.388-01')
        ->setPhone('11', '98888-3333')
        ->setEmail('fulanodasilva@gmail.com')
        ->setAddress($ipag->address()
            ->setStreet('Rua Júlio Gonzalez')
            ->setNumber('1000')
            ->setNeighborhood('Barra Funda')
            ->setCity('São Paulo')
            ->setState('SP')
            ->setZipCode('01156-060')
    );
    $products = [
        ['Produto 1', 5.00, 1, 'ABDC1'],
        ['Produto 2', 2.50, 2, 'ABDC2']
    ];
    $cart = $ipag->cart(...$products);

    $creditCard = $ipag->creditCard()
        ->setNumber('4066553613548107')
        ->setHolder('FULANO')
        ->setExpiryMonth('10')
        ->setExpiryYear('2025')
        ->setCvc('123');

    $transaction = $ipag->transaction();

    $transaction->getOrder()
        ->setOrderId($orderId)
        ->setCallbackUrl('https://minha_loja.com.br/ipag/callback')
        ->setAmount(10.00)
        ->setInstallments(1)
        ->setPayment($ipag->payment()
            ->setMethod(Method::VISA)
            ->setCreditCard($creditCard)
        )
        ->setCustomer($customer)
        ->setCart($cart);

    $response = $transaction->execute();

    //Retornou algum erro?
    if (!empty($response->error)) {
        throw new \Exception($response->errorMessage);
    }

    //Pagamento Aprovado (5) ou Aprovado e Capturado(8) ?
    if (in_array($response->payment->status, [
        PaymentStatus::PRE_AUTHORIZED, PaymentStatus::CAPTURED
    ]) {
        //Faz alguma coisa...
        return $response;
    }
} catch(\Exception $e) {
    print_r($e->__toString());
}

Exemplo de Transação com Regra de Split

Exemplo via Cartão de Crédito

<?php

require 'vendor/autoload.php';

use Ipag\Ipag;
use Ipag\Classes\Authentication;
use Ipag\Classes\Endpoint;
use Ipag\Classes\Enum\PaymentStatus;

try {
    $ipag = new Ipag(new Authentication('my_id_ipag', 'my_ipag_key'), Endpoint::SANDBOX);

    $customer = $ipag->customer()
        ->setName('Fulano da Silva')
        ->setTaxpayerId('799.993.388-01')
        ->setPhone('11', '98888-3333')
        ->setEmail('fulanodasilva@gmail.com')
        ->setAddress($ipag->address()
            ->setStreet('Rua Júlio Gonzalez')
            ->setNumber('1000')
            ->setNeighborhood('Barra Funda')
            ->setCity('São Paulo')
            ->setState('SP')
            ->setZipCode('01156-060')
    );

    $products = [
        ['Produto 1', 5.00, 1, 'ABDC1'],
        ['Produto 2', 2.50, 2, 'ABDC2']
    ];
    $cart = $ipag->cart(...$products);

    $creditCard = $ipag->creditCard()
        ->setNumber('4066553613548107')
        ->setHolder('FULANO')
        ->setExpiryMonth('10')
        ->setExpiryYear('2025')
        ->setCvc('123');

    $payment = $ipag->payment()
            ->setMethod(Method::VISA)
            ->setCreditCard($creditCard);

    //Regra de Split 1 (com porcentagem %)
    $payment->addSplitRule($ipag->splitRule()
        ->setSellerId('c66fabf44786459e81e3c65e339a4fc9')
        ->setPercentage(15)
        ->setLiable(1)
    );

    //Regra de Split 2 (com valor absoluto R$)
    $payment->addSplitRule($ipag->splitRule()
        ->setSellerId('c66fabf44786459e81e3c65e339a4fc9')
        ->setAmount(5.00)
        ->setLiable(1)
    );

    $transaction = $ipag->transaction();
    $transaction->getOrder()
        ->setOrderId($orderId)
        ->setCallbackUrl('https://minha_loja.com.br/ipag/callback')
        ->setAmount(10.00)
        ->setInstallments(1)
        ->setPayment($payment)
        ->setCustomer($customer)
        ->setCart($cart);

    $response = $transaction->execute();

    //Retornou algum erro?
    if (!empty($response->error)) {
        throw new \Exception($response->errorMessage);
    }

    //Pagamento Aprovado (5) ou Aprovado e Capturado(8) ?
    if (in_array($response->payment->status, [
        PaymentStatus::PRE_AUTHORIZED, PaymentStatus::CAPTURED
    ]) {
        //Faz alguma coisa...
        return $response;
    }
} catch(\Exception $e) {
    print_r($e->__toString());
}

Exemplo via Boleto

<?php

require 'vendor/autoload.php';

use Ipag\Ipag;
use Ipag\Classes\Authentication;
use Ipag\Classes\Endpoint;
use Ipag\Classes\Enum\PaymentStatus;

try {
    $ipag = new Ipag(new Authentication('my_id_ipag', 'my_ipag_key'), Endpoint::SANDBOX);

    $customer = $ipag->customer()
        ->setName('Fulano da Silva')
        ->setTaxpayerId('799.993.388-01')
        ->setPhone('11', '98888-3333')
        ->setEmail('fulanodasilva@gmail.com')
        ->setAddress($ipag->address()
            ->setStreet('Rua Júlio Gonzalez')
            ->setNumber('1000')
            ->setNeighborhood('Barra Funda')
            ->setCity('São Paulo')
            ->setState('SP')
            ->setZipCode('01156-060')
    );
    $products = [
        ['Produto 1', 5.00, 1, 'ABDC1'],
        ['Produto 2', 2.50, 2, 'ABDC2']
    ];
    $cart = $ipag->cart(...$products);

    $transaction = $ipag->transaction();

    $transaction->getOrder()
        ->setOrderId($orderId)
        ->setCallbackUrl('https://minha_loja.com.br/ipag/callback')
        ->setAmount(10.00)
        ->setInstallments(1)
        ->setExpiry('10/07/2021')
        ->setPayment($ipag->payment()
            ->setMethod(Method::BANKSLIP_ZOOP)
        )->setCustomer($customer)
    );

    $response = $transaction->execute();

    //Retornou algum erro?
    if (!empty($response->error)) {
        throw new \Exception($response->errorMessage);
    }

    //Pagamento de Boleto Criado (1) ou Boleto Impresso (2) ?
    if (in_array($response->payment->status, [
        PaymentStatus::CREATED,
        PaymentStatus::PRINTED_BOLETO
    ])) {
        // Boleto Link
        //echo $response->urlAuthentication;

        return $response;
    }
} catch(\Exception $e) {
    print_r($e->__toString());
}

Exemplo de Página de Callback

<?php

require_once 'vendor/autoload.php';

use Ipag\Classes\Services\CallbackService;
use Ipag\Classes\Enum\PaymentStatus;

$postContent = file_get_contents('php://input');

$callbackService = new CallbackService();

// $response conterá os dados de retorno do iPag
// $postContent deverá conter o XML enviado pelo iPag
$response = $callbackService->getResponse($postContent);

// Verificar se o retorno tem erro
if (!empty($response->error)) {
    echo "Contem erro! {$response->error} - {$response->errorMessage}";
}

// Verificar se a transação foi aprovada e capturada:
if ($response->payment->status == PaymentStatus::CAPTURED) {
    echo 'Transação Aprovada e Capturada';
    // Atualize minha base de dados ...
}

Resposta

Estrutura do Transaction Response:

  • transaction
    • id
    • tid
    • authId
    • amount
    • acquirer
    • acquirerMessage
    • urlAuthentication
    • urlCallback
    • createdAt
    • creditCard
      • holder
      • number
      • expiry
      • brand
      • token
    • subscription
      • id
      • profileId
    • payment
      • status
      • message
    • order
      • orderId
    • customer
      • name
      • email
      • phone
      • cpfCnpj
      • address
        • street
        • number
        • district
        • complement
        • city
        • state
        • zipCode
    • antifraud
      • id
      • score
      • status
      • message
    • splitRules
      • [0]
        • rule
        • seller_id
        • ipag_id
        • amount
        • amount
        • percentage
        • liable
        • charge_processing_fee
    • error
    • errorMessage
    • history
      • [0]
        • amount
        • operationType
        • status
        • responseCode
        • responseMessage
        • authorizationCode
        • authorizationId
        • authorizationNsu
        • createdAt

Testes

Os Tests Unitários são realizados contra o Sandbox do iPag, o arquivo de configuração (phpunit.xml) já vem preenchido com um acesso limitado ao Sandbox.

É necessário a instalação do PHPUnit para a realização dos testes.

Licença

The MIT License

Documentação

Documentação Oficial

Dúvidas & Sugestões

Em caso de dúvida ou sugestão para o SDK abra uma nova Issue.