O modo mais simples e fácil de integrar sua aplicação PHP com a Paggcerto.
Sumário
- Requisições
- Instalação
- Exemplos de utilização
Para utilizar nosso SDK é necessário ter as seguintes requisições:
- PHP >= 5.5
- rmccue/requests >= 1.0
- phpunit/phpunit ~ 5.0
Para iniciar a instalação execute em seu shell:
composer require paggcerto/paggcerto-sdk-php
require 'vendor/autoload.php';
use Paggcerto\Auth;
use Paggcerto\Auth\NoAuth;
$endpoint = "prod";
$paggcerto = new Paggcerto(new NoAuth, $endpoint);
require 'vendor/autoload.php';
use Paggcerto\Auth;
use Paggcerto\Auth\Auth;
$endpoint = "prod";
$user = "[email protected]";
$password = "12345678";
$appId = "LkD";
$paggcerto = new Paggcerto(new Auth($user, $password, $appId), $endpoint);
require 'vendor/autoload.php';
use Paggcerto\Auth;
use Paggcerto\Auth\Auth;
$endpoint = "prod";
$hash = "Ehjikkja585569779efwrf.ihuheyvvc872622791ndbdehv";
$appId = "LkD";
$paggcerto = new Paggcerto(new AuthHash($hash, $appId), $endpoint);
Este método é utilizado para o cadastro da conta do titular. Após a finalização deste cadastro, deve ser realizada a autenticação do titular da conta.
$holder = $paggcerto->account()
->setHolderFullName("Mariana Fulano de Tal")
->setHolderBirthDate("1995-01-18")
->setHolderGender("F")
->setHolderTaxDocument("927.228.895-95")
->setHolderPhone("(79) 2946-7954")
->setHolderMobile("(79) 99999-9999")
->setCompanyTradeName("Esportes ME")
->setCompanyFullName("Mariana e Emanuelly Esportes ME")
->setCompanyTaxDocument("94.467.995/0001-49")
->setBusinessTypeId("vL")
->setAddressCityCode("2800308")
->setAddressDistrict("Farolândia")
->setAddressLine1("Rua Silvio do Espírito Santos Seixas")
->setAddressLine2("Ap 001, Cleveland House")
->setAddressStreetNumber("92")
->setAddressZipCode("49030-423")
->setBankAccountBankNumber("001")
->setBankAccountNumber("31232156132-12")
->setBankAccountBranchNumber("0031")
->setBankAccountVariation("001")
->setBankAccountType("corrente")
->setBankAccountIsJuridic(true)
->setUserEmail("[email protected]")
->setUserPassword("12345678")
->setBusinessActivityId("MA")
->setMarketingMediaId("k5")
->setTransferPlanDays(32)
->setTransferPlanAnticipated(true)
->setMothersName("Mothers Name")
->createHolderAccount();
print_r($holder);
Com a configuração da conta podem ser alteradas as seguintes informações:
- Conta bancária;
- A descrição que irá constar na fatura do cliente ;
- Endereço;
- Escolher o dia para repasse: 2 ou 32 dias;
$presetsHolder = $paggcerto->account()
->setUserPassword("12345678")
->setPhone("(79) 2946-7954")
->setMobile("(79) 99999-9999")
->setComercialName("Esporte e CIA")
->setSoftDescriptor("Esportes ME")
->setTransferPlanDays(32)
->setTransferPlanAnticipated(true)
->setBankAccountBankNumber("001")
->setBankAccountNumber("31232156132-12")
->setBankAccountBranchNumber("0031")
->setBankAccountVariation("001")
->setBankAccountType("corrente")
->setBankAccountIsJuridic(true)
->setAddressCityCode("2800308")
->setAddressDistrict("Farolândia")
->setAddressLine1("Rua Silvio do Espírito Santos Seixas")
->setAddressLine2("Ap 001, Cleveland House")
->setAddressStreetNumber("92")
->setAddressZipCode("49030-423")
->setMothersName("Mothers Name")
->setupHolderAccount();
$this->assertTrue(true);
Neste método são exibidas todas as informações do titular da conta.
$presets = $paggcerto->account()->getSetupHolderAccount();
print_r($presets);
São métodos de consulta, que apresentam informações complementares para a criação da conta titular. Para acessar estes métodos não precisam estar autenticado.
Nesta consulta são retornados todos os tipos de empresa.
$businessTypes = $paggcerto->businessType()->getRequest();
print_r($businessTypes);
Com a utilização desta consulta são retornadas as informações a respeito das cidades que estão localizadas no estado informado no endpoint.
$cities = $paggcerto->city()->getRequest(["SE"]);
print_r($cities);
É retornada uma lista com informações a respeito das instituições financeiras.
$banks = $paggcerto->bank()->getRequest();
print_r($banks);
Com a utilização desta consulta são retornadas as informações de todos os ramos de atividades.
$businessActivities = $paggcerto->businessActivity()->getRequest();
print_r($businessActivities);
Ao utilizar esta consulta são retornadas as informações a respeito das medias de marketing, que possibilitaram o usuário conhecer a Paggcerto.
$marketingMedias = $paggcerto->marketingMedia()->getRequest();
print_r($marketingMedias);
O primeiro passo após a realização do cadastro da conta do titular é realizar sua autenticação. Nesta etapa será gerado o token de acesso para se conectar com nosso SDK e assim realizar as requisições. O token de acesso é confidencial e recomendamos não compartilhá-lo em ambientes públicos ou com terceiros. A seguir estão descritos os métodos que são responsáveis pela autenticação.
O objetivo da autenticação do usuário é ter como resultado a geração do Token de Acesso. O token gerado para o ambiente sandbox é diferente do token do ambiente de produção.
$paggcerto = new Paggcerto(new Auth("[email protected]", "12345678", "applicationId"));
A finalidade deste método é realizar a autenticação do usuário que foi cadastrado pelo titular da conta através do Hash que foi enviado ao e-mail desse usuário. Como resultado, é gerado o token temporário, que deve ser utilizado para Criar Nova Senha.
$paggcerto = new Paggcerto(new AuthHash("ZAyCNFfbBWp1wYTB6OJx2e1sd45156d4fewfcdsvcd454"));
Através deste método, o parceiro gera o token para o lojista sem a necessidade de conhecer a sua senha, passando apenas o id do lojista que se deseja gerar o token.
$paggcerto = new Paggcerto(new AuthHashByPartner("holderId"));
Para acessar os métodos complementares não é necessário estar autenticado. Abaixo está o exemplo:
$paggcerto = new Paggcerto(new NoAuth());
O titular da conta pode configurar perfis de usuários para que outras pessoas possam realizar operações na conta do titular. O perfil determina quais funcionalidades (métodos ou recursos) os usuários podem ter acesso. Abaixo estão os exemplos para o gerenciamento destes perfis.
$createdRole = $paggcerto->role()
->setName("Administrador")
->createRole();
print_r($createdRole);
Para atualizar o perfil é necessário informar o identificador único roleId
do perfil desejado.
$updatedRole = $paggcerto->role()
->setName("Admin Update Test")
->setActive(true)
->setRoleId("a0b1")
->updateRole();
print_r($updatedRole);
$list = $paggcerto->role()
->rolesList();
print_r($list);
$listWithFilters = $paggcerto->role()
->setLength(2)
->setIndex(2)
->rolesList();
print_r($listWithFilters);
Este método é utilizado quando se deseja buscar um perfil específico, para isso o roleId
do perfil deve ser informado.
$search = $paggcerto->role()
->setRoleId("a0b1")
->searchRole();
print_r($search);
O roleId
deve ser informado para desativar o perfil.
$deactivate = $paggcerto->role()
->setRoleId("a0b1")
->deactivateRole();
print_r($deactivate);
Informar o roleId
para ativar o perfil.
$activate = $paggcerto->role()
->setRoleId("a0b1")
->activateRole();
print_r($activate);
Para remover um perfil deve ser informado o roleId
.
$delete = $paggcerto->role()
->setRoleId("a0b1")
->deleteRole();
print_r($delete);
Para que o usuário acesse as funcionalidades é necessário que ele esteja vinculado à um perfil e que este perfil tenha as devidas permissões.
Para conceder as permissões é necessário informar o roleId
.
$paggcerto->roleConcept()
->setRoleId("a0b1")
->setScopes(["account.users.edit", "account.users.readonly"])
->roleGrantPermission();
O roleId
deve ser informado para remover a permissão.
$paggcerto->roleConcept()
->setRoleId("a0b1")
->setScopes(["account.users.edit", "account.users.readonly"])
->roleRevokePermission();
A seguir serão apresentados todos os métodos com funcionalidades para o gerenciamento dos usuários. Os usuários são pessoas que realizam operações em uma conta com a permissão do titular, é necessário que o usuário esteja associado a um perfil.
Com a utilização deste método um novo usuário é criado. Os usuários recém-criados receberão por e-mail o hash de autenticação, que será utilizado no método autenticar com Hash.
Para acessar esse método é necessário ter a seguinte permissão: account.users.edit
$createdUser = $paggcerto->user()
->setRoleId("a0b1")
->setFullName("João Mateus dos Santos")
->setEmail("[email protected]")
->setTaxDocument("123.123.123-87")
->setAppUrl("http://meuaplicativo.com.br")
->createUser();
print_r($createdUser);
Com a utilização deste método os dados do usuário serão atualizados, para isso é necessário informar o ID
do usuário desejado.
Para ter acesso a esse método, é necessário ter a seguinte permissão: account.users.edit.
$updatedUser = $paggcerto->user()
->setId("d2e2")
->setRoleId("a0b1")
->setFullName("João Mateus dos Santos")
->setEmail("[email protected]")
->setTaxDocument("123.123.123-87")
->updateUser();
print_r($updatedUser);
O objetivo deste método é listar todos os usuários cadastrados.
Para ter acesso a esse método, é necessário ter a seguinte permissão: account.users.readonly
$list = $paggcerto->user()
->usersList();
print_r($list);
$listWithFilters = $paggcerto->user()
->setFullName("João Mateus")
->setEmail("[email protected]")
->setTaxDocument("123.123.123-87")
->setLength(2)
->setIndex(2)
->usersList();
print_r($listWithFilters);
Esse método deve ser utilizado quando se deseja pesquisar um usuário específico, para isso o ID
do usuário deve ser informado.
Para ter acesso a esse método, é necessário ter a seguinte permissão: account.users.readonly
$search = $paggcerto->user()
->setId("d2e2")
->searchUser();
print_r($search);
O ID
deve ser informado para desativar o usuário.
Para ter acesso a esse método, é necessário ter a seguinte permissão: account.users.edit
$deactivate = $paggcerto->user()
->setId("d2e2")
->deactivateUser();
print_r($deactivate);
Informar o ID
para ativar o usuário.
Para ter acesso a esse método, é necessário ter a seguinte permissão: account.users.edit
$activate = $paggcerto->user()
->setId("d2e2")
->activateUser();
print_r($activate);
Pagamento com cartão pode ser realizado a vista ou parcelado, utilizando múltiplos cartões e com possibilidade de split de pagamento. Cada transação de cartão deve obedecer requisitos pré-determinados: validade, limite financeiro do cartão, nome do titular do cartão e código de segurança. Nesta seção são exibidos os métodos para sua utilização.
A tabela abaixo apresenta alguns cartões para a realização de testes em nosso ambiente sandbox. Neste ambiente o nome do titular, a data de validade e o cvv podem ser fictícios:
Bandeira | Nº do cartão |
---|---|
AMEX | 349881342411264 |
DINERSCLUB | 30386724055675 |
ELO | 6363693078504487 |
HIPERCARD | 6062820640453968 |
MASTERCARD | 5111925270937702 |
VISA | 4929915748910899 |
Esse método retorna uma lista com todas as bandeiras aceitas pela Paggcerto e suas respectivas regras de processamento (expressões regulares).
$result = $paggcerto->cardPayment()
->getCardsBrands();
print_r($result->bins());
Ao utilizar este método é calculado o valor que o titular irá receber de acordo com o valor cobrado para um pagamento com cartão.
$result = $paggcerto->cardPayment()
->setAmount(100)
->setInstallments(2)
->setCardBrand("visa")
->setCredit(true)
->setCustomerPaysFee(true)
->setPinpad(false)
->paySimulate();
print_r($result);
Esse método permite que o usuário realize um pagamento utilizando um ou mais cartões. Quando o valor do pagamento não for atingido, ele pode ser continuado com novos cartões através do método Continuar Pagamento.
Em addCard
devem ser inseridas as seguintes informações: Nome do titular impreso no cartão, número do cartão, mês da validade, ano da validade, valor cobrado (esse valor não pode ser inferior a R$ 1,00 para venda à vista ou inferior a R$ 5,00 para venda parcelada), CVV, número da parcelas, informar a modalidade da venda: credito (true
) ou débito (false
).
Para ter acesso a esse método, é necessário ter a seguinte permissão: payments.create.
$result = $paggcerto->cardPayment()
->setAmount(158.35)
->addCard("Rodrigo Alves", "5111925270937702", 12, 2018, 158.35, "035", 1, true)
->setPaymentDeviceSerialNumber("8000151509001953")
->setPaymentDeviceModel("mp5")
->pay();
print_r($result);
Com a utilização desse método o usuário poderá realizar um pagamento pré-autorizado, ou seja, a autorização do pagamento será realizada de forma manual através do método Capturar Pagamento. Sendo assim, o valor informado será temporariamente bloqueado no cartão até que seja finalizada a autorização do pagamento. Para esse tipo de pagamento, o campo isAuthorizedSale estar com o valor true e deve ser informado a quantidade de dias limite para a captura do pagamento no campo setDaysLimitAuthorization. Se este campo não for informado e o isAuthorizedSale for true, será considerado a quantidade de 29 dias.
Para ter acesso a esse método, é necessário ter a seguinte permissão: payments.create.
$result = $paggcerto->cardPayment()
->setAmount(158.35)
->addCard("Rodrigo Alves", "5111925270937702", 12, 2018, 158.35, "035", 1, true)
->setPaymentDeviceSerialNumber("8000151509001953")
->setPaymentDeviceModel("mp5")
->isAuthorizedSale(true)
->setDaysLimitAuthorization(28)
->pay();
print_r($result);
A finalidade desse método é permitir que o usuário continue o pagamento que não foi finalizado (o valor do pagamento não foi atingido).
Para ter acesso a esse método, é necessário ter a seguinte permissão: payments.create.
$result = $paggcerto->cardPayment()
->setPaymentId($payment->id)
->addCard("Maria Alves", "6363693078504487", 5, 2020, 50, "587", 1, false)
->payContinue();
print_r($result);
O objetivo desse método é permitir a captura manual de um pagamento em duas etapas:
- O campo isAuthorizedSale do método Pagamento com pré-captura deve ser igual a true.
- Utilizar esse método para a captura efetiva do pagamento.
Somente o titular possui acesso a esse método.
$result = $paggcerto->cardPayment()
->setPaymentId($payment->id)
->setAmount(158.35)
->paymentCapture();
print_r($result);
O objetivo deste método é enviar o comprovante da transação para o cliente.
Para ter acesso a esse método, é necessário ter a seguinte permissão: payments.create.
$receipt = $paggcerto->cardPayment()
->setNsu("1005")
->setEmail("[email protected]")
->sendReceipt();
Boleto é um título de cobrança que pode ser pago em qualquer instituição ou estabelecimento conveniado. Além de indicar a data de vencimento, podem conter informações sobre desconto e/ou acréscimo de multa e juros e outras instruções. Após a emissão do boleto e se o e-mail e/ou telefone celular do pagador for informado ele poderá receber notificações, essas notificações são enviadas a partir das 11 horas de acordo com o horário de Brasília.
A tabela a seguir apresenta as regras para o envio das notificações:
Notificação | Regras | Comunicação |
---|---|---|
Boleto à vencer | A notificação é enviada 3 dias antes do dia do vencimento ou no mesmo dia da emissão, caso o boleto seja emitido em até 3 dias antes do vencimento | Do titular para o pagador |
Boleto vencido | A notificação é enviada 1, 5 e 10 dias após vencimento | Do titular para o pagador |
Boleto pago | A notificação é enviada no mesmo dia da liquidação do boleto (após o processamento do arquivo de retorno enviado pelo banco) | Do titular para o pagador |
Boleto cancelado | A notificação é enviada no mesmo dia do cancelamento do boleto | Do titular para o pagador |
Boleto expirado | A notificação é enviada na data do cancelamento (baixa automática) programada junto ao banco no momento do registro | Do titular para o pagador |
O ojetivo deste método é realizado o pagamento com boletos. Por meio dele pode ser gerado apenas um ou mais boletos (carnê).
Para ter acesso a esse método, é necessário ter a seguinte permissão: payments.create
$dateDue = (new DateTime())->add(new DateInterval("P10D"));
$result = $paggcerto->bankSlipPayment()
->setDiscount(2.55)
->setDiscountDays(30)
->setFines(5)
->setInterest(3)
->setAcceptedUntil(15)
->addPayer("Rodrigo Alves", "953.262.300-03")
->addInstallment($dateDue->format("Y-m-d"), 100)
->setInstructions("PHP SDK")
->setNote("Descrição")
->pay();
print_r($result);
Um pagamento é automaticamente finalizado quando a soma dos valores pagos atinge o valor esperado para o pagamento. Porém, também é possível finalizar um pagamento sem que a soma de todas as transações ou boletos pagos atingam o valor esperado para esse pagamento devido a:
Pagamentos podem ser concluídos utilizando outra forma de pagamento (dinheiro, cheque, entre outros);
A contratação do serviço pode ser cancelada, dessa forma os boletos futuros podem ser cancelados, porém, mantendo o que já foi pago.
Para ter acesso a esse método, é necessário ter a seguinte permissão: payments.create.
$conclusion = $paggcerto->payment()
->setPaymentId("a0b1")
->setNote("O valor de R$ 50,00 foi pago em dinheiro.")
->payFinalize();
print_r($conclusion);
O cancelamento somente será efetuado se for possível cancelar todas as transações com cartão e todos os boletos. Transações com cartão somente podem ser canceladas se forem realizadas na mesma data do seu processamento. Boletos podem ser cancelados desde que estejam pendentes ou vencidos, desta forma, não é possível cancelar boletos que já foram pagos.
Para ter acesso a esse método, é necessário ter a seguinte permissão: payments.create.
$result = $paggcerto->payment()
->setPaymentId("a0b1")
->paymentCancel();
print_r($result);
O cancelamento da transação do cartão somente será efetuado se for realizado na mesma data do seu processamento.
Para ter acesso a esse método, é necessário ter a seguinte permissão: payments.create.
$result = $paggcerto->cardPayment()
->setNsu("1005")
->cardTransactionCancel();
print_r($result);
O cancelamento do boleto somente será efetuado se seu pagamento estiver pendente.
Para ter acesso a esse método, é necessário ter a seguinte permissão: payments.create.
$result = $paggcerto->bankSlipPayment()
->setNumber("10000002345")
->cancel();
print_r($result);
Este método deve ser utilizado para exibir todas as informações a respeito do pagamento desejado.
Para ter acesso a esse método, é necessário ter a seguinte permissão: payments.readonly
$result = $paggcerto->reportsManagement()
->setPaymentId($payment->id)
->getPaymentDetails();
print_r($result);
A finalidade deste método é cadastrar os recebedores para split de pagamento. Somente o titular da conta pode cadastrar recebedores.
$createSplit = $paggcerto->split()
->setName("Administrador")
->setHolderName("Mariana Fulano de Tal")
->setTaxDocument("578.585.110-50")
->setAddressCityCode("2800308")
->setAddressDistrict("Smallville")
->setAddressLine1("Rua do Talon")
->setAddressLine2("Ap 001, Cleveland House")
->setAddressStreetNumber("6000")
->setAddressZipCode("49030-620")
->setBankAccountBankNumber("001")
->setBankAccountNumber("31232156132-12")
->setBankAccountBranchNumber("0031")
->setBankAccountType("corrente")
->setTransferDays(32)
->setAnticipatedTransfer(true)
->createSplitter();
print_r($createSplit);
O objetivo deste método é atualizar as informações do recebedor especificado no endpoint. Somente o titular da conta pode atualizar recebedores.
$updateSplit = $paggcerto->split()
->setSplitterId($id)
->setName("Administrado")
->setHolderName("Mariana Fulano de Tal")
->setTaxDocument("029.378.350-07")
->setAddressCityCode("2800308")
->setAddressDistrict("Smallville")
->setAddressLine1("Rua do Talon")
->setAddressLine2("Ap 001, Cleveland House")
->setAddressStreetNumber("6000")
->setAddressZipCode("49030-620")
->setBankAccountBankNumber("001")
->setBankAccountNumber("31232156132-12")
->setBankAccountBranchNumber("0031")
->setBankAccountType("corrente")
->setTransferDays(32)
->setAnticipatedTransfer(false)
->updateSplitter();
print_r($updateSplit);
Esse método deve ser utilizado quando se deseja pesquisar um recebedor específico. Somente o titular da conta pode pesquisar recebedor.
$split = $paggcerto->split()
->setSplitterId($id)
->searchSplitter();
print_r($split);
O objetivo deste método é listar todos os recebedores cadastrados. Somente o titular da conta pode listar recebedores.
$split = $paggcerto->split()
->setName("Fulano")
->splittersList();
print_r($split);