Descrição:
Pagamento com cartão
Passo a passo para gerar uma cobrança de cartão de crédito na API Gerencianet
Atualmente disponibilizamos dois procedimentos para a criação de uma transação do tipo cartão de crédito, na primeira delas o titulo é criado em um passo único, assim fora convencionado como One Step. A segunda opção de criação da transação se da em dois passos, sendo assim convencionada como Two Steps. Ambos os fluxos estão detalhados a seguir:
1. Criação de transação por cartão de crédito em One Step (Um passo)
Importante
Para que a criação de transações via One Step ocorra normalmente é necessário atualizar sua SDK. Todos os arquivos necessários para tal estão disponíveis através de nosso repositório e em nossa documentação.
No caso de transações com cartão de crédito, será realizada uma etapa anterior a criação onde ocorre a transmissão (via JavaScript, no browser), de forma segura, dos dados do cartão e retornando um payment_token, e na segunda etapa seu backend envia o restante das informações da transação e o payment_token obtido na primeira etapa.
É importante frisar que não é possível efetuar pagamento com cartão de crédito sem obter o payment_token da transação, por isso, é imprescindível a realização dos procedimentos do item 1.1 deste documento (obter o payment_token), e só depois passar para o item 1.2 (que é de fato o pagamento com cartão).
1.1. Obtenção do payment_token
Inicialmente, vamos realizar a primeira etapa, que é a obtenção do payment_token. Para tal, você necessitará de um código JavaScript específico de sua conta Gerencianet. Para gerá-lo, siga os passos :
- Efetue login em sua conta Gerencianet e acesse
API (Lateral a esquerda)
- Copie seu
Identificador de Conta (veja onde)
- Cole no campo abaixo e clique no botão
Gerar
É importante frisar que é obtido via JavaScript, no browser, de forma segura, os dados do cartão e retorna um payment_token, que é a representação dos dados enviados.
Lembre-se que, após informar seu identificador de conta, serão gerados 2 (dois) códigos JavaScript distintos.
Copie e utilize o código referente ao ambiente desejado, atentando-se às diferenças do ambiente de "Homologação" e "Produção".
Para aplicações web, você deve copiar o script, específico da sua conta, e utilizar a nossa biblioteca Javascript, conforme o snippet abaixo. Se você possui um app mobile, confira como proceder acessando nossa página no GitHub para Android e/ou iOS.
Adicionalmente, esclarecemos que uma conta Gerencianet não possui um payment_token - ele é diferente e criado para cada cobrança gerada por cartão de crédito. Ele representa os dados do cartão do pagador e é obtido pela função getPaymentToken. Além disso, cabe frisar que o payment_token pode ser utilizado uma única vez, portanto, não é possível utilizá-lo para cobrar de forma recorrente.
a) Obtendo um "payment_token" ( getPaymentToken )
$gn.ready(function (checkout) {
checkout.getPaymentToken(
{
brand: 'visa', // bandeira do cartão
number: '4012001038443335', // número do cartão
cvv: '123', // código de segurança
expiration_month: '05', // mês de vencimento
expiration_year: '2021' // ano de vencimento
},
function (error, response) {
if (error) {
// Trata o erro ocorrido
console.error(error);
} else {
// Trata a resposta
console.log(response);
}
}
);
});
b) Obtendo informações sobre parcelamentos ( getInstallments )
$gn.ready(function (checkout) {
checkout.getInstallments(
50000, // valor total da cobrança
'visa', // bandeira do cartão
function (error, response) {
if (error) {
// Trata o erro ocorrido
console.log(error);
} else {
// Trata a respostae
console.log(response);
}
}
);
});
c) Atributos relacionados ao envio de dados do cartão:
$gn.ready ( callback )
Parâmetro
Descrição
Tipo
callback
Função de inicialização que possibilita a chamada das funções getPaymentToken e getInstallments.
Parâmetro(s) de callback
object // Objeto que recebe as instâncias das outras funções.
Function
getPaymentToken ( card_data, callback )
Parâmetro
Descrição
card_data
Objeto que contém os dados do cartão.
As propriedades desse objeto são:
brand // Bandeira do cartão
number // Número do cartão sem formatação
cvv // Código de segurança do cartão
expiration_month // Mês de expiração do cartão no formato "MM"
expiration_year // Ano de expiração do cartão no formato "YYYY"
Object
callback
Função que recebe a resposta da Gerencianet.
Parâmetro(s) de callback:
error // Se não foi possível gerar o payment_token, os erros serão retornados neste parâmetro.
response // Recebe os dados que representam o cartão de crédito: payment_token e card_mask
Function
getInstallments ( total, brand, callback )
Parâmetro
Descrição
Tipo
total
Valor total da cobrança, incluindo fretes, em centavos.
Por exemplo: R$ 230,90 equivale a 23090.
Integer
brand
Bandeira do cartão que deseja-se obter os valores de parcelas.
Possíveis valores:
visa // Bandeira Visa
mastercard // Bandeira MasterCard
amex // Bandeira AmericanExpress
elo // Bandeira Elo
hipercard // Bandeira Hipercard
String
callback
Função que recebe a resposta da Gerencianet.
Parâmetro(s) de callback:
error // Se não foi possível obter dados sobre o pagamento, os erros serão retornados neste parâmetro.
response // Recebe os dados relacionados ao tipo de pagamento consultado.
Function
1.2. Pagando com cartão
Agora que o payment_token já foi obtido através do código Javascript, vamos prosseguir com o pagamento com cartão de crédito.
Nesta etapa, seu backend envia o restante das informações da transação e o payment_token obtido na primeira etapa.
Ao pagar uma transação por cartão de crédito, o status é alterado de new para waiting. Isso significa que a transação está associada a uma forma de pagamento e que está aguardando a confirmação do pagamento.
Assim que o pagamento for confirmado, a transação terá o status alterado de waiting para paid. Mas, se por alguma razão não for possível confirmar o pagamento, o status será alterado para unpaid.
O exemplo abaixo mostra como isto pode ser feito, utilizando as SDK's disponíveis:
require __DIR__.'/../../autoload.php'; //Caminho da SDK
use Gerencianet\Exception\GerencianetException;
use Gerencianet\Gerencianet;
$clientId = 'informe_seu_client_id'; // insira seu Client_Id, conforme o ambiente (Des ou Prod)
$clientSecret = 'informe_seu_client_secret'; // insira seu Client_Secret, conforme o ambiente (Des ou Prod)
$options = [
'client_id' => $clientId,
'client_secret' => $clientSecret,
'sandbox' => true // altere conforme o ambiente (true = Homologação e false = producao)
];
$paymentToken = '83d52dbd590d9ebc991938c711ddd31f65df89a5'; // payment_token obtido no procedimento através do Javascript único por conta Gerencianet
$item_1 = [
'name' => 'Item 1', // nome do item, produto ou serviço
'amount' => 1, // quantidade
'value' => 3000 // valor (1000 = R$ 10,00) (Obs: É possível a criação de itens com valores negativos. Porém, o valor total da fatura deve ser superior ao valor mínimo para geração de transações.)
];
$items = [
$item_1
];
$metadata = array('notification_url'=>'https://SuaUrl/16rpx6y1');
$customer = [
'name' => 'Gorbadoc Oldbuck', // nome do cliente
'cpf' => '04267484171', // cpf do cliente
'phone_number' => '5144916523', // telefone do cliente
'email' => '[email protected]', // endereço de email do cliente
'birth' => '1977-01-15' // data de nascimento do cliente
];
$billingAddress = [
'street' => 'Av JK',
'number' => 909,
'neighborhood' => 'Bauxita',
'zipcode' => '35400000',
'city' => 'Ouro Preto',
'state' => 'MG'
];
$discount = [
'type' => 'currency',
'value' => 599
];
$credit_card = [
'customer' => $customer,
'installments' => 1, // número de parcelas em que o pagamento deve ser dividido
'discount' =>$discount,
'billing_address' => $billingAddress,
'payment_token' => $paymentToken,
'message' => 'teste\nteste\nteste\nteste'
];
$payment = [
'credit_card' => $credit_card // forma de pagamento (credit_card = cartão)
];
$body = [
'items' => $items,
'metadata' =>$metadata,
'payment' => $payment
];
try {
$api = new Gerencianet($options);
$pay_charge = $api->oneStep([],$body);
echo '<pre>';
print_r($pay_charge);
echo '<pre>';
} catch (GerencianetException $e) {
print_r($e->code);
print_r($e->error);
print_r($e->errorDescription);
} catch (Exception $e) {
print_r($e->getMessage());
}
a) Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
"items"
"name"
"value"
"amount"
"marketplace"
"payee_code"
"percentage"
"shippings"
"name"
"value"
"payee_code"
"metadata"
"custom_id"
"notification_url"
"payment"
"credit_card"
"customer"
"name"
"cpf"
"email"
"phone_number"
"birth"
"address"
"street"
"number"
"neighborhood"
"zipcode"
"city"
"complement"
"state"
"juridical_person"
"corporate_name"
"cnpj"
"installments"
"discount"
"type"
"percentage",
"currency"
"value"
"billing_address"
"street"
"number"
"neighborhood"
"zipcode"
"city"
"complement"
"state"
"payment_token"
"message"
b) Atributos que podem ser utilizados para criar uma transação:
Atributo
Descrição
Obrigatório
Tipo
items
Item que está sendo vendido. Uma mesma transação pode possuir ilimitados itens.
Atributos de items
name* // Nome do item, produto ou serviço. Mínimo de 1 caractere e máximo de 255 caracteres (String).
value* // Valor, em centavos. Ex: R$ 10,00 = 1000. Integer.
amount // Quantidade. Integer (padrão: 1)
Sim
Array
shippings
Determina o(s) valor(es) de frete(s) de uma transação. Uma mesma transação pode possuir ilimitados valores de frete.
Atributos de shippings
name* // Rótulo do frete. Máximo de 255 caracteres. String.
value* // Valor do frete, em centavos (1990 equivale a R$19,90). Integer.
payeeCode, // código da conta Gerencianet que receberá o repasse do valor total do frete - refere-se ao "identificador da conta" Gerencianet (onde localizar meu identificador?) (String)
Não
Array
metadata
Define dados específicos da transação.
Atributos de metadata
custom_id // Permite associar uma transação Gerencianet a uma ID específica de seu sistema ou aplicação, permitindo identificá-la caso você possua uma identificação específica e queira mantê-la. Máximo de 255 caracteres. String/null.
notification_url // Endereço de sua URL válida que receberá as notificações de mudanças de status das transações. Máximo de 255 caracteres. String/null.
Não
Object
Objeto Payment
Atributo
Descrição
Obrigatório
Tipo
credit_card
Objeto contendo as informações necessárias para o pagamento via cartão de crédito, como por exemplo, o número de parcelas e os dados do cliente.
Sim
Objeto Credit_Card
Objeto Credit_Card
Atributo
Descrição
Obrigatório
Tipo
customer
Dados pessoais do pagador.
Atributos de customer
name* // nome (String)
cpf* // CPF do cliente (sem pontos, vírgulas ou hífen) (String)
email* // Endereço de email válido do cliente (String)
phone_number* // Telefone válido do cliente, sem caracteres especiais (String)
birth* // Data de Nascimento do cliente (data válida em formato YYYY-MM-DD) (String)
juridical_person // Dados de pessoa jurídica (Object) (mais informações)
Sim
Object
installments
Número de parcelas em que o pagamento deve ser dividido.
Mínimo 1 e máximo 12. Integer.
Não
Integer
discount
Define dados de desconto sobre a cobrança.
Atributos de discount
type*, // Tipo do desconto (String). Valores permitidos:
currency: o desconto será informado em centavos;
percentage: o desconto será informado em porcentagem.
value*, // Valor do desconto (Integer). Se o tipo do desconto for currency, o valor desta tag deverá ser informada pelo integrador em centavos (ou seja, 500 equivale a R$ 5,00). Caso o tipo do desconto seja percentage, o valor deverá ser multiplicado por 100 (ou seja, 1500 equivale a 15%). Exemplos:
1) currency // deve ser informado em centavos, ou seja, se o desconto será de R$ 5,99, o integrador deve informar 599;
2) percentage // deve ser informado em centavos, ou seja, se o desconto é de 15%, o integrador deve informar 1500.
Não
Object
billing_address
Endereço de cobrança (mais informações)
Atributos de billing_address
street* // nome da rua (Object)
number* // número (String/Integer)
neighborhood* // Bairro (String)
zipcode* // CEP (sem pontos ou hífen) (String)
city* // cidade (String)
complement // complemento (String/null)
state* // estado (2 caracteres) (Object)
Sim
Object
payment_token
Token único de pagamento obtido na primeira etapa da geração da transação.
Sim
String
message
Permite incluir no boleto uma "observação", ou em outras palavras, uma mensagem para o cliente. Essa mensagem poderá ser vista nos e-mails relacionados à cobrança, no boleto ou carnê.
Até 4 linhas contendo 100 caracteres em cada linha. String.
O operador \n é utilizado para efetuar a quebra de linha.
Não
String
* valor obrigatório
2. Criação de transação por cartão de crédito em Two Steps (Dois passos)
Nesta opção é necessário que o body da requisição contenha todos os atributos mínimos obrigatórios para a emissão do titulo.
Abaixo temos os exemplos de implementação utilizando as SDK's disponíveis:
2.1. Crie a transação, informando o item/produto/serviço, valor, quantidade, etc;
2.2. Associe à forma de pagamento via cartão, informando o charge_id da transação criada e os dados do cliente;
2.3. Obtenção do payment_token (via JavaScript, único por transação);
2.4. Pagando com cartão.
Por se tratar de pagamento via cartão e envolver dados sensíveis, como dados do cartão de crédito, os procedimentos descritos nos itens 3.1 e 3.2, ou seja, obtenção do payment_token e pagando com cartão, respectivamente, são necessários.
O restante desta página apresenta os procedimentos detalhados, mas você precisa instalar uma de nossas bibliotecas em seu servidor para executar os códigos de exemplo. Certifique-se de que a SDK da Gerencianet foi instalada.
2.1. Criar transação
Primeiramente, precisamos gerar a transação (também chamada de "cobrança"). É neste momento que será informado o nome do item/produto/serviço, valor da transação, quantidade, dentre outras informações possíveis.
Após criá-la, será retornado o charge_id, que é o identificador único da transação e que será utilizado para associar à forma de pagamento.
Assim que essa transação é criada, ela recebe o status new, que significa que a cobrança foi gerada e está aguardando definição da forma de pagamento. Essa cobrança somente terá seu status alterado quando o integrador definir sua forma de pagamento.
Para gerar uma transação, você deve enviar uma requisição POST para a rota /v1/charge.
Caso queira, pode explorar e conhecer mais sobre este recurso usando nosso Playground.
O exemplo abaixo mostra como isto pode ser feito, utilizando as SDK's disponíveis:
require __DIR__.'/../../vendor/autoload.php'; // caminho relacionado a SDK
use Gerencianet\Exception\GerencianetException;
use Gerencianet\Gerencianet;
$clientId = 'informe_seu_client_id'; // insira seu Client_Id, conforme o ambiente (Des ou Prod)
$clientSecret = 'informe_seu_client_secret'; // insira seu Client_Secret, conforme o ambiente (Des ou Prod)
$options = [
'client_id' => $clientId,
'client_secret' => $clientSecret,
'sandbox' => true // altere conforme o ambiente (true = Homologação e false = producao)
];
$item_1 = [
'name' => 'Item 1', // nome do item, produto ou serviço
'amount' => 1, // quantidade
'value' => 1000 // valor (1000 = R$ 10,00) (Obs: É possível a criação de itens com valores negativos. Porém, o valor total da fatura deve ser superior ao valor mínimo para geração de transações.)
];
$item_2 = [
'name' => 'Item 2', // nome do item, produto ou serviço
'amount' => 2, // quantidade
'value' => 2000 // valor (2000 = R$ 20,00)
];
$items = [
$item_1,
$item_2
];
// Exemplo para receber notificações da alteração do status da transação.
// $metadata = ['notification_url'=>'sua_url_de_notificacao_.com.br']
// Outros detalhes em: https://dev.gerencianet.com.br/docs/notificacoes
// Como enviar seu $body com o $metadata
// $body = [
// 'items' => $items,
// 'metadata' => $metadata
// ];
$body = [
'items' => $items
];
try {
$api = new Gerencianet($options);
$charge = $api->createCharge([], $body);
print_r($charge);
} catch (GerencianetException $e) {
print_r($e->code);
print_r($e->error);
print_r($e->errorDescription);
} catch (Exception $e) {
print_r($e->getMessage());
}
a) Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
"id": "/Charge"
"items"
"name"
"value"
"amount"
"marketplace"
"payee_code"
"percentage"
"shippings"
"name"
"value"
"payee_code"
"metadata"
"custom_id"
"notification_url"
Para verificar mais detalhes, acesse aqui e explore em nosso Playground.
b) Atributos que podem ser utilizados para criar uma transação:
Atributo
Descrição
Obrigatório
Tipo
items
Item que está sendo vendido. Uma mesma transação pode possuir ilimitados itens.
Atributos de items
name* // Nome do item, produto ou serviço. Mínimo de 1 caractere e máximo de 255 caracteres (String).
value* // Valor, em centavos. Ex: R$ 10,00 = 1000. Integer.
amount // Quantidade. Integer (padrão: 1)
Sim
Array
shippings
Determina o(s) valor(es) de frete(s) de uma transação. Uma mesma transação pode possuir ilimitados valores de frete.
Atributos de shippings
name* // Rótulo do frete. Máximo de 255 caracteres. String.
value* // Valor do frete, em centavos (1990 equivale a R$19,90). Integer.
payeeCode, // código da conta Gerencianet que receberá o repasse do valor total do frete - refere-se ao "identificador da conta" Gerencianet (onde localizar meu identificador?) (String)
Não
Array
metadata
Define dados específicos da transação.
Atributos de metadata
custom_id // Permite associar uma transação Gerencianet a uma ID específica de seu sistema ou aplicação, permitindo identificá-la caso você possua uma identificação específica e queira mantê-la. Máximo de 255 caracteres. String/null.
notification_url // Endereço de sua URL válida que receberá as notificações de mudanças de status das transações. Máximo de 255 caracteres. String/null.
Não
Object
* valor obrigatório
2.2. Associe à forma de pagamento via cartão
Com a transação criada, vamos associá-la à forma de pagamento desejada, que neste caso, será cartão de crédito. Para tal, deverá ser informado a charge_id obtido no consumo anterior em que foi gerada a transação.
No caso de transações com cartão de crédito, será realizado em duas etapas, sendo a primeira a transmissão (via JavaScript, no browser), de forma segura, os dados do cartão e retornando um payment_token, e na segunda etapa seu backend envia o restante das informações da transação e o payment_token obtido na primeira etapa.
IMPORTANTE - SOBRE O PAYMENT_TOKEN
É importante frisar que não é possível efetuar pagamento com cartão de crédito sem obter o payment_token da transação, por isso, é imprescindível a realização dos procedimentos do item 2.1 deste documento (obter o payment_token), e só depois passar para o item 2.2 (que é de fato o pagamento com cartão).
Para associar à forma de pagamento, você deve enviar uma requisição POST para a rota /v1/charge/:id/pay, onde :id é o charge_id da transação desejada.
Caso queira, pode explorar e conhecer mais sobre este recurso usando nosso Playground.
2.3. Obtenção do payment_token
Inicialmente, vamos realizar a primeira etapa, que é a obtenção do payment_token. Para tal, você necessitará de um código JavaScript específico de sua conta Gerencianet. Para gerá-lo, siga os passos :
- Efetue login em sua conta Gerencianet e acesse
API (Lateral a esquerda)
- Copie seu
Identificador de Conta (veja onde)
- Cole no campo abaixo e clique no botão
Gerar
É importante frisar que é obtido via JavaScript, no browser, de forma segura, os dados do cartão e retorna um payment_token, que é a representação dos dados enviados.
IMPORTANTE
Lembre-se que, após informar seu identificador de conta, serão gerados 2 (dois) códigos JavaScript distintos.
Copie e utilize o código referente ao ambiente desejado, atentando-se às diferenças do ambiente de "Homologação" e "Produção".
Para aplicações web, você deve copiar o script acima, específico da sua conta, e utilizar a nossa biblioteca Javascript, conforme o snippet abaixo. Se você possui um app mobile, confira como proceder acessando nossa página no GitHub para Android e/ou iOS.
Adicionalmente, esclarecemos que uma conta Gerencianet não possui um payment_token - ele é diferente e criado para cada cobrança gerada por cartão de crédito. Ele representa os dados do cartão do pagador e é obtido pela função getPaymentToken. Além disso, cabe frisar que o payment_token pode ser utilizado uma única vez, portanto, não é possível utilizá-lo para cobrar de forma recorrente.
a) Obtendo um "payment_token" ( getPaymentToken )
$gn.ready(function(checkout) {
var callback = function(error, response) {
if(error) {
// Trata o erro ocorrido
console.error(error);
} else {
// Trata a resposta
console.log(response);
}
};
checkout.getPaymentToken({
brand: 'visa', // bandeira do cartão
number: '4012001038443335', // número do cartão
cvv: '123', // código de segurança
expiration_month: '05', // mês de vencimento
expiration_year: '2021' // ano de vencimento
}, callback);
});
b) Obtendo informações sobre parcelamentos ( getInstallments )
$gn.ready(function(checkout){
checkout.getInstallments(50000,'visa', function(error, response){
if(error) {
// Trata o erro ocorrido
console.log(error);
} else {
// Insere o parcelamento no site
}
});
});
c) Atributos relacionados ao envio de dados do cartão:
$gn.ready ( callback )
Parâmetro
Descrição
Tipo
callback
Função de inicialização que possibilita a chamada das funções getPaymentToken e getInstallments.
Parâmetro(s) de callback
object // Objeto que recebe as instâncias das outras funções.
Function
getPaymentToken ( card_data, callback )
Parâmetro
Descrição
Tipo
card_data
Objeto que contém os dados do cartão.
As propriedades desse objeto são:
brand // Bandeira do cartão
number // Número do cartão sem formatação
cvv // Código de segurança do cartão
expiration_month // Mês de expiração do cartão no formato "MM"
expiration_year // Ano de expiração do cartão no formato "YYYY"
Object
callback
Função que recebe a resposta da Gerencianet.
Parâmetro(s) de callback:
error // Se não foi possível gerar o payment_token, os erros serão retornados neste parâmetro.
response // Recebe os dados que representam o cartão de crédito: payment_token e card_mask
Function
getInstallments ( total, brand, callback )
Parâmetro
Descrição
Tipo
total
Valor total da cobrança, incluindo fretes, em centavos.
Por exemplo: R$ 230,90 equivale a 23090.
Integer
brand
Bandeira do cartão que deseja-se obter os valores de parcelas.
Possíveis valores:
visa // Bandeira Visa
mastercard // Bandeira MasterCard
amex // Bandeira AmericanExpress
elo // Bandeira Elo
hipercard // Bandeira Hipercard
String
callback
Função que recebe a resposta da Gerencianet.
Parâmetro(s) de callback:
error // Se não foi possível obter dados sobre o pagamento, os erros serão retornados neste parâmetro.
response // Recebe os dados relacionados ao tipo de pagamento consultado.
Function
2.4. Pagando com cartão
Agora que a transação já foi criada e o payment_token já foi obtido através do código Javascript da primeira etapa, vamos prosseguir com o pagamento com cartão de crédito.
Nesta etapa, seu backend envia o restante das informações da transação e o payment_token obtido na primeira etapa.
Ao pagar uma transação por cartão de crédito, o status é alterado de new para waiting. Isso significa que a transação está associada a uma forma de pagamento e que está aguardando a confirmação do pagamento.
Assim que o pagamento for confirmado, a transação terá o status alterado de waiting para paid. Mas, se por alguma razão não for possível confirmar o pagamento, o status será alterado para unpaid.
O exemplo abaixo mostra como isto pode ser feito, utilizando as SDK's disponíveis:
require __DIR__.'/../../vendor/autoload.php'; // caminho relacionado a SDK
use Gerencianet\Exception\GerencianetException;
use Gerencianet\Gerencianet;
$clientId = 'informe_seu_client_id'; // insira seu Client_Id, conforme o ambiente (Des ou Prod)
$clientSecret = 'informe_seu_client_secret'; // insira seu Client_Secret, conforme o ambiente (Des ou Prod)
$options = [
'client_id' => $clientId,
'client_secret' => $clientSecret,
'sandbox' => true // altere conforme o ambiente (true = Homologação e false = producao)
];
// $charge_id refere-se ao ID da transação gerada anteriormente
$params = [
'id' => $charge_id
];
$paymentToken = '6426f3abd8688639c6772963669bbb8e0eb3c319'; // payment_token obtido na 1ª etapa (através do Javascript único por conta Gerencianet)
$customer = [
'name' => 'Gorbadoc Oldbuck', // nome do cliente
'cpf' => '94271564656' , // cpf do cliente
'email' => '[email protected]' , // endereço de email do cliente
'phone_number' => '5144916523' // telefone do cliente
'birth' => '1990-05-20' // data de nascimento do cliente
];
$billingAddress = [
'street' => 'Street 3',
'number' => 10,
'neighborhood' => 'Bauxita',
'zipcode' => '35400000',
'city' => 'Ouro Preto',
'state' => 'MG',
];
$creditCard = [
'installments' => 1, // número de parcelas em que o pagamento deve ser dividido
'billing_address' => $billingAddress,
'payment_token' => $paymentToken,
'customer' => $customer
];
$body = [
'payment' => $payment
];
$payment = [
'credit_card' => $creditCard // forma de pagamento (credit_card = cartão)
];
try {
$api = new Gerencianet($options);
$charge = $api->payCharge($params, $body);
print_r($charge);
} catch (GerencianetException $e) {
print_r($e->code);
print_r($e->error);
print_r($e->errorDescription);
} catch (Exception $e) {
print_r($e->getMessage());
}
a) Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
"id": "/Pay",
"payment"
"credit_card"
"customer"
"name"
"cpf"
"email"
"phone_number"
"birth"
"address"
"street"
"number"
"neighborhood"
"zipcode"
"city"
"complement"
"state"
"juridical_person"
"corporate_name"
"cnpj"
"installments"
"discount"
"type"
"percentage",
"currency"
"value"
"billing_address"
"street"
"number"
"neighborhood"
"zipcode"
"city"
"complement"
"state"
"payment_token"
"message"
Para verificar mais detalhes, acesse aqui e explore em nosso Playground.
b) Atributos relacionados ao pagamento com cartão de crédito:
Parâmetros da url
Atributo
Descrição
Obrigatório
Tipo
id
Identificador da transação (charge_id)
Sim
Objeto ID
Objeto ID
Atributo
Descrição
Obrigatório
Tipo
payment
Tag raiz
Sim
Objeto Payment
Objeto Payment
Atributo
Descrição
Obrigatório
Tipo
credit_card
Objeto contendo as informações necessárias para o pagamento via cartão de crédito, como por exemplo, o número de parcelas e os dados do cliente.
Sim
Objeto Credit_Card
Objeto Credit_Card
Atributo
Descrição
Obrigatório
Tipo
customer
Dados pessoais do pagador.
Atributos de customer
name* // nome (String)
cpf* // CPF do cliente (sem pontos, vírgulas ou hífen) (String)
email* // Endereço de email válido do cliente (String)
phone_number // Telefone válido do cliente, sem caracteres especiais (String)
birth* // Data de Nascimento do cliente (data válida em formato YYYY-MM-DD) (String)
juridical_person // Dados de pessoa jurídica (Object) (mais informações)
Sim
Object
installments
Número de parcelas em que o pagamento deve ser dividido.
Mínimo 1 e máximo 12. Integer.
Não
Integer
discount
Define dados de desconto sobre a cobrança.
Atributos de discount
type*, // Tipo do desconto (String). Valores permitidos:
currency: o desconto será informado em centavos;
percentage: o desconto será informado em porcentagem.
value*, // Valor do desconto (Integer). Se o tipo do desconto for currency, o valor desta tag deverá ser informada pelo integrador em centavos (ou seja, 500 equivale a R$ 5,00). Caso o tipo do desconto seja percentage, o valor deverá ser multiplicado por 100 (ou seja, 1500 equivale a 15%). Exemplos:
1) currency // deve ser informado em centavos, ou seja, se o desconto será de R$ 5,99, o integrador deve informar 599;
2) percentage // deve ser informado em centavos, ou seja, se o desconto é de 15%, o integrador deve informar 1500.
Não
Object
billing_address
Endereço de cobrança (mais informações)
Atributos de billing_address
street* // nome da rua (Object)
number* // número (String/Integer)
neighborhood* // Bairro (String)
zipcode* // CEP (sem pontos ou hífen) (String)
city* // cidade (String)
complement // complemento (String/null)
state* // estado (2 caracteres) (Object)
Sim
Object
payment_token
Token único de pagamento obtido na primeira etapa da geração da transação.
Sim
String
message
Permite incluir no boleto uma "observação", ou em outras palavras, uma mensagem para o cliente. Essa mensagem poderá ser vista nos e-mails relacionados à cobrança, no boleto ou carnê.
Até 4 linhas contendo 100 caracteres em cada linha. String.
O operador \n é utilizado para efetuar a quebra de linha.
Não
String
* valor obrigatório
Pagamento realizado como Pessoa Jurídica (PJ)
O cliente associado à transação pode ser uma Pessoa Jurídica. Nesse caso, devem ser informados a Razão Social e o CNPJ da empresa pagadora dentro do atributo juridical_person.
Veja detalhes neste link sobre como gerar um pagamento cuja forma de pagamento seja "cartão de crédito" para um cliente que seja Pessoa Jurídica (PJ).
Relação de todos os possíveis status de uma transação
Todas as transações possuem status, que representa a "situação" dessa transação. Portanto, é importante conhecer os possíveis status na API para fornecer as devidas tratativas em seu sistema.
Confira neste link todos os detalhes dos possíveis status das transações.
Callbacks (notificações) das transações da API para seu sistema
As notificações permitem que você seja informado quando uma transação tiver seu status alterado. Dessa forma, você poderá identificar quando uma cobrança for paga, por exemplo.
Confira neste link todos os detalhes sobre como implementar a sua URL de notificação.
3. Outros endpoints
Existem outros endpoints e métodos relacionados a pagamento via cartão de crédito que estão disponíveis na API e podem ser explorados pelo integrador. Confira a relação completa:
Pagamento com cartão
Passo a passo para gerar uma cobrança de cartão de crédito na API Gerencianet
Atualmente disponibilizamos dois procedimentos para a criação de uma transação do tipo cartão de crédito, na primeira delas o titulo é criado em um passo único, assim fora convencionado como One Step. A segunda opção de criação da transação se da em dois passos, sendo assim convencionada como Two Steps. Ambos os fluxos estão detalhados a seguir:
1. Criação de transação por cartão de crédito em One Step (Um passo)
Importante
Para que a criação de transações via One Step ocorra normalmente é necessário atualizar sua SDK. Todos os arquivos necessários para tal estão disponíveis através de nosso repositório e em nossa documentação.
No caso de transações com cartão de crédito, será realizada uma etapa anterior a criação onde ocorre a transmissão (via JavaScript, no browser), de forma segura, dos dados do cartão e retornando um payment_token, e na segunda etapa seu backend envia o restante das informações da transação e o payment_token obtido na primeira etapa.
É importante frisar que não é possível efetuar pagamento com cartão de crédito sem obter o payment_token da transação, por isso, é imprescindível a realização dos procedimentos do item 1.1 deste documento (obter o payment_token), e só depois passar para o item 1.2 (que é de fato o pagamento com cartão).
1.1. Obtenção do payment_token
Inicialmente, vamos realizar a primeira etapa, que é a obtenção do payment_token. Para tal, você necessitará de um código JavaScript específico de sua conta Gerencianet. Para gerá-lo, siga os passos :
- Efetue login em sua conta Gerencianet e acesse
API(Lateral a esquerda) - Copie seu
Identificador de Conta(veja onde) - Cole no campo abaixo e clique no botão
Gerar
É importante frisar que é obtido via JavaScript, no browser, de forma segura, os dados do cartão e retorna um payment_token, que é a representação dos dados enviados.
Lembre-se que, após informar seu identificador de conta, serão gerados 2 (dois) códigos JavaScript distintos.
Copie e utilize o código referente ao ambiente desejado, atentando-se às diferenças do ambiente de "Homologação" e "Produção".
Para aplicações web, você deve copiar o script, específico da sua conta, e utilizar a nossa biblioteca Javascript, conforme o snippet abaixo. Se você possui um app mobile, confira como proceder acessando nossa página no GitHub para Android e/ou iOS.
Adicionalmente, esclarecemos que uma conta Gerencianet não possui um payment_token - ele é diferente e criado para cada cobrança gerada por cartão de crédito. Ele representa os dados do cartão do pagador e é obtido pela função getPaymentToken. Além disso, cabe frisar que o payment_token pode ser utilizado uma única vez, portanto, não é possível utilizá-lo para cobrar de forma recorrente.
a) Obtendo um "payment_token" ( getPaymentToken )
$gn.ready(function (checkout) { checkout.getPaymentToken( { brand: 'visa', // bandeira do cartão number: '4012001038443335', // número do cartão cvv: '123', // código de segurança expiration_month: '05', // mês de vencimento expiration_year: '2021' // ano de vencimento }, function (error, response) { if (error) { // Trata o erro ocorrido console.error(error); } else { // Trata a resposta console.log(response); } } ); });
b) Obtendo informações sobre parcelamentos ( getInstallments )
$gn.ready(function (checkout) { checkout.getInstallments( 50000, // valor total da cobrança 'visa', // bandeira do cartão function (error, response) { if (error) { // Trata o erro ocorrido console.log(error); } else { // Trata a respostae console.log(response); } } ); });
c) Atributos relacionados ao envio de dados do cartão:
$gn.ready ( callback )
| Parâmetro | Descrição | Tipo |
|---|---|---|
|
|
Função de inicialização que possibilita a chamada das funções getPaymentToken e getInstallments. Parâmetro(s) de callback
object // Objeto que recebe as instâncias das outras funções.
|
Function |
getPaymentToken ( card_data, callback )
| Parâmetro | Descrição | |
|---|---|---|
|
|
Objeto que contém os dados do cartão. As propriedades desse objeto são:
brand // Bandeira do cartãonumber // Número do cartão sem formataçãocvv // Código de segurança do cartãoexpiration_month // Mês de expiração do cartão no formato "MM"expiration_year // Ano de expiração do cartão no formato "YYYY"
|
Object |
|
|
Função que recebe a resposta da Gerencianet. Parâmetro(s) de callback:
error // Se não foi possível gerar o payment_token, os erros serão retornados neste parâmetro.
response // Recebe os dados que representam o cartão de crédito: payment_token e card_mask
|
Function |
getInstallments ( total, brand, callback )
| Parâmetro | Descrição | Tipo |
|---|---|---|
|
|
Valor total da cobrança, incluindo fretes, em centavos.
Por exemplo: R$ 230,90 equivale a 23090.
|
Integer |
|
|
Bandeira do cartão que deseja-se obter os valores de parcelas. Possíveis valores:
visa // Bandeira Visa
mastercard // Bandeira MasterCard
amex // Bandeira AmericanExpress
elo // Bandeira Elo
hipercard // Bandeira Hipercard
|
String |
|
|
Função que recebe a resposta da Gerencianet. Parâmetro(s) de callback:
error // Se não foi possível obter dados sobre o pagamento, os erros serão retornados neste parâmetro.
response // Recebe os dados relacionados ao tipo de pagamento consultado.
|
Function |
1.2. Pagando com cartão
Agora que o payment_token já foi obtido através do código Javascript, vamos prosseguir com o pagamento com cartão de crédito.
Nesta etapa, seu backend envia o restante das informações da transação e o payment_token obtido na primeira etapa.
Ao pagar uma transação por cartão de crédito, o status é alterado de new para waiting. Isso significa que a transação está associada a uma forma de pagamento e que está aguardando a confirmação do pagamento.
Assim que o pagamento for confirmado, a transação terá o status alterado de waiting para paid. Mas, se por alguma razão não for possível confirmar o pagamento, o status será alterado para unpaid.
O exemplo abaixo mostra como isto pode ser feito, utilizando as SDK's disponíveis:
require __DIR__.'/../../autoload.php'; //Caminho da SDK use Gerencianet\Exception\GerencianetException; use Gerencianet\Gerencianet; $clientId = 'informe_seu_client_id'; // insira seu Client_Id, conforme o ambiente (Des ou Prod) $clientSecret = 'informe_seu_client_secret'; // insira seu Client_Secret, conforme o ambiente (Des ou Prod) $options = [ 'client_id' => $clientId, 'client_secret' => $clientSecret, 'sandbox' => true // altere conforme o ambiente (true = Homologação e false = producao) ]; $paymentToken = '83d52dbd590d9ebc991938c711ddd31f65df89a5'; // payment_token obtido no procedimento através do Javascript único por conta Gerencianet $item_1 = [ 'name' => 'Item 1', // nome do item, produto ou serviço 'amount' => 1, // quantidade 'value' => 3000 // valor (1000 = R$ 10,00) (Obs: É possível a criação de itens com valores negativos. Porém, o valor total da fatura deve ser superior ao valor mínimo para geração de transações.) ]; $items = [ $item_1 ]; $metadata = array('notification_url'=>'https://SuaUrl/16rpx6y1'); $customer = [ 'name' => 'Gorbadoc Oldbuck', // nome do cliente 'cpf' => '04267484171', // cpf do cliente 'phone_number' => '5144916523', // telefone do cliente 'email' => '[email protected]', // endereço de email do cliente 'birth' => '1977-01-15' // data de nascimento do cliente ]; $billingAddress = [ 'street' => 'Av JK', 'number' => 909, 'neighborhood' => 'Bauxita', 'zipcode' => '35400000', 'city' => 'Ouro Preto', 'state' => 'MG' ]; $discount = [ 'type' => 'currency', 'value' => 599 ]; $credit_card = [ 'customer' => $customer, 'installments' => 1, // número de parcelas em que o pagamento deve ser dividido 'discount' =>$discount, 'billing_address' => $billingAddress, 'payment_token' => $paymentToken, 'message' => 'teste\nteste\nteste\nteste' ]; $payment = [ 'credit_card' => $credit_card // forma de pagamento (credit_card = cartão) ]; $body = [ 'items' => $items, 'metadata' =>$metadata, 'payment' => $payment ]; try { $api = new Gerencianet($options); $pay_charge = $api->oneStep([],$body); echo '<pre>'; print_r($pay_charge); echo '<pre>'; } catch (GerencianetException $e) { print_r($e->code); print_r($e->error); print_r($e->errorDescription); } catch (Exception $e) { print_r($e->getMessage()); }
a) Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
"items"
"name"
"value"
"amount"
"marketplace"
"payee_code"
"percentage"
"shippings"
"name"
"value"
"payee_code"
"metadata"
"custom_id"
"notification_url"
"payment"
"credit_card"
"customer"
"name"
"cpf"
"email"
"phone_number"
"birth"
"address"
"street"
"number"
"neighborhood"
"zipcode"
"city"
"complement"
"state"
"juridical_person"
"corporate_name"
"cnpj"
"installments"
"discount"
"type"
"percentage",
"currency"
"value"
"billing_address"
"street"
"number"
"neighborhood"
"zipcode"
"city"
"complement"
"state"
"payment_token"
"message"
b) Atributos que podem ser utilizados para criar uma transação:
| Atributo | Descrição | Obrigatório | Tipo |
|---|---|---|---|
|
|
Item que está sendo vendido. Uma mesma transação pode possuir ilimitados itens. Atributos de items
name* // Nome do item, produto ou serviço. Mínimo de 1 caractere e máximo de 255 caracteres (String).
value* // Valor, em centavos. Ex: R$ 10,00 = 1000. Integer.
amount // Quantidade. Integer (padrão: 1)
|
Sim |
Array |
|
|
Determina o(s) valor(es) de frete(s) de uma transação. Uma mesma transação pode possuir ilimitados valores de frete. Atributos de shippings
name* // Rótulo do frete. Máximo de 255 caracteres. String.
value* // Valor do frete, em centavos (1990 equivale a R$19,90). Integer.
payeeCode, // código da conta Gerencianet que receberá o repasse do valor total do frete - refere-se ao "identificador da conta" Gerencianet (onde localizar meu identificador?) (String)
|
Não |
Array |
|
|
Define dados específicos da transação. Atributos de metadata
custom_id // Permite associar uma transação Gerencianet a uma ID específica de seu sistema ou aplicação, permitindo identificá-la caso você possua uma identificação específica e queira mantê-la. Máximo de 255 caracteres. String/null.
notification_url // Endereço de sua URL válida que receberá as notificações de mudanças de status das transações. Máximo de 255 caracteres. String/null.
|
Não |
Object |
Objeto Payment
| Atributo | Descrição | Obrigatório | Tipo |
|---|---|---|---|
|
|
Objeto contendo as informações necessárias para o pagamento via cartão de crédito, como por exemplo, o número de parcelas e os dados do cliente. |
Sim |
Objeto Credit_Card |
Objeto Credit_Card
| Atributo | Descrição | Obrigatório | Tipo |
|---|---|---|---|
|
|
Dados pessoais do pagador. Atributos de customer
name* // nome (String)
cpf* // CPF do cliente (sem pontos, vírgulas ou hífen) (String)
email* // Endereço de email válido do cliente (String)
phone_number* // Telefone válido do cliente, sem caracteres especiais (String)
birth* // Data de Nascimento do cliente (data válida em formato YYYY-MM-DD) (String)
juridical_person // Dados de pessoa jurídica (Object) (mais informações)
|
Sim |
Object |
|
|
Número de parcelas em que o pagamento deve ser dividido. |
Não |
Integer |
|
|
Define dados de desconto sobre a cobrança. Atributos de discount
type*, // Tipo do desconto (String). Valores permitidos: currency: o desconto será informado em centavos;percentage: o desconto será informado em porcentagem.
value*, // Valor do desconto (Integer). Se o tipo do desconto for currency, o valor desta tag deverá ser informada pelo integrador em centavos (ou seja, 500 equivale a R$ 5,00). Caso o tipo do desconto seja percentage, o valor deverá ser multiplicado por 100 (ou seja, 1500 equivale a 15%). Exemplos:1) currency // deve ser informado em centavos, ou seja, se o desconto será de R$ 5,99, o integrador deve informar 599;2) percentage // deve ser informado em centavos, ou seja, se o desconto é de 15%, o integrador deve informar 1500.
|
Não |
Object |
|
|
Endereço de cobrança (mais informações) Atributos de billing_address
street* // nome da rua (Object)
number* // número (String/Integer)
neighborhood* // Bairro (String)
zipcode* // CEP (sem pontos ou hífen) (String)
city* // cidade (String)
complement // complemento (String/null)
state* // estado (2 caracteres) (Object)
|
Sim |
Object |
|
|
Token único de pagamento obtido na primeira etapa da geração da transação. |
Sim |
String |
|
|
Permite incluir no boleto uma "observação", ou em outras palavras, uma mensagem para o cliente. Essa mensagem poderá ser vista nos e-mails relacionados à cobrança, no boleto ou carnê. O operador |
Não |
String |
* valor obrigatório
2. Criação de transação por cartão de crédito em Two Steps (Dois passos)
Nesta opção é necessário que o body da requisição contenha todos os atributos mínimos obrigatórios para a emissão do titulo.
Abaixo temos os exemplos de implementação utilizando as SDK's disponíveis:
2.1. Crie a transação, informando o item/produto/serviço, valor, quantidade, etc;
2.2. Associe à forma de pagamento via cartão, informando o charge_id da transação criada e os dados do cliente;
2.3. Obtenção do payment_token (via JavaScript, único por transação);
2.4. Pagando com cartão.
Por se tratar de pagamento via cartão e envolver dados sensíveis, como dados do cartão de crédito, os procedimentos descritos nos itens 3.1 e 3.2, ou seja, obtenção do payment_token e pagando com cartão, respectivamente, são necessários.
O restante desta página apresenta os procedimentos detalhados, mas você precisa instalar uma de nossas bibliotecas em seu servidor para executar os códigos de exemplo. Certifique-se de que a SDK da Gerencianet foi instalada.
2.1. Criar transação
Primeiramente, precisamos gerar a transação (também chamada de "cobrança"). É neste momento que será informado o nome do item/produto/serviço, valor da transação, quantidade, dentre outras informações possíveis.
Após criá-la, será retornado o charge_id, que é o identificador único da transação e que será utilizado para associar à forma de pagamento.
Assim que essa transação é criada, ela recebe o status new, que significa que a cobrança foi gerada e está aguardando definição da forma de pagamento. Essa cobrança somente terá seu status alterado quando o integrador definir sua forma de pagamento.
Para gerar uma transação, você deve enviar uma requisição POST para a rota /v1/charge.
Caso queira, pode explorar e conhecer mais sobre este recurso usando nosso Playground.
O exemplo abaixo mostra como isto pode ser feito, utilizando as SDK's disponíveis:
require __DIR__.'/../../vendor/autoload.php'; // caminho relacionado a SDK use Gerencianet\Exception\GerencianetException; use Gerencianet\Gerencianet; $clientId = 'informe_seu_client_id'; // insira seu Client_Id, conforme o ambiente (Des ou Prod) $clientSecret = 'informe_seu_client_secret'; // insira seu Client_Secret, conforme o ambiente (Des ou Prod) $options = [ 'client_id' => $clientId, 'client_secret' => $clientSecret, 'sandbox' => true // altere conforme o ambiente (true = Homologação e false = producao) ]; $item_1 = [ 'name' => 'Item 1', // nome do item, produto ou serviço 'amount' => 1, // quantidade 'value' => 1000 // valor (1000 = R$ 10,00) (Obs: É possível a criação de itens com valores negativos. Porém, o valor total da fatura deve ser superior ao valor mínimo para geração de transações.) ]; $item_2 = [ 'name' => 'Item 2', // nome do item, produto ou serviço 'amount' => 2, // quantidade 'value' => 2000 // valor (2000 = R$ 20,00) ]; $items = [ $item_1, $item_2 ]; // Exemplo para receber notificações da alteração do status da transação. // $metadata = ['notification_url'=>'sua_url_de_notificacao_.com.br'] // Outros detalhes em: https://dev.gerencianet.com.br/docs/notificacoes // Como enviar seu $body com o $metadata // $body = [ // 'items' => $items, // 'metadata' => $metadata // ]; $body = [ 'items' => $items ]; try { $api = new Gerencianet($options); $charge = $api->createCharge([], $body); print_r($charge); } catch (GerencianetException $e) { print_r($e->code); print_r($e->error); print_r($e->errorDescription); } catch (Exception $e) { print_r($e->getMessage()); }
a) Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
"id": "/Charge"
"items"
"name"
"value"
"amount"
"marketplace"
"payee_code"
"percentage"
"shippings"
"name"
"value"
"payee_code"
"metadata"
"custom_id"
"notification_url"
Para verificar mais detalhes, acesse aqui e explore em nosso Playground.
b) Atributos que podem ser utilizados para criar uma transação:
| Atributo | Descrição | Obrigatório | Tipo |
|---|---|---|---|
|
|
Item que está sendo vendido. Uma mesma transação pode possuir ilimitados itens. Atributos de items
name* // Nome do item, produto ou serviço. Mínimo de 1 caractere e máximo de 255 caracteres (String).
value* // Valor, em centavos. Ex: R$ 10,00 = 1000. Integer.
amount // Quantidade. Integer (padrão: 1)
|
Sim |
Array |
|
|
Determina o(s) valor(es) de frete(s) de uma transação. Uma mesma transação pode possuir ilimitados valores de frete. Atributos de shippings
name* // Rótulo do frete. Máximo de 255 caracteres. String.
value* // Valor do frete, em centavos (1990 equivale a R$19,90). Integer.
payeeCode, // código da conta Gerencianet que receberá o repasse do valor total do frete - refere-se ao "identificador da conta" Gerencianet (onde localizar meu identificador?) (String)
|
Não |
Array |
|
|
Define dados específicos da transação. Atributos de metadata
custom_id // Permite associar uma transação Gerencianet a uma ID específica de seu sistema ou aplicação, permitindo identificá-la caso você possua uma identificação específica e queira mantê-la. Máximo de 255 caracteres. String/null.
notification_url // Endereço de sua URL válida que receberá as notificações de mudanças de status das transações. Máximo de 255 caracteres. String/null.
|
Não |
Object |
* valor obrigatório
2.2. Associe à forma de pagamento via cartão
Com a transação criada, vamos associá-la à forma de pagamento desejada, que neste caso, será cartão de crédito. Para tal, deverá ser informado a charge_id obtido no consumo anterior em que foi gerada a transação.
No caso de transações com cartão de crédito, será realizado em duas etapas, sendo a primeira a transmissão (via JavaScript, no browser), de forma segura, os dados do cartão e retornando um payment_token, e na segunda etapa seu backend envia o restante das informações da transação e o payment_token obtido na primeira etapa.
IMPORTANTE - SOBRE O PAYMENT_TOKEN
É importante frisar que não é possível efetuar pagamento com cartão de crédito sem obter o payment_token da transação, por isso, é imprescindível a realização dos procedimentos do item 2.1 deste documento (obter o payment_token), e só depois passar para o item 2.2 (que é de fato o pagamento com cartão).
Para associar à forma de pagamento, você deve enviar uma requisição POST para a rota /v1/charge/:id/pay, onde :id é o charge_id da transação desejada.
Caso queira, pode explorar e conhecer mais sobre este recurso usando nosso Playground.
2.3. Obtenção do payment_token
Inicialmente, vamos realizar a primeira etapa, que é a obtenção do payment_token. Para tal, você necessitará de um código JavaScript específico de sua conta Gerencianet. Para gerá-lo, siga os passos :
- Efetue login em sua conta Gerencianet e acesse
API(Lateral a esquerda) - Copie seu
Identificador de Conta(veja onde) - Cole no campo abaixo e clique no botão
Gerar
É importante frisar que é obtido via JavaScript, no browser, de forma segura, os dados do cartão e retorna um payment_token, que é a representação dos dados enviados.
IMPORTANTE
Lembre-se que, após informar seu identificador de conta, serão gerados 2 (dois) códigos JavaScript distintos.
Copie e utilize o código referente ao ambiente desejado, atentando-se às diferenças do ambiente de "Homologação" e "Produção".
Para aplicações web, você deve copiar o script acima, específico da sua conta, e utilizar a nossa biblioteca Javascript, conforme o snippet abaixo. Se você possui um app mobile, confira como proceder acessando nossa página no GitHub para Android e/ou iOS.
Adicionalmente, esclarecemos que uma conta Gerencianet não possui um payment_token - ele é diferente e criado para cada cobrança gerada por cartão de crédito. Ele representa os dados do cartão do pagador e é obtido pela função getPaymentToken. Além disso, cabe frisar que o payment_token pode ser utilizado uma única vez, portanto, não é possível utilizá-lo para cobrar de forma recorrente.
a) Obtendo um "payment_token" ( getPaymentToken )
$gn.ready(function(checkout) { var callback = function(error, response) { if(error) { // Trata o erro ocorrido console.error(error); } else { // Trata a resposta console.log(response); } }; checkout.getPaymentToken({ brand: 'visa', // bandeira do cartão number: '4012001038443335', // número do cartão cvv: '123', // código de segurança expiration_month: '05', // mês de vencimento expiration_year: '2021' // ano de vencimento }, callback); });
b) Obtendo informações sobre parcelamentos ( getInstallments )
$gn.ready(function(checkout){ checkout.getInstallments(50000,'visa', function(error, response){ if(error) { // Trata o erro ocorrido console.log(error); } else { // Insere o parcelamento no site } }); });
c) Atributos relacionados ao envio de dados do cartão:
$gn.ready ( callback )
| Parâmetro | Descrição | Tipo |
|---|---|---|
|
|
Função de inicialização que possibilita a chamada das funções getPaymentToken e getInstallments. Parâmetro(s) de callback
object // Objeto que recebe as instâncias das outras funções.
|
Function |
getPaymentToken ( card_data, callback )
| Parâmetro | Descrição | Tipo |
|---|---|---|
|
|
Objeto que contém os dados do cartão. As propriedades desse objeto são:
brand // Bandeira do cartãonumber // Número do cartão sem formataçãocvv // Código de segurança do cartãoexpiration_month // Mês de expiração do cartão no formato "MM"expiration_year // Ano de expiração do cartão no formato "YYYY"
|
Object |
|
|
Função que recebe a resposta da Gerencianet. Parâmetro(s) de callback:
error // Se não foi possível gerar o payment_token, os erros serão retornados neste parâmetro.
response // Recebe os dados que representam o cartão de crédito: payment_token e card_mask
|
Function |
getInstallments ( total, brand, callback )
| Parâmetro | Descrição | Tipo |
|---|---|---|
|
|
Valor total da cobrança, incluindo fretes, em centavos.
Por exemplo: R$ 230,90 equivale a 23090.
|
Integer |
|
|
Bandeira do cartão que deseja-se obter os valores de parcelas. Possíveis valores:
visa // Bandeira Visa
mastercard // Bandeira MasterCard
amex // Bandeira AmericanExpress
elo // Bandeira Elo
hipercard // Bandeira Hipercard
|
String |
|
|
Função que recebe a resposta da Gerencianet. Parâmetro(s) de callback:
error // Se não foi possível obter dados sobre o pagamento, os erros serão retornados neste parâmetro.
response // Recebe os dados relacionados ao tipo de pagamento consultado.
|
Function |
2.4. Pagando com cartão
Agora que a transação já foi criada e o payment_token já foi obtido através do código Javascript da primeira etapa, vamos prosseguir com o pagamento com cartão de crédito.
Nesta etapa, seu backend envia o restante das informações da transação e o payment_token obtido na primeira etapa.
Ao pagar uma transação por cartão de crédito, o status é alterado de new para waiting. Isso significa que a transação está associada a uma forma de pagamento e que está aguardando a confirmação do pagamento.
Assim que o pagamento for confirmado, a transação terá o status alterado de waiting para paid. Mas, se por alguma razão não for possível confirmar o pagamento, o status será alterado para unpaid.
O exemplo abaixo mostra como isto pode ser feito, utilizando as SDK's disponíveis:
require __DIR__.'/../../vendor/autoload.php'; // caminho relacionado a SDK use Gerencianet\Exception\GerencianetException; use Gerencianet\Gerencianet; $clientId = 'informe_seu_client_id'; // insira seu Client_Id, conforme o ambiente (Des ou Prod) $clientSecret = 'informe_seu_client_secret'; // insira seu Client_Secret, conforme o ambiente (Des ou Prod) $options = [ 'client_id' => $clientId, 'client_secret' => $clientSecret, 'sandbox' => true // altere conforme o ambiente (true = Homologação e false = producao) ]; // $charge_id refere-se ao ID da transação gerada anteriormente $params = [ 'id' => $charge_id ]; $paymentToken = '6426f3abd8688639c6772963669bbb8e0eb3c319'; // payment_token obtido na 1ª etapa (através do Javascript único por conta Gerencianet) $customer = [ 'name' => 'Gorbadoc Oldbuck', // nome do cliente 'cpf' => '94271564656' , // cpf do cliente 'email' => '[email protected]' , // endereço de email do cliente 'phone_number' => '5144916523' // telefone do cliente 'birth' => '1990-05-20' // data de nascimento do cliente ]; $billingAddress = [ 'street' => 'Street 3', 'number' => 10, 'neighborhood' => 'Bauxita', 'zipcode' => '35400000', 'city' => 'Ouro Preto', 'state' => 'MG', ]; $creditCard = [ 'installments' => 1, // número de parcelas em que o pagamento deve ser dividido 'billing_address' => $billingAddress, 'payment_token' => $paymentToken, 'customer' => $customer ]; $body = [ 'payment' => $payment ]; $payment = [ 'credit_card' => $creditCard // forma de pagamento (credit_card = cartão) ]; try { $api = new Gerencianet($options); $charge = $api->payCharge($params, $body); print_r($charge); } catch (GerencianetException $e) { print_r($e->code); print_r($e->error); print_r($e->errorDescription); } catch (Exception $e) { print_r($e->getMessage()); }
a) Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
"id": "/Pay",
"payment"
"credit_card"
"customer"
"name"
"cpf"
"email"
"phone_number"
"birth"
"address"
"street"
"number"
"neighborhood"
"zipcode"
"city"
"complement"
"state"
"juridical_person"
"corporate_name"
"cnpj"
"installments"
"discount"
"type"
"percentage",
"currency"
"value"
"billing_address"
"street"
"number"
"neighborhood"
"zipcode"
"city"
"complement"
"state"
"payment_token"
"message"
Para verificar mais detalhes, acesse aqui e explore em nosso Playground.
b) Atributos relacionados ao pagamento com cartão de crédito:
Parâmetros da url
| Atributo | Descrição | Obrigatório | Tipo |
|---|---|---|---|
|
|
Identificador da transação ( |
Sim |
Objeto ID |
Objeto ID
| Atributo | Descrição | Obrigatório | Tipo |
|---|---|---|---|
|
|
Tag raiz |
Sim |
Objeto Payment |
Objeto Payment
| Atributo | Descrição | Obrigatório | Tipo |
|---|---|---|---|
|
|
Objeto contendo as informações necessárias para o pagamento via cartão de crédito, como por exemplo, o número de parcelas e os dados do cliente. |
Sim |
Objeto Credit_Card |
Objeto Credit_Card
| Atributo | Descrição | Obrigatório | Tipo |
|---|---|---|---|
|
|
Dados pessoais do pagador. Atributos de customer
name* // nome (String)
cpf* // CPF do cliente (sem pontos, vírgulas ou hífen) (String)
email* // Endereço de email válido do cliente (String)
phone_number // Telefone válido do cliente, sem caracteres especiais (String)
birth* // Data de Nascimento do cliente (data válida em formato YYYY-MM-DD) (String)
juridical_person // Dados de pessoa jurídica (Object) (mais informações)
|
Sim |
Object |
|
|
Número de parcelas em que o pagamento deve ser dividido. |
Não |
Integer |
|
|
Define dados de desconto sobre a cobrança. Atributos de discount
type*, // Tipo do desconto (String). Valores permitidos: currency: o desconto será informado em centavos;percentage: o desconto será informado em porcentagem.
value*, // Valor do desconto (Integer). Se o tipo do desconto for currency, o valor desta tag deverá ser informada pelo integrador em centavos (ou seja, 500 equivale a R$ 5,00). Caso o tipo do desconto seja percentage, o valor deverá ser multiplicado por 100 (ou seja, 1500 equivale a 15%). Exemplos:1) currency // deve ser informado em centavos, ou seja, se o desconto será de R$ 5,99, o integrador deve informar 599;2) percentage // deve ser informado em centavos, ou seja, se o desconto é de 15%, o integrador deve informar 1500.
|
Não |
Object |
|
|
Endereço de cobrança (mais informações) Atributos de billing_address
street* // nome da rua (Object)
number* // número (String/Integer)
neighborhood* // Bairro (String)
zipcode* // CEP (sem pontos ou hífen) (String)
city* // cidade (String)
complement // complemento (String/null)
state* // estado (2 caracteres) (Object)
|
Sim |
Object |
|
|
Token único de pagamento obtido na primeira etapa da geração da transação. |
Sim |
String |
|
|
Permite incluir no boleto uma "observação", ou em outras palavras, uma mensagem para o cliente. Essa mensagem poderá ser vista nos e-mails relacionados à cobrança, no boleto ou carnê. O operador |
Não |
String |
* valor obrigatório
Pagamento realizado como Pessoa Jurídica (PJ)
O cliente associado à transação pode ser uma Pessoa Jurídica. Nesse caso, devem ser informados a Razão Social e o CNPJ da empresa pagadora dentro do atributo juridical_person.
Veja detalhes neste link sobre como gerar um pagamento cuja forma de pagamento seja "cartão de crédito" para um cliente que seja Pessoa Jurídica (PJ).
Relação de todos os possíveis status de uma transação
Todas as transações possuem status, que representa a "situação" dessa transação. Portanto, é importante conhecer os possíveis status na API para fornecer as devidas tratativas em seu sistema.
Confira neste link todos os detalhes dos possíveis status das transações.
Callbacks (notificações) das transações da API para seu sistema
As notificações permitem que você seja informado quando uma transação tiver seu status alterado. Dessa forma, você poderá identificar quando uma cobrança for paga, por exemplo.
Confira neste link todos os detalhes sobre como implementar a sua URL de notificação.
3. Outros endpoints
Existem outros endpoints e métodos relacionados a pagamento via cartão de crédito que estão disponíveis na API e podem ser explorados pelo integrador. Confira a relação completa:
Pagamento com cartão
Passo a passo para gerar uma cobrança de cartão de crédito na API Gerencianet
Atualmente disponibilizamos dois procedimentos para a criação de uma transação do tipo cartão de crédito, na primeira delas o titulo é criado em um passo único, assim fora convencionado como One Step. A segunda opção de criação da transação se da em dois passos, sendo assim convencionada como Two Steps. Ambos os fluxos estão detalhados a seguir:
1. Criação de transação por cartão de crédito em One Step (Um passo)
Importante
Para que a criação de transações via One Step ocorra normalmente é necessário atualizar sua SDK. Todos os arquivos necessários para tal estão disponíveis através de nosso repositório e em nossa documentação.
No caso de transações com cartão de crédito, será realizada uma etapa anterior a criação onde ocorre a transmissão (via JavaScript, no browser), de forma segura, dos dados do cartão e retornando um payment_token, e na segunda etapa seu backend envia o restante das informações da transação e o payment_token obtido na primeira etapa.
É importante frisar que não é possível efetuar pagamento com cartão de crédito sem obter o payment_token da transação, por isso, é imprescindível a realização dos procedimentos do item 1.1 deste documento (obter o payment_token), e só depois passar para o item 1.2 (que é de fato o pagamento com cartão).
1.1. Obtenção do payment_token
Inicialmente, vamos realizar a primeira etapa, que é a obtenção do payment_token. Para tal, você necessitará de um código JavaScript específico de sua conta Gerencianet. Para gerá-lo, siga os passos :
- Efetue login em sua conta Gerencianet e acesse
API(Lateral a esquerda) - Copie seu
Identificador de Conta(veja onde) - Cole no campo abaixo e clique no botão
Gerar
É importante frisar que é obtido via JavaScript, no browser, de forma segura, os dados do cartão e retorna um payment_token, que é a representação dos dados enviados.
Lembre-se que, após informar seu identificador de conta, serão gerados 2 (dois) códigos JavaScript distintos.
Copie e utilize o código referente ao ambiente desejado, atentando-se às diferenças do ambiente de "Homologação" e "Produção".
Para aplicações web, você deve copiar o script, específico da sua conta, e utilizar a nossa biblioteca Javascript, conforme o snippet abaixo. Se você possui um app mobile, confira como proceder acessando nossa página no GitHub para Android e/ou iOS.
Adicionalmente, esclarecemos que uma conta Gerencianet não possui um payment_token - ele é diferente e criado para cada cobrança gerada por cartão de crédito. Ele representa os dados do cartão do pagador e é obtido pela função getPaymentToken. Além disso, cabe frisar que o payment_token pode ser utilizado uma única vez, portanto, não é possível utilizá-lo para cobrar de forma recorrente.
a) Obtendo um "payment_token" ( getPaymentToken )
$gn.ready(function (checkout) { checkout.getPaymentToken( { brand: 'visa', // bandeira do cartão number: '4012001038443335', // número do cartão cvv: '123', // código de segurança expiration_month: '05', // mês de vencimento expiration_year: '2021' // ano de vencimento }, function (error, response) { if (error) { // Trata o erro ocorrido console.error(error); } else { // Trata a resposta console.log(response); } } ); });
b) Obtendo informações sobre parcelamentos ( getInstallments )
$gn.ready(function (checkout) { checkout.getInstallments( 50000, // valor total da cobrança 'visa', // bandeira do cartão function (error, response) { if (error) { // Trata o erro ocorrido console.log(error); } else { // Trata a respostae console.log(response); } } ); });
c) Atributos relacionados ao envio de dados do cartão:
$gn.ready ( callback )
| Parâmetro | Descrição | Tipo |
|---|---|---|
|
|
Função de inicialização que possibilita a chamada das funções getPaymentToken e getInstallments. Parâmetro(s) de callback
object // Objeto que recebe as instâncias das outras funções.
|
Function |
getPaymentToken ( card_data, callback )
| Parâmetro | Descrição | |
|---|---|---|
|
|
Objeto que contém os dados do cartão. As propriedades desse objeto são:
brand // Bandeira do cartãonumber // Número do cartão sem formataçãocvv // Código de segurança do cartãoexpiration_month // Mês de expiração do cartão no formato "MM"expiration_year // Ano de expiração do cartão no formato "YYYY"
|
Object |
|
|
Função que recebe a resposta da Gerencianet. Parâmetro(s) de callback:
error // Se não foi possível gerar o payment_token, os erros serão retornados neste parâmetro.
response // Recebe os dados que representam o cartão de crédito: payment_token e card_mask
|
Function |
getInstallments ( total, brand, callback )
| Parâmetro | Descrição | Tipo |
|---|---|---|
|
|
Valor total da cobrança, incluindo fretes, em centavos.
Por exemplo: R$ 230,90 equivale a 23090.
|
Integer |
|
|
Bandeira do cartão que deseja-se obter os valores de parcelas. Possíveis valores:
visa // Bandeira Visa
mastercard // Bandeira MasterCard
amex // Bandeira AmericanExpress
elo // Bandeira Elo
hipercard // Bandeira Hipercard
|
String |
|
|
Função que recebe a resposta da Gerencianet. Parâmetro(s) de callback:
error // Se não foi possível obter dados sobre o pagamento, os erros serão retornados neste parâmetro.
response // Recebe os dados relacionados ao tipo de pagamento consultado.
|
Function |
1.2. Pagando com cartão
Agora que o payment_token já foi obtido através do código Javascript, vamos prosseguir com o pagamento com cartão de crédito.
Nesta etapa, seu backend envia o restante das informações da transação e o payment_token obtido na primeira etapa.
Ao pagar uma transação por cartão de crédito, o status é alterado de new para waiting. Isso significa que a transação está associada a uma forma de pagamento e que está aguardando a confirmação do pagamento.
Assim que o pagamento for confirmado, a transação terá o status alterado de waiting para paid. Mas, se por alguma razão não for possível confirmar o pagamento, o status será alterado para unpaid.
O exemplo abaixo mostra como isto pode ser feito, utilizando as SDK's disponíveis:
require __DIR__.'/../../autoload.php'; //Caminho da SDK use Gerencianet\Exception\GerencianetException; use Gerencianet\Gerencianet; $clientId = 'informe_seu_client_id'; // insira seu Client_Id, conforme o ambiente (Des ou Prod) $clientSecret = 'informe_seu_client_secret'; // insira seu Client_Secret, conforme o ambiente (Des ou Prod) $options = [ 'client_id' => $clientId, 'client_secret' => $clientSecret, 'sandbox' => true // altere conforme o ambiente (true = Homologação e false = producao) ]; $paymentToken = '83d52dbd590d9ebc991938c711ddd31f65df89a5'; // payment_token obtido no procedimento através do Javascript único por conta Gerencianet $item_1 = [ 'name' => 'Item 1', // nome do item, produto ou serviço 'amount' => 1, // quantidade 'value' => 3000 // valor (1000 = R$ 10,00) (Obs: É possível a criação de itens com valores negativos. Porém, o valor total da fatura deve ser superior ao valor mínimo para geração de transações.) ]; $items = [ $item_1 ]; $metadata = array('notification_url'=>'https://SuaUrl/16rpx6y1'); $customer = [ 'name' => 'Gorbadoc Oldbuck', // nome do cliente 'cpf' => '04267484171', // cpf do cliente 'phone_number' => '5144916523', // telefone do cliente 'email' => '[email protected]', // endereço de email do cliente 'birth' => '1977-01-15' // data de nascimento do cliente ]; $billingAddress = [ 'street' => 'Av JK', 'number' => 909, 'neighborhood' => 'Bauxita', 'zipcode' => '35400000', 'city' => 'Ouro Preto', 'state' => 'MG' ]; $discount = [ 'type' => 'currency', 'value' => 599 ]; $credit_card = [ 'customer' => $customer, 'installments' => 1, // número de parcelas em que o pagamento deve ser dividido 'discount' =>$discount, 'billing_address' => $billingAddress, 'payment_token' => $paymentToken, 'message' => 'teste\nteste\nteste\nteste' ]; $payment = [ 'credit_card' => $credit_card // forma de pagamento (credit_card = cartão) ]; $body = [ 'items' => $items, 'metadata' =>$metadata, 'payment' => $payment ]; try { $api = new Gerencianet($options); $pay_charge = $api->oneStep([],$body); echo '<pre>'; print_r($pay_charge); echo '<pre>'; } catch (GerencianetException $e) { print_r($e->code); print_r($e->error); print_r($e->errorDescription); } catch (Exception $e) { print_r($e->getMessage()); }
a) Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
"items"
"name"
"value"
"amount"
"marketplace"
"payee_code"
"percentage"
"shippings"
"name"
"value"
"payee_code"
"metadata"
"custom_id"
"notification_url"
"payment"
"credit_card"
"customer"
"name"
"cpf"
"email"
"phone_number"
"birth"
"address"
"street"
"number"
"neighborhood"
"zipcode"
"city"
"complement"
"state"
"juridical_person"
"corporate_name"
"cnpj"
"installments"
"discount"
"type"
"percentage",
"currency"
"value"
"billing_address"
"street"
"number"
"neighborhood"
"zipcode"
"city"
"complement"
"state"
"payment_token"
"message"
b) Atributos que podem ser utilizados para criar uma transação:
| Atributo | Descrição | Obrigatório | Tipo |
|---|---|---|---|
|
|
Item que está sendo vendido. Uma mesma transação pode possuir ilimitados itens. Atributos de items
name* // Nome do item, produto ou serviço. Mínimo de 1 caractere e máximo de 255 caracteres (String).
value* // Valor, em centavos. Ex: R$ 10,00 = 1000. Integer.
amount // Quantidade. Integer (padrão: 1)
|
Sim |
Array |
|
|
Determina o(s) valor(es) de frete(s) de uma transação. Uma mesma transação pode possuir ilimitados valores de frete. Atributos de shippings
name* // Rótulo do frete. Máximo de 255 caracteres. String.
value* // Valor do frete, em centavos (1990 equivale a R$19,90). Integer.
payeeCode, // código da conta Gerencianet que receberá o repasse do valor total do frete - refere-se ao "identificador da conta" Gerencianet (onde localizar meu identificador?) (String)
|
Não |
Array |
|
|
Define dados específicos da transação. Atributos de metadata
custom_id // Permite associar uma transação Gerencianet a uma ID específica de seu sistema ou aplicação, permitindo identificá-la caso você possua uma identificação específica e queira mantê-la. Máximo de 255 caracteres. String/null.
notification_url // Endereço de sua URL válida que receberá as notificações de mudanças de status das transações. Máximo de 255 caracteres. String/null.
|
Não |
Object |
Objeto Payment
| Atributo | Descrição | Obrigatório | Tipo |
|---|---|---|---|
|
|
Objeto contendo as informações necessárias para o pagamento via cartão de crédito, como por exemplo, o número de parcelas e os dados do cliente. |
Sim |
Objeto Credit_Card |
Objeto Credit_Card
| Atributo | Descrição | Obrigatório | Tipo |
|---|---|---|---|
|
|
Dados pessoais do pagador. Atributos de customer
name* // nome (String)
cpf* // CPF do cliente (sem pontos, vírgulas ou hífen) (String)
email* // Endereço de email válido do cliente (String)
phone_number* // Telefone válido do cliente, sem caracteres especiais (String)
birth* // Data de Nascimento do cliente (data válida em formato YYYY-MM-DD) (String)
juridical_person // Dados de pessoa jurídica (Object) (mais informações)
|
Sim |
Object |
|
|
Número de parcelas em que o pagamento deve ser dividido. |
Não |
Integer |
|
|
Define dados de desconto sobre a cobrança. Atributos de discount
type*, // Tipo do desconto (String). Valores permitidos: currency: o desconto será informado em centavos;percentage: o desconto será informado em porcentagem.
value*, // Valor do desconto (Integer). Se o tipo do desconto for currency, o valor desta tag deverá ser informada pelo integrador em centavos (ou seja, 500 equivale a R$ 5,00). Caso o tipo do desconto seja percentage, o valor deverá ser multiplicado por 100 (ou seja, 1500 equivale a 15%). Exemplos:1) currency // deve ser informado em centavos, ou seja, se o desconto será de R$ 5,99, o integrador deve informar 599;2) percentage // deve ser informado em centavos, ou seja, se o desconto é de 15%, o integrador deve informar 1500.
|
Não |
Object |
|
|
Endereço de cobrança (mais informações) Atributos de billing_address
street* // nome da rua (Object)
number* // número (String/Integer)
neighborhood* // Bairro (String)
zipcode* // CEP (sem pontos ou hífen) (String)
city* // cidade (String)
complement // complemento (String/null)
state* // estado (2 caracteres) (Object)
|
Sim |
Object |
|
|
Token único de pagamento obtido na primeira etapa da geração da transação. |
Sim |
String |
|
|
Permite incluir no boleto uma "observação", ou em outras palavras, uma mensagem para o cliente. Essa mensagem poderá ser vista nos e-mails relacionados à cobrança, no boleto ou carnê. O operador |
Não |
String |
* valor obrigatório
2. Criação de transação por cartão de crédito em Two Steps (Dois passos)
Nesta opção é necessário que o body da requisição contenha todos os atributos mínimos obrigatórios para a emissão do titulo.
Abaixo temos os exemplos de implementação utilizando as SDK's disponíveis:
2.1. Crie a transação, informando o item/produto/serviço, valor, quantidade, etc;
2.2. Associe à forma de pagamento via cartão, informando o charge_id da transação criada e os dados do cliente;
2.3. Obtenção do payment_token (via JavaScript, único por transação);
2.4. Pagando com cartão.
Por se tratar de pagamento via cartão e envolver dados sensíveis, como dados do cartão de crédito, os procedimentos descritos nos itens 3.1 e 3.2, ou seja, obtenção do payment_token e pagando com cartão, respectivamente, são necessários.
O restante desta página apresenta os procedimentos detalhados, mas você precisa instalar uma de nossas bibliotecas em seu servidor para executar os códigos de exemplo. Certifique-se de que a SDK da Gerencianet foi instalada.
2.1. Criar transação
Primeiramente, precisamos gerar a transação (também chamada de "cobrança"). É neste momento que será informado o nome do item/produto/serviço, valor da transação, quantidade, dentre outras informações possíveis.
Após criá-la, será retornado o charge_id, que é o identificador único da transação e que será utilizado para associar à forma de pagamento.
Assim que essa transação é criada, ela recebe o status new, que significa que a cobrança foi gerada e está aguardando definição da forma de pagamento. Essa cobrança somente terá seu status alterado quando o integrador definir sua forma de pagamento.
Para gerar uma transação, você deve enviar uma requisição POST para a rota /v1/charge.
Caso queira, pode explorar e conhecer mais sobre este recurso usando nosso Playground.
O exemplo abaixo mostra como isto pode ser feito, utilizando as SDK's disponíveis:
require __DIR__.'/../../vendor/autoload.php'; // caminho relacionado a SDK use Gerencianet\Exception\GerencianetException; use Gerencianet\Gerencianet; $clientId = 'informe_seu_client_id'; // insira seu Client_Id, conforme o ambiente (Des ou Prod) $clientSecret = 'informe_seu_client_secret'; // insira seu Client_Secret, conforme o ambiente (Des ou Prod) $options = [ 'client_id' => $clientId, 'client_secret' => $clientSecret, 'sandbox' => true // altere conforme o ambiente (true = Homologação e false = producao) ]; $item_1 = [ 'name' => 'Item 1', // nome do item, produto ou serviço 'amount' => 1, // quantidade 'value' => 1000 // valor (1000 = R$ 10,00) (Obs: É possível a criação de itens com valores negativos. Porém, o valor total da fatura deve ser superior ao valor mínimo para geração de transações.) ]; $item_2 = [ 'name' => 'Item 2', // nome do item, produto ou serviço 'amount' => 2, // quantidade 'value' => 2000 // valor (2000 = R$ 20,00) ]; $items = [ $item_1, $item_2 ]; // Exemplo para receber notificações da alteração do status da transação. // $metadata = ['notification_url'=>'sua_url_de_notificacao_.com.br'] // Outros detalhes em: https://dev.gerencianet.com.br/docs/notificacoes // Como enviar seu $body com o $metadata // $body = [ // 'items' => $items, // 'metadata' => $metadata // ]; $body = [ 'items' => $items ]; try { $api = new Gerencianet($options); $charge = $api->createCharge([], $body); print_r($charge); } catch (GerencianetException $e) { print_r($e->code); print_r($e->error); print_r($e->errorDescription); } catch (Exception $e) { print_r($e->getMessage()); }
a) Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
"id": "/Charge"
"items"
"name"
"value"
"amount"
"marketplace"
"payee_code"
"percentage"
"shippings"
"name"
"value"
"payee_code"
"metadata"
"custom_id"
"notification_url"
Para verificar mais detalhes, acesse aqui e explore em nosso Playground.
b) Atributos que podem ser utilizados para criar uma transação:
| Atributo | Descrição | Obrigatório | Tipo |
|---|---|---|---|
|
|
Item que está sendo vendido. Uma mesma transação pode possuir ilimitados itens. Atributos de items
name* // Nome do item, produto ou serviço. Mínimo de 1 caractere e máximo de 255 caracteres (String).
value* // Valor, em centavos. Ex: R$ 10,00 = 1000. Integer.
amount // Quantidade. Integer (padrão: 1)
|
Sim |
Array |
|
|
Determina o(s) valor(es) de frete(s) de uma transação. Uma mesma transação pode possuir ilimitados valores de frete. Atributos de shippings
name* // Rótulo do frete. Máximo de 255 caracteres. String.
value* // Valor do frete, em centavos (1990 equivale a R$19,90). Integer.
payeeCode, // código da conta Gerencianet que receberá o repasse do valor total do frete - refere-se ao "identificador da conta" Gerencianet (onde localizar meu identificador?) (String)
|
Não |
Array |
|
|
Define dados específicos da transação. Atributos de metadata
custom_id // Permite associar uma transação Gerencianet a uma ID específica de seu sistema ou aplicação, permitindo identificá-la caso você possua uma identificação específica e queira mantê-la. Máximo de 255 caracteres. String/null.
notification_url // Endereço de sua URL válida que receberá as notificações de mudanças de status das transações. Máximo de 255 caracteres. String/null.
|
Não |
Object |
* valor obrigatório
2.2. Associe à forma de pagamento via cartão
Com a transação criada, vamos associá-la à forma de pagamento desejada, que neste caso, será cartão de crédito. Para tal, deverá ser informado a charge_id obtido no consumo anterior em que foi gerada a transação.
No caso de transações com cartão de crédito, será realizado em duas etapas, sendo a primeira a transmissão (via JavaScript, no browser), de forma segura, os dados do cartão e retornando um payment_token, e na segunda etapa seu backend envia o restante das informações da transação e o payment_token obtido na primeira etapa.
IMPORTANTE - SOBRE O PAYMENT_TOKEN
É importante frisar que não é possível efetuar pagamento com cartão de crédito sem obter o payment_token da transação, por isso, é imprescindível a realização dos procedimentos do item 2.1 deste documento (obter o payment_token), e só depois passar para o item 2.2 (que é de fato o pagamento com cartão).
Para associar à forma de pagamento, você deve enviar uma requisição POST para a rota /v1/charge/:id/pay, onde :id é o charge_id da transação desejada.
Caso queira, pode explorar e conhecer mais sobre este recurso usando nosso Playground.
2.3. Obtenção do payment_token
Inicialmente, vamos realizar a primeira etapa, que é a obtenção do payment_token. Para tal, você necessitará de um código JavaScript específico de sua conta Gerencianet. Para gerá-lo, siga os passos :
- Efetue login em sua conta Gerencianet e acesse
API(Lateral a esquerda) - Copie seu
Identificador de Conta(veja onde) - Cole no campo abaixo e clique no botão
Gerar
É importante frisar que é obtido via JavaScript, no browser, de forma segura, os dados do cartão e retorna um payment_token, que é a representação dos dados enviados.
IMPORTANTE
Lembre-se que, após informar seu identificador de conta, serão gerados 2 (dois) códigos JavaScript distintos.
Copie e utilize o código referente ao ambiente desejado, atentando-se às diferenças do ambiente de "Homologação" e "Produção".
Para aplicações web, você deve copiar o script acima, específico da sua conta, e utilizar a nossa biblioteca Javascript, conforme o snippet abaixo. Se você possui um app mobile, confira como proceder acessando nossa página no GitHub para Android e/ou iOS.
Adicionalmente, esclarecemos que uma conta Gerencianet não possui um payment_token - ele é diferente e criado para cada cobrança gerada por cartão de crédito. Ele representa os dados do cartão do pagador e é obtido pela função getPaymentToken. Além disso, cabe frisar que o payment_token pode ser utilizado uma única vez, portanto, não é possível utilizá-lo para cobrar de forma recorrente.
a) Obtendo um "payment_token" ( getPaymentToken )
$gn.ready(function(checkout) { var callback = function(error, response) { if(error) { // Trata o erro ocorrido console.error(error); } else { // Trata a resposta console.log(response); } }; checkout.getPaymentToken({ brand: 'visa', // bandeira do cartão number: '4012001038443335', // número do cartão cvv: '123', // código de segurança expiration_month: '05', // mês de vencimento expiration_year: '2021' // ano de vencimento }, callback); });
b) Obtendo informações sobre parcelamentos ( getInstallments )
$gn.ready(function(checkout){ checkout.getInstallments(50000,'visa', function(error, response){ if(error) { // Trata o erro ocorrido console.log(error); } else { // Insere o parcelamento no site } }); });
c) Atributos relacionados ao envio de dados do cartão:
$gn.ready ( callback )
| Parâmetro | Descrição | Tipo |
|---|---|---|
|
|
Função de inicialização que possibilita a chamada das funções getPaymentToken e getInstallments. Parâmetro(s) de callback
object // Objeto que recebe as instâncias das outras funções.
|
Function |
getPaymentToken ( card_data, callback )
| Parâmetro | Descrição | Tipo |
|---|---|---|
|
|
Objeto que contém os dados do cartão. As propriedades desse objeto são:
brand // Bandeira do cartãonumber // Número do cartão sem formataçãocvv // Código de segurança do cartãoexpiration_month // Mês de expiração do cartão no formato "MM"expiration_year // Ano de expiração do cartão no formato "YYYY"
|
Object |
|
|
Função que recebe a resposta da Gerencianet. Parâmetro(s) de callback:
error // Se não foi possível gerar o payment_token, os erros serão retornados neste parâmetro.
response // Recebe os dados que representam o cartão de crédito: payment_token e card_mask
|
Function |
getInstallments ( total, brand, callback )
| Parâmetro | Descrição | Tipo |
|---|---|---|
|
|
Valor total da cobrança, incluindo fretes, em centavos.
Por exemplo: R$ 230,90 equivale a 23090.
|
Integer |
|
|
Bandeira do cartão que deseja-se obter os valores de parcelas. Possíveis valores:
visa // Bandeira Visa
mastercard // Bandeira MasterCard
amex // Bandeira AmericanExpress
elo // Bandeira Elo
hipercard // Bandeira Hipercard
|
String |
|
|
Função que recebe a resposta da Gerencianet. Parâmetro(s) de callback:
error // Se não foi possível obter dados sobre o pagamento, os erros serão retornados neste parâmetro.
response // Recebe os dados relacionados ao tipo de pagamento consultado.
|
Function |
2.4. Pagando com cartão
Agora que a transação já foi criada e o payment_token já foi obtido através do código Javascript da primeira etapa, vamos prosseguir com o pagamento com cartão de crédito.
Nesta etapa, seu backend envia o restante das informações da transação e o payment_token obtido na primeira etapa.
Ao pagar uma transação por cartão de crédito, o status é alterado de new para waiting. Isso significa que a transação está associada a uma forma de pagamento e que está aguardando a confirmação do pagamento.
Assim que o pagamento for confirmado, a transação terá o status alterado de waiting para paid. Mas, se por alguma razão não for possível confirmar o pagamento, o status será alterado para unpaid.
O exemplo abaixo mostra como isto pode ser feito, utilizando as SDK's disponíveis:
require __DIR__.'/../../vendor/autoload.php'; // caminho relacionado a SDK use Gerencianet\Exception\GerencianetException; use Gerencianet\Gerencianet; $clientId = 'informe_seu_client_id'; // insira seu Client_Id, conforme o ambiente (Des ou Prod) $clientSecret = 'informe_seu_client_secret'; // insira seu Client_Secret, conforme o ambiente (Des ou Prod) $options = [ 'client_id' => $clientId, 'client_secret' => $clientSecret, 'sandbox' => true // altere conforme o ambiente (true = Homologação e false = producao) ]; // $charge_id refere-se ao ID da transação gerada anteriormente $params = [ 'id' => $charge_id ]; $paymentToken = '6426f3abd8688639c6772963669bbb8e0eb3c319'; // payment_token obtido na 1ª etapa (através do Javascript único por conta Gerencianet) $customer = [ 'name' => 'Gorbadoc Oldbuck', // nome do cliente 'cpf' => '94271564656' , // cpf do cliente 'email' => '[email protected]' , // endereço de email do cliente 'phone_number' => '5144916523' // telefone do cliente 'birth' => '1990-05-20' // data de nascimento do cliente ]; $billingAddress = [ 'street' => 'Street 3', 'number' => 10, 'neighborhood' => 'Bauxita', 'zipcode' => '35400000', 'city' => 'Ouro Preto', 'state' => 'MG', ]; $creditCard = [ 'installments' => 1, // número de parcelas em que o pagamento deve ser dividido 'billing_address' => $billingAddress, 'payment_token' => $paymentToken, 'customer' => $customer ]; $body = [ 'payment' => $payment ]; $payment = [ 'credit_card' => $creditCard // forma de pagamento (credit_card = cartão) ]; try { $api = new Gerencianet($options); $charge = $api->payCharge($params, $body); print_r($charge); } catch (GerencianetException $e) { print_r($e->code); print_r($e->error); print_r($e->errorDescription); } catch (Exception $e) { print_r($e->getMessage()); }
a) Estrutura hierárquica dos atributos do Schema que podem ser utilizados:
"id": "/Pay",
"payment"
"credit_card"
"customer"
"name"
"cpf"
"email"
"phone_number"
"birth"
"address"
"street"
"number"
"neighborhood"
"zipcode"
"city"
"complement"
"state"
"juridical_person"
"corporate_name"
"cnpj"
"installments"
"discount"
"type"
"percentage",
"currency"
"value"
"billing_address"
"street"
"number"
"neighborhood"
"zipcode"
"city"
"complement"
"state"
"payment_token"
"message"
Para verificar mais detalhes, acesse aqui e explore em nosso Playground.
b) Atributos relacionados ao pagamento com cartão de crédito:
Parâmetros da url
| Atributo | Descrição | Obrigatório | Tipo |
|---|---|---|---|
|
|
Identificador da transação ( |
Sim |
Objeto ID |
Objeto ID
| Atributo | Descrição | Obrigatório | Tipo |
|---|---|---|---|
|
|
Tag raiz |
Sim |
Objeto Payment |
Objeto Payment
| Atributo | Descrição | Obrigatório | Tipo |
|---|---|---|---|
|
|
Objeto contendo as informações necessárias para o pagamento via cartão de crédito, como por exemplo, o número de parcelas e os dados do cliente. |
Sim |
Objeto Credit_Card |
Objeto Credit_Card
| Atributo | Descrição | Obrigatório | Tipo |
|---|---|---|---|
|
|
Dados pessoais do pagador. Atributos de customer
name* // nome (String)
cpf* // CPF do cliente (sem pontos, vírgulas ou hífen) (String)
email* // Endereço de email válido do cliente (String)
phone_number // Telefone válido do cliente, sem caracteres especiais (String)
birth* // Data de Nascimento do cliente (data válida em formato YYYY-MM-DD) (String)
juridical_person // Dados de pessoa jurídica (Object) (mais informações)
|
Sim |
Object |
|
|
Número de parcelas em que o pagamento deve ser dividido. |
Não |
Integer |
|
|
Define dados de desconto sobre a cobrança. Atributos de discount
type*, // Tipo do desconto (String). Valores permitidos: currency: o desconto será informado em centavos;percentage: o desconto será informado em porcentagem.
value*, // Valor do desconto (Integer). Se o tipo do desconto for currency, o valor desta tag deverá ser informada pelo integrador em centavos (ou seja, 500 equivale a R$ 5,00). Caso o tipo do desconto seja percentage, o valor deverá ser multiplicado por 100 (ou seja, 1500 equivale a 15%). Exemplos:1) currency // deve ser informado em centavos, ou seja, se o desconto será de R$ 5,99, o integrador deve informar 599;2) percentage // deve ser informado em centavos, ou seja, se o desconto é de 15%, o integrador deve informar 1500.
|
Não |
Object |
|
|
Endereço de cobrança (mais informações) Atributos de billing_address
street* // nome da rua (Object)
number* // número (String/Integer)
neighborhood* // Bairro (String)
zipcode* // CEP (sem pontos ou hífen) (String)
city* // cidade (String)
complement // complemento (String/null)
state* // estado (2 caracteres) (Object)
|
Sim |
Object |
|
|
Token único de pagamento obtido na primeira etapa da geração da transação. |
Sim |
String |
|
|
Permite incluir no boleto uma "observação", ou em outras palavras, uma mensagem para o cliente. Essa mensagem poderá ser vista nos e-mails relacionados à cobrança, no boleto ou carnê. O operador |
Não |
String |
* valor obrigatório
Pagamento realizado como Pessoa Jurídica (PJ)
O cliente associado à transação pode ser uma Pessoa Jurídica. Nesse caso, devem ser informados a Razão Social e o CNPJ da empresa pagadora dentro do atributo juridical_person.
Veja detalhes neste link sobre como gerar um pagamento cuja forma de pagamento seja "cartão de crédito" para um cliente que seja Pessoa Jurídica (PJ).
Relação de todos os possíveis status de uma transação
Todas as transações possuem status, que representa a "situação" dessa transação. Portanto, é importante conhecer os possíveis status na API para fornecer as devidas tratativas em seu sistema.
Confira neste link todos os detalhes dos possíveis status das transações.
Callbacks (notificações) das transações da API para seu sistema
As notificações permitem que você seja informado quando uma transação tiver seu status alterado. Dessa forma, você poderá identificar quando uma cobrança for paga, por exemplo.
Confira neste link todos os detalhes sobre como implementar a sua URL de notificação.
3. Outros endpoints
Existem outros endpoints e métodos relacionados a pagamento via cartão de crédito que estão disponíveis na API e podem ser explorados pelo integrador. Confira a relação completa:
Pagamento com cartão API Gerencianet Treinamento Completo, Maykon Silveira, Como Gerar Bolix API Gerencianet, Glossário com os termos mais comuns relacionados a API e Integrações no gerencianet, Cursos online completos e gratuitos, curso php 8, curso node.js, curso de react, curso de react.js, curso de arduino, curso de html, curso de css, curso javascript, Maykon Silveira, criando api com Maykon Silveira, curso de sheep php, sheep php, Gerando Boletos com QRCODE PIX no gerencianet treinamento completo
