README

Integração em PHP para a Pagar.me API

Índice

Instalação e configuração
Utilizando a SDK
Suporte
Licença
Contribuindo

Instalação e configuração

Para utilizar a biblioteca, você pode instalá-la via composer, com o comando:

composer require 'pagarme/pagarme-php-v3.7.10'

Então, basta importá-la para dentro de seu arquivo e instanciar o objeto PagarMe:

require __DIR__.'/vendor/autoload.php';

$apiKey = 'ak_test_grXijQ4GicOa2BLGZrDRTR5qNQxJW0';
$pagarMe =  new \PagarMe\Sdk\PagarMe($apiKey);

Nota: todos os exemplos listados aqui utilizam o objeto $pagarMe instanciado acima.

Utilizando a SDK

Parâmetros page e count

$page representa o número da página e $count representa a quantidade de registros. Então, se você utilizar, $page = 2 e $count = 20 para buscar um objeto, serão retornados os 20~40 objetos mais recentes

Transações

Nesta seção será explicado como utilizar transações no Pagar.me com essa biblioteca.

Criando uma transação

<?php
$amount = 1000;
$installments = 1;
$capture = true;
$postbackUrl = 'http://requestb.in/pkt7pgpk';
$metadata = ['idProduto' => 13933139];

$customer = new \PagarMe\Sdk\Customer\Customer(
    [
        'name' => 'John Dove',
        'email' => 'john@site.com',
        'document_number' => '09130141095',
        'address' => [
            'street'        => 'rua teste',
            'street_number' => 42,
            'neighborhood'  => 'centro',
            'zipcode'       => '01227200',
            'complementary' => 'Apto 42',
            'city'          => 'São Paulo',
            'state'         => 'SP',
            'country'       => 'Brasil'
        ],
        'phone' => [
            'ddd'    => "15",
            'number' =>"987523421"
        ],
        'born_at' => '15021994',
        'sex' => 'M'
    ]
);

$card = $pagarMe->card()->create(
    '4242424242424242',
    'JOHN DOVE',
    '0722'
);

$recipient1 = $pagarMe->recipient()->get('re_civb4p9l7004xbm6dhsetkpj8');
$recipient2 = $pagarMe->recipient()->get('re_civb4o6zr003u3m6e8dezzja6');

$splitRule1 = $pagarMe->splitRule()->percentageRule(
    40,
    $recipient1,
    true, // liable
    true, // chargeProcessingFee,
    true // chargeReminder
);

$splitRule2 = $pagarMe->splitRule()->percentageRule(
    60,
    $recipient,
    true, // liable
    true, // chargeProcessingFee,
    false // chargeReminder
);

$splitrules = new PagarMe\Sdk\SplitRule\SplitRuleCollection();
$splitrules[0] = $splitRule1;
$splitrules[1] = $splitRule2;

// Credit Card Transaction
$transaction = $pagarMe->transaction()->creditCardTransaction(
    $amount,
    $card,
    $customer,
    $installments,
    $capture,
    $postbackUrl,
    $metadata,
    ["split_rules" => $splitrules]
);

// Boleto Transaction
$transaction2 = $pagarMe->transaction()->boletoTransaction(
    $amount,
    $customer,
    $postbackUrl,
    $metadata,
    ["split_rules" => $splitrules]
);

Capturando uma transação

<?php
$transaction = $pagarMe->transaction()->get(4752390);
$amountToCapture = 1000;
$metadata = ['idProduto' => '123']; // Parâmetro opcional

$splitRules = new \PagarMe\Sdk\SplitRule\SplitRuleCollection(); // Parâmetro opcional

$recipient1 = $pagarMe->recipient()->get('re_cjqgt03fv02bq4k6e3xbxxbia');
$recipient2 = $pagarMe->recipient()->get('re_cjm0lfmy3001zaq6espflawv2');

$splitRule1 = $pagarMe->splitRule()->percentageRule(
    40,
    $recipient1,
    true, // liable
    true, // chargeProcessingFee,
    true // chargeReminder
);

$splitRule2 = $pagarMe->splitRule()->percentageRule(
    60,
    $recipient2,
    true, // liable
    true, // chargeProcessingFee,
    false // chargeReminder
);

$splitRules[] = $splitRule1;
$splitRules[] = $splitRule2;

$pagarMe->transaction()->capture($transaction, $amountToCapture, $metadata, $splitRules);

Estornando uma transação

<?php
$transaction = $pagarMe->transaction()->get("1627830");

// Credit Card Refund
$transaction = $pagarMe->transaction()->creditCardRefund($transaction);

// Boleto Refund
$bankAccount = $pagarMe->bankAccount()->create(
  '341',
  '0932',
  '58054',
  '5',
  '26268738888',
  'API BANK ACCOUNT',
  '1'
);

$transaction = $pagarMe->transaction()->boletoRefund($transaciton, $bankAccount);

Esta funcionalidade também funciona com estornos parciais, ou estornos com split. Por exemplo:

Estornando uma transação parcialmente

<?php
$transaction = $pagarMe->transaction()->get("1627835");
$amountRefunded = 20000;

// Credit card
$transaction = $pagarMe->transaction()->creditCardRefund(
    $transaction,
    $amountRefunded
);

// Boleto
$transaction = $pagarMe->transaction()->boletoRefund(
    $transaciton,
    $bankAccount,
    $amountRefunded
);

Estornando uma transação com split

Não possui essa feature.

Retornando transações

<?php
$transactionList = $pagarMe->transaction()->getList($page, $count);

Retornando uma transação

<?php
$transactionId = "1627864";
$transaction = $pagarMe->transaction()->get($transactionId);

Retornando recebíveis de uma transação

Não possui essa feature.

Retornando um recebível de uma transação

Não possui essa feature.

Retornando o histórico de operações de uma transação

Não possui essa feature.

Notificando cliente sobre boleto a ser pago

Não possui essa feature.

Retornando eventos de uma transação

$transactionId = "1627864";
$transaction = $pagarMe->transaction()->get($transactionId);
$transactionEvents = $pagarMe->transaction()->events($transaction);

Calculando pagamentos parcelados

Essa rota não é obrigatória para uso. É apenas uma forma de calcular pagamentos parcelados com o Pagar.me.

Para fins de explicação, utilizaremos os seguintes valores:

amount: 1000, free_installments: 4, max_installments: 12, interest_rate: 3

O parâmetro free_installments decide a quantidade de parcelas sem juros. Ou seja, se ele for preenchido com o valor 4, as quatro primeiras parcelas não terão alteração em seu valor original.

Nessa rota, é calculado juros simples, efetuando o seguinte calculo:

valorTotal = valorDaTransacao ( 1 + ( taxaDeJuros numeroDeParcelas ) / 100 )

Então, utilizando os valores acima, na quinta parcela, a conta ficaria dessa maneira:

valorTotal = 1000 (1 + (3 5) / 100)

Então, o valor a ser pago na quinta parcela seria de 15% da compra, totalizando 1150.

Você pode usar o código abaixo caso queira utilizar essa rota:

<?php
$amount = 10000;
$rate = 13;
$rateFreeInstallments = 1;
$maxInstallments = 12;
$installments = $pagarMe->calculation()->calculateInstallmentsAmount(
    $amount,
    $rate,
    $rateFreeInstallments,
    $maxInstallments
);

$totalAmount = $installments[2]["total_amount"];
$installmentAmount = $installments[2]["installment_amount"];

Testando pagamento de boletos

<?php
$transaction = $pagarMe->transaction()->payTransaction(1627871);

Estornos

Você pode visualizar todos os estornos que ocorreram em sua conta, com esse código:

Não possui essa feature.

Cartões

Sempre que você faz uma requisição através da nossa API, nós guardamos as informações do portador do cartão, para que, futuramente, você possa utilizá-las em novas cobranças, ou até mesmo implementar features como one-click-buy.

Criando cartões

<?php
//Create with card data
$cardNumber = '4242424242424242';
$cardHolderName = 'Aardvark Silva';
$cardExpirationDate = '1122';
$cardCvv = 123;
$card = $pagarMe->card()->create(
    $cardNumber,
    $cardHolderName,
    $cardExpirationDate,
    $cardCvv
);

//Create with card_hash
$card = $pagarMe->card()->createFromHash('card_hash');

Retornando cartões

Não possui essa feature.

Retornando um cartão

$cardId = 'card_cj428xxsx01dt3f6dvre6belx';
$card = $pagarMe->card()->get(cardId);

Planos

Representa uma configuração de recorrência a qual um cliente consegue assinar. É a entidade que define o preço, nome e periodicidade da recorrência

Criando planos

$amount = 15000;
$days = 30;
$name = 'The Pro Plan - Platinum  - Best Ever';
$trialDays = 0;
$paymentsMethods = ['credit_card', 'boleto'];
$charges = null;
$installments = 1;

$plan = $pagarMe->plan()->create(
    $amount,
    $days,
    $name,
    $trialDays,
    $paymentsMethods,
    $charges,
    $installments
);

Retornando planos

<?php
$plans = $pagarMe->plan()->getList($page, $count);

Retornando um plano

<?php
$plan = $pagarMe->plan()->get(164526);

Atualizando um plano

<?php
$oldPlan = $pagarMe->plan()->get(163871);
$oldPlan->setName('The Pro Plan - Susan');
$oldPlan->setTrialDays('7');

$newPlan = $pagarMe->plan()->update($oldPlan);

Assinaturas

Criando assinaturas

<?php
$planId = 136869;
$plan = $pagarMe->plan()->get($planId);

$cardId = 'card_cizri9czn00csfi6e1ygzw9vz';
$card = $pagarMe->card()->get($cardId);
$metadata = ['idAssinatura' => '123'];
$extraAttributtes = [
    'soft_descriptor' => 'Minha empresa'
];

$postbackUrl = 'http://requestb.in/zyn5obzy';

$customer = new \PagarMe\Sdk\Customer\Customer(
    [
        'name' => 'John Dove',
        'email' => 'john@site.com',
        'document_number' => '09130141095',
        'address' => new \PagarMe\Sdk\Customer\Address([
            'street'        => 'rua teste',
            'street_number' => 42,
            'neighborhood'  => 'centro',
            'zipcode'       => '01227200',
            'complementary' => 'Apto 42',
            'city'          => 'São Paulo',
            'state'         => 'SP',
            'country'       => 'Brasil'
        ]),
        'phone' => new \PagarMe\Sdk\Customer\Phone([
            'ddd'    => "15",
            'number' =>"987523421"
        ]),
        'born_at' => '15021994',
        'sex' => 'M'
    ]
);

// Credit card subscription
$subscription = $pagarMe->subscription()->createCardSubscription(
    $plan,
    $card,
    $customer,
    $postbackUrl,
    $metadata,
    $extraAttributes
);

// Boleto Subscription
$subscription = $pagarMe->subscription()->createBoletoSubscription(
    $transaction,
    $customer,
    $postbackUrl,
    $metadata,
    $extraAttributtes
);

Split com assinatura

<?php
$planId = 136869;
$plan = $pagarMe->plan()->get($planId);

$cardId = 'card_cizri9czn00csfi6e1ygzw9vz';
$card = $pagarMe->card()->get($cardId);
$metadata = ['idAssinatura' => '123'];

$postbackUrl = 'http://requestb.in/zyn5obzy';

$customer = new \PagarMe\Sdk\Customer\Customer(
    [
        'name' => 'John Dove',
        'email' => 'john@site.com',
        'document_number' => '09130141095',
        'address' => new \PagarMe\Sdk\Customer\Address([
            'street'        => 'rua teste',
            'street_number' => 42,
            'neighborhood'  => 'centro',
            'zipcode'       => '01227200',
            'complementary' => 'Apto 42',
            'city'          => 'São Paulo',
            'state'         => 'SP',
            'country'       => 'Brasil'
        ]),
        'phone' => new \PagarMe\Sdk\Customer\Phone([
            'ddd'    => "15",
            'number' =>"987523421"
        ]),
        'born_at' => '15021994',
        'sex' => 'M'
    ]
);

$splitRules = new \PagarMe\Sdk\SplitRule\SplitRuleCollection();

$recipient1 = $pagarMe->recipient()->get('re_cjqgt03fv02bq4k6e3xbxxbia');
$recipient2 = $pagarMe->recipient()->get('re_cjm0lfmy3001zaq6espflawv2');

$splitRule1 = $pagarMe->splitRule()->percentageRule(
    40,
    $recipient1,
    true, // liable
    true, // chargeProcessingFee,
    true // chargeReminder
);

$splitRule2 = $pagarMe->splitRule()->percentageRule(
    60,
    $recipient2,
    true, // liable
    true, // chargeProcessingFee,
    false // chargeReminder
);

$splitRules[] = $splitRule1;
$splitRules[] = $splitRule2;


// Credit card subscription
$subscription = $pagarMe->subscription()->createCardSubscription(
    $plan,
    $card,
    $customer,
    $postbackUrl,
    $metadata,
    ['split_rules' => $splitRules]
);

// Boleto Subscription
$subscription = $pagarMe->subscription()->createBoletoSubscription(
    $transaction,
    $customer,
    $postbackUrl,
    $metadata,
    ['split_rules' => $splitRules]
);

Retornando uma assinatura

<?php
$subscription = $pagarMe->subscription()->get(205881);

Retornando assinaturas

<?php
$subscriptions = $pagarMe->subscription()->getList($page, $count);

Atualizando uma assinatura

<?php
$subscription = $pagarMe->subscription()->get(184577);
$newPlan = $pagarMe->plan()->get(166234);
$subscription->setPlan($newPlan);
$subscription->setPaymentMethod('credit_card');
$card = $pagarMe->card()->get('card_cj41mpuhc01bb3f6d8exeo072');
$subscription->setCard($card);

$updatedSubscription = $pagarMe->subscription()->update($subscription);

Cancelando uma assinatura

<?php
$subscriptionId = 205880;
$subscription = $pagarMe->subscription()->get($subscriptionId);
$subscription = $pagarMe->subscription()->cancel($subscription);

Transações de assinatura

<?php
$subscriptionId = 205840;
$subscription = $pagarMe->subscription()->get($subscriptionId);
$transactions = $pagarMe->subscription()->transactions($subscription);

Pulando cobranças

Não possui essa feature.

Postbacks

Ao criar uma transação ou uma assinatura você tem a opção de passar o parâmetro postback_url na requisição. Essa é uma URL do seu sistema que irá então receber notificações a cada alteração de status dessas transações/assinaturas.

Para obter informações sobre postbacks, 3 informações serão necessárias, sendo elas: model, model_id e postback_id.

model: Se refere ao objeto que gerou aquele POSTback. Pode ser preenchido com o valor transaction ou subscription.

model_id: Se refere ao ID do objeto que gerou ao POSTback, ou seja, é o ID da transação ou assinatura que você quer acessar os POSTbacks.

postback_id: Se refere à notificação específica. Para cada mudança de status de uma assinatura ou transação, é gerado um POSTback. Cada POSTback pode ter várias tentativas de entregas, que podem ser identificadas pelo campo deliveries, e o ID dessas tentativas possui o prefixo pd_. O campo que deve ser enviado neste parâmetro é o ID do POSTback, que deve ser identificado pelo prefixo po_.

Retornando postbacks

$transactionId = 1159049;
$transaction = $pagarMe->transaction()->get(transactionId);
$postbacks = $pagarMe->postback()->getList($transaction);

Retornando um postback

<?php
$transactionId = 1159049;
$transaction = $pagarMe->transaction()->get($transactionId);

$postbackId = 'po_ciat6ssga0022k06ng8vxg';
$postbacks = $pagarMe->postback()->get(
    $transaction,
    $postbackId
);

Reenviando um postback

<?php
$transactionId = 1662527;
$transaction = $pagarMe->transaction()->get($transactionId);

$postbackId = 'po_cj4haa8l4131bpi73glgzbnpp';
$postbacks = $pagarMe->postback()->redeliver(
    $transaction,
    $postbackId
);

Validando uma requisição de postback

<?php
$postbackBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_HUB_SIGNATURE'];

if ($pagarMe->postback()->validateRequest($postbackBody, $signature) {
    echo "POSTback válido";
} else {
    echo "POSTback inválido";
}

Observação: o código acima serve somente de exemplo para que o processo de validação funcione. Recomendamos que utilize ferramentas fornecidas por bibliotecas ou frameworks para recuperar estas informações de maneira mais adequada.

Saldo do recebedor principal

Para saber o saldo de sua conta, você pode utilizar esse código:

<?php
$balance = $pagarMe->balance()->get();

Operações de saldo

Com este objeto você pode acompanhar todas as movimentações financeiras ocorridas em sua conta Pagar.me.

Histórico das operações

<?php
$operationList = $pagarMe->balanceOperation()->getList();

Histórico de uma operação específica

$operation = $pagarme->balanceOperation()->get(4861);

Recebível

Objeto contendo os dados de um recebível. O recebível (payable) é gerado automaticamente após uma transação ser paga. Para cada parcela de uma transação é gerado um recebível, que também pode ser dividido por recebedor (no caso de um split ter sido feito).

Retornando recebíveis

<?php
$payables = $pagarMe->payable()->getList($page, $count);

Retornando um recebível

<?php
$payable = $pagarMe->payable()->get("573310");

Transferências

Transferências representam os saques de sua conta.

Criando uma transferência

<?php
$amount = 10000;
$recipient = $pagarMe->recipient()->get('re_citkg218g00hl8q6dh1pr5mld');

$transfer = $pagarMe->transfer()->create(
    $amount,
    $recipient
);

Retornando transferências

<?php
$transfers = $pagarMe->transfer()->getList($page, $count)

Retornando uma transferência

<?php
$transfer = $pagarMe->transfer()->get("16264");

Cancelando uma transferência

<?php
$transfer = $pagarMe->transfer()->get("16264");
$canceledTransfer = $pagarMe->transfer()->cancel($transfer);

Antecipações

Para entender o que são as antecipações, você deve acessar esse link.

Criando uma antecipação

<?php
$recipientId = "re_ciu4jif1j007td56dsm17yew9";
$recipient = new \PagarMe\Sdk\Recipient\Recipient([
    "id" => $recipientId
]);

$date = new \DateTime();
$date->add(new \DateInterval("P10D"));
$timeframe = 'end';
$requestedAmount = 13000;
$build = true;
$anticipation = $pagarMe->bulkAnticipation()->create(
    $recipient,
    $date,
    $timeframe,
    $requestedAmount,
    $build
);

Obtendo os limites de antecipação

<?php
$recipientId = "re_ciu4jif1j007td56dsm17yew9";
$recipient = new \PagarMe\Sdk\Recipient\Recipient([
    "id" => recipientId
]);

$paymentDate = new \DateTime();
$paymentDate->add(new \DateInterval("P10D"));
$timeframe = 'end';
$limits = $pagarMe->bulkAnticipation()->limits(
    $recipient,
    $paymentDate,
    $timeframe
);

Confirmando uma antecipação building

<?php
$recipient = new \PagarMe\Sdk\Recipient\Recipient([
    "id" => "re_ciu4jif1j007td56dsm17yew9"
]);

$anticipation = new PagarMe\Sdk\BulkAnticipation\BulkAnticipation([
    "id" => "ba_cj3uppown001gvm6dqgmjw2ce"
]);

$anticipation = $pagarMe->bulkAnticipation()->confirm(
    $recipient,
    $anticipation
);

Cancelando uma antecipação pending

<?php
$recipient = new \PagarMe\Sdk\Recipient\Recipient([
    "id" => "re_ciu4jif1j007td56dsm17yew9"
]);

$anticipation = new PagarMe\Sdk\BulkAnticipation\BulkAnticipation([
    "id" => "ba_cj3ur2rpl002bpn6ektsnc9lu"
]);

$anticipation = $pagarMe->bulkAnticipation()->cancel(
    $recipient,
    $anticipation
);

Deletando uma antecipação building

<?php
$recipient = new \PagarMe\Sdk\Recipient\Recipient([
    "id" => "re_ciu4jif1j007td56dsm17yew9"
]);

$anticipation = new PagarMe\Sdk\BulkAnticipation\BulkAnticipation([
    "id" => "ba_cj3us6nal0022v86daxfamp4t"
]);

$anticipation = $pagarMe->bulkAnticipation()->delete(
    $recipient,
    $anticipation
);

Retornando antecipações

<?php
$recipietId = "re_ciu4jif1j007td56dsm17yew9";
$page = 1;
$count = 50;
$recipient = new \PagarMe\Sdk\Recipient\Recipient([
    "id" => $recipientId
]);
$anticipationList = $pagarMe->bulkAnticipation()->getList(
    $recipient,
    $page,
    $count
);

Contas bancárias

Contas bancárias identificam para onde será enviado o dinheiro de futuros pagamentos.

Criando uma conta bancária

<?php
$bankCode = '341';
$agenciaNumber = '0932';
$accountNumber = '58054';
$accountDigit = '5';
$documentNumber = '26268738888';
$legalName = 'Conta Teste 2';
$agenciaDigit = '1';
$bankAccount = $pagarMe->bankAccount()->create(
    $bankCode,
    $agenciaNumber,
    $accountNumber,
    $accountDigit,
    $documentNumber,
    $legalName,
    $agenciaDigit
);

Retornando uma conta bancária

<?php
$bankAccountId = 17411339;
$bankAccount = $pagarMe->bankAccount()->get($bankAccountId);

Retornando contas bancárias

<?php
$bankAccounts = $pagarMe->bankAccount()->getList($page, $count);

Recebedores

Para dividir uma transação entre várias entidades, é necessário ter um recebedor para cada uma dessas entidades. Recebedores contém informações da conta bancária para onde o dinheiro será enviado, e possuem outras informações para saber quanto pode ser antecipado por ele, ou quando o dinheiro de sua conta será sacado automaticamente.

Criando um recebedor

<?php
$bankAccount = new \PagarMe\Sdk\BankAccount\BankAccount([
    "id" => 17490076
]);

$transferInterval = "monthly";
$transferDay = 13;
$transferEnabled = true;
$automaticAnticipationEnabled = true;
$anticipatableVolumePercentage = 42;
$recipient = $pagarMe->recipient()->create(
    $bankAccount,
    $transferInterval,
    $transferDay,
    $transferEnabled,
    $automaticAnticipationEnabled,
    $anticipatableVolumePercentage
);

Retornando recebedores

<?php
$recipients = $pagarMe->recipient()->getList($page, $count);

Retornando um recebedor

<?php
$recipientId = "re_cj3g1cml000e75f6ehjnpsl9y";
$recipient = $pagarMe->recipient()->get($recipientId);

Atualizando um recebedor

<?php
$recipientId = "re_ciu4jif1j007td56dsm17yew9";
$recipient = new \PagarMe\Sdk\Recipient\Recipient([
    "id" => $recipientId,
    "anticipatable_volume_percentage" => "50",
    "transfer_enabled" => true,
    "transfer_interval" => "monthly",
    "transfer_day" => 15,
    "bank_account" => new \PagarMe\Sdk\BankAccount\BankAccount([
        "id" => "17492906"
    ])
]);

$updatedRecipient = $pagarMe->recipient()->update(
    $recipient
);

Saldo de um recebedor

<?php
$recipientId = "re_cj3g1cml000e75f6ehjnpsl9y";
$recipient = $pagarMe->recipient()->get($recipientId);
$balance = $pagarMe->recipient()->balance($recipient);

Operações de saldo de um recebedor

<?php
$recipientId = "re_cj3g1cml000e75f6ehjnpsl9y";
$recipient = $pagarMe->recipient()->get($recipientId);
$balance = $pagarMe->recipient()->balanceOperations($recipient, $page, $count);

Operação de saldo específica de um recebedor

<?php
$recipientId = "re_ciu4jif1j007td56dsm17yew9";
$recipient = $pagarMe->recipient()->get($recipientId);
$balanceOperationId = 2043993;
$operation = $pagarMe->recipient()->balanceOperation($recipient, $balanceOperationId);

Clientes

Clientes representam os usuários de sua loja, ou negócio. Este objeto contém informações sobre eles, como nome, e-mail e telefone, além de outros campos.

Criando um cliente

<?php
$customer = $pagarMe->customer()->create(
    'John Dove',
    'john@site.com',
    '09130141095',
    /** @var $address \PagarMe\Sdk\Customer\Address */
    $address,
    /** @var $phone \PagarMe\Sdk\Customer\Phone */
    $phone,
    '15021994',
    'M'
);

Retornando clientes

<?php
$customerList = $pagarMe->customer()->getList();

Retornando um cliente

<?php
$customer = $pagarme->customer()->get(11222);

Suporte

Se você tiver qualquer problema ou sugestão, por favor abra uma issue aqui.

Contribuindo

Veja nosso guia de contribuição antes de nos enviar sua contribuição.

rededecisao / pagarme-php

Maintainers

Details