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

Índice

• iPag PHP client SDK
  • AVISO - SDK Abandonado
    • SDK Status
  • Dependências
  • Instalação
  • Autenticação
    • Por Basic Auth
  • Cliente
    • Dados do Cliente
  • Cartão de Crédito/Débito
    • Dados do Cartão de Crédito/Débito
  • Carrinho
    • Adicionando Produtos
  • Transação (Pagamento)
    • Transação com Cartão de Crédito
    • Transação com Token de Cartão de Crédito
    • Transação com Boleto
    • Transação com Pix
    • Consulta
    • Captura
    • Captura Parcial
    • Cancelamento
    • Cancelamento Parcial
  • Assinatura
    • Criando uma Assinatura
  • Exemplo de Transação Completa
    • Exemplo via Cartão de Crédito
  • Exemplo de Transação com Regra de Split
    • Exemplo via Cartão de Crédito
    • Exemplo via Boleto
  • Exemplo de Página de Callback
  • Resposta
  • Testes
  • Licença
  • Documentação
  • Dúvidas & Sugestões

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.