Assinaturas
Para criar uma assinatura em nossa base de dados, é necessário ter no mínimo um plano já criado na sua conta. Caso você ainda não tenha, basta voltar à seção Planos e aprender como fazer isso.
Com o plano criado, basta então realizar a criação da assinatura utilizando os parâmetros abaixo e seguindo os exemplos.
Parâmetros de uma assinatura
Aprenda um pouco mais sobre os parâmetro usados nos exemplos a seguir, e como ajustá-los para a sua aplicação:
| Parâmetro | Padrão | Descrição |
|---|---|---|
plan_idObrigatório | -- | ID do plano a ser associado a assinatura. |
| payment_method | "credit_card" | Método de pagamento da assinatura. Pode ser credit_card ou boleto. |
card_hash ou card_idObrigatório (caso payment_method = credit_card) | -- | Dados encriptados do cartão do cliente. Para saber mais sobre esses parâmetros você pode dar uma olhada na seção Obtendo os dados do Cartão. |
| postback_url | -- | URL de sua aplicação, para a qual a nossa API envia requisições informativas sobre mudanças de status e criação de transações na assinatura. |
| boleto_expiration_date | Data atual + 7 dias | Prazo limite para pagamento do boleto. Deve ser passado no formato yyyy-mm-dd. |
customer[email]Obrigatório | -- | E-mail do cliente. |
customer[name]Obrigatório | -- | Nome completo ou razão social do cliente. |
customer[document_number]Obrigatório | -- | CPF ou CNPJ do cliente, sem separadores. |
customer[address][street]Obrigatório | -- | Rua ou Avenida da residência do cliente. |
customer[address][street_number]Obrigatório | -- | Número da residência do cliente. |
| customer[address][complementary] | -- | Complemento do endereço do cliente. |
customer[address][neighborhood]Obrigatório | -- | Bairro de residência do cliente. |
customer[address][zipcode]Obrigatório | -- | CEP do imóvel do cliente, sem separadores. |
customer[phone][ddd]Obrigatório | -- | DDD do telefone do cliente. |
customer[phone][number]Obrigatório | -- | Número do telefone do cliente. |
| customer[gender] | -- | Gênero do cliente. |
| custome[born_at] | -- | Data de nascimento do cliente. Ex: 11-02-1985. |
| soft_descriptor | -- | Descrição que aparecerá na fatura depois do nome de sua empresa. Máximo de 13 caracteres, sendo alfanuméricos e espaços. |
| reference_key | -- | Valor único que identifica a primeira transação da assinatura e impede que a mesma operação seja executada duas vezes. OBS: Não pode ser igual a um valor já usado em uma criação de transação. |
| metadata | -- | Você pode passar dados adicionais na criação da transação. Ex: metadata [idProduto]=13933139. |
| boleto_fine[days] | -- | Dias após a expiração do boleto quando a multa deve ser cobrada. |
| boleto_fine[amount] | -- | Valor em centavos da multa. |
| boleto_fine[percentage] | -- | Valor em porcentagem da multa. |
| boleto_interest[days] | -- | Dias após a expiração do boleto quando o juros deve ser cobrado. |
| boleto_interest[amount] | -- | Valor em centavos da taxa de juros que será cobrado por dia. |
| boleto_interest[percentage] | -- | Valor em porcentagem da taxa de juros que será cobrado por dia. |
Mais informações em Objeto Assinatura.
Formas de pagamento
Na hora de criar uma nova assinatura você deve enviar o parâmetro payment_method (método de pagamento) para identificar qual dos dois métodos possíveis você deseja utilizar nesta assinatura. Sendo que por padrão iremos atribuir o valor de credit_card para ele, ou seja, se você não enviar esse parâmetro iremos assumir que se trata de uma assinatura com cartão.
Lembrando que esse método de pagamento deve estar disponível no plano que deseja utilizar, mais informações em Parâmetros de um plano.
Criando uma assinatura
Para criar uma assinatura tudo que precisamos é que você envie uma requisição para a rota Criando assinaturas contendo pelo menos todos os parâmetros obrigatórios listados acima.
Exemplos de criação
Você pode usar os nossos SDKs para criar assinaturas, ou fazer a chamada diretamente em nossa API. Veja alguns exemplos:
Exemplo de criação de assinatura com payment method (método de pagamento) igual a credit_card:
curl -X POST https://api.pagar.me/1/subscriptions -H 'content-type: application/json' -d '{
"api_key": "SUA_API_KEY",
"card_id": "card_ci234fx8rr649rt16rtb11132",
"customer": {
"address": {
"neighborhood": "Cidade Monções",
"street": "Rua Dr.Geraldo Campos Moreira",
"street_number": "240",
"zipcode": "04571020"
},
"document_number": "92545278157",
"email": "[email protected]",
"name": "John Appleseed",
"phone": {
"ddd": "11",
"number": "15510101"
}
},
"payment_method": "credit_card",
"plan_id": "12783",
"postback_url": "http://requestb.in/zyn5obzy"
}'
require 'pagarme'
PagarMe.api_key = "SUA_API_KEY"
plan = PagarMe::Plan.find_by_id("12783")
subscription = PagarMe::Subscription.new({
:payment_method => 'credit_card',
:card_hash => "CARD_HASH_GERADO",
:postback_url => "http://test.com/postback",
:customer => {
:name => "John Appleseed",
:document_number => "92545278157",
:email => "[email protected]",
:address => {
:street => "Rua Dr. Geraldo Campos Moreira",
:neighborhood => "Cidade Monções",
:zipcode => "04571020",
:street_number => "240"
},
:phone => {
:ddd => "11"
:number => "15510101"
}
}
})
subscription.plan = plan
subscription.create
<?php
require("vendor/autoload.php");
$pagarme = new PagarMe\Client('SUA_CHAVE_DE_API');
$subscription = $pagarme->subscriptions()->create([
'plan_id' => 123456,
'payment_method' => 'credit_card',
'card_number' => '4111111111111111',
'card_holder_name' => 'UNIX TIME',
'card_expiration_date' => '0722',
'card_cvv' => '123',
'postback_url' => 'http://postbacj.url',
'customer' => [
'email' => '[email protected]',
'name' => 'Unix Time',
'document_number' => '75948706036',
'address' => [
'street' => 'Rua de Teste',
'street_number' => '100',
'complementary' => 'Apto 666',
'neighborhood' => 'Bairro de Teste',
'zipcode' => '11111111'
],
'phone' => [
'ddd' => '01',
'number' => '923456780'
],
'gender' => 'other',
'born_at' => '1970-01-01',
],
'metadata' => [
'foo' => 'bar'
]
]);
?>
PagarMeService.DefaultApiKey = "SUA_API_KEY";
Subscription subscription = new Subscription
{
PaymentMethod = PaymentMethod.CreditCard;
CardHash = "CARD_HASH_GERADO";
};
subscription.Plan = PagarMeService.GetDefaultService().Plans.Find(12783);
Customer customer = new Customer {
Name = "John Appleseed",
DocumentNumber = "92545278157",
Email = "[email protected]",
Address = new Address() {
Street = "Rua Dr. Geraldo Campos Moreira",
Neighborhood = "Cidade Monções",
Zipcode = "04571020",
StreetNumber = "240"
},
Phone = new Phone {
Ddd = "11",
Number = "15510101"
}
};
subscription.Customer = customer;
subscription.Save();
import me.pagar.model.Customer;
import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Subscription;
PagarMe.init("SUA_API_KEY");
Phone phone = new Phone();
phone.setDdd("11");
phone.setDdi("55");
phone.setNumber("99999999");
String street = "Avenida Brigadeiro Faria Lima";
String streetNumber = "1811";
String neighborhood = "Jardim Paulistano";
String zipcode = "01451001";
Address address = new Address(street, streetNumber, neighborhood, zipcode);
String name = "Aardvark Silva";
String email = "[email protected]";
String documentNumber = "18152564000105";
Customer customer = new Customer(name, email);
customer.setAddress(address);
customer.setPhone(phone);
customer.setDocumentNumber(documentNumber);
Card card = new Card();
card.setNumber("4901720080344448");
card.setHolderName("Jose da Silva");
card.setExpiresAt("1219");
card.setCvv(122);
card.save();
Subscription subscription = new Subscription();
subscription.setCreditCardSubscriptionWithCardId("122539", card.getId(), customer);
subscription.save();
import pagarme from 'pagarme'
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
.then(client => client.subscriptions.create({
plan_id: 12783,
card_id: 'CARD_ID',
payment_method:'credit_card',
customer: {
email: '[email protected]',
name: 'Daenerys Targaryen',
document_number: '18152564000105',
address: {
zipcode: '04571020',
neighborhood: 'Dragon Village',
street: 'Rua Drogon',
street_number: '240'
},
phone: {
number: '987654321',
ddd: '11'
}
}
}))
import pagarme
pagarme.authentication_key('SUA_API_KEY')
plan_params = {
'amount': '10000',
'days': '30',
'trial_days': '0',
'name': 'Credit card Plan',
'payment_methods': ['credit_card']
}
plan = pagarme.plan.create(plan_params)
customer_params = {
'email': '[email protected]',
'name': 'Daenerys Targaryen',
'document_number': '18152564000105',
'address': {
'zipcode': '04571020',
'neighborhood': 'Dragon Village',
'street': 'Rua Drogon',
'street_number': '240'
},
'phone': {
'number': '987654321',
'ddd': '11'
}
}
subscription_params = {
'plan_id': plan['id'],
'card_id': 'CARD_ID',
'customer': customer_params,
'payment_method':'credit_card',
'postback_url': 'http://urlTeste.com'
}
subscription = pagarme.subscription.create(subscription_params)
print (subscription)
Exemplo de criação de assinatura com payment method (método de pagamento) igual a boleto:
curl -X POST https://api.pagar.me/1/subscriptions -H 'content-type: application/json' -d '{
"api_key": "SUA_API_KEY",
"customer": {
"address": {
"neighborhood": "Cidade Monções",
"street": "Rua Dr.Geraldo Campos Moreira",
"street_number": "240",
"zipcode": "04571020"
},
"document_number": "92545278157",
"email": "[email protected]",
"name": "John Appleseed",
"phone": {
"ddd": "11",
"number": "15510101"
}
},
"payment_method": "boleto",
"plan_id": "12783",
"postback_url": "http://requestb.in/zyn5obzy"
}'
require 'pagarme'
PagarMe.api_key = "SUA_API_KEY"
plan = PagarMe::Plan.find_by_id("12783")
subscription = PagarMe::Subscription.new({
:payment_method => 'boleto',
:postback_url => "http://test.com/postback"
:customer => {
:name => "John Appleseed",
:document_number => "92545278157",
:email => "[email protected]",
:address => {
:street => "Rua Dr. Geraldo Campos Moreira",
:neighborhood => "Cidade Monções",
:zipcode => "04571020",
:street_number => "240"
},
:phone => {
:ddd => "11"
:number => "15510101"
}
}
})
subscription.plan = plan
subscription.create
<?php
require("vendor/autoload.php");
$pagarme = new PagarMe\Client('SUA_CHAVE_DE_API');
$subscription = $pagarme->subscriptions()->create([
'plan_id' => 123456,
'payment_method' => 'boleto',
'postback_url' => 'http://postback.url',
'customer' => [
'email' => '[email protected]',
'name' => 'Unix Time',
'document_number' => '75948706036',
'address' => [
'street' => 'Rua de Teste',
'street_number' => '100',
'complementary' => 'Apto 666',
'neighborhood' => 'Bairro de Teste',
'zipcode' => '11111111'
],
'phone' => [
'ddd' => '01',
'number' => '923456780'
],
'gender' => 'other',
'born_at' => '1970-01-01',
],
'metadata' => [
'foo' => 'bar'
]
]);
?>
PagarMeService.DefaultApiKey = "SUA_API_KEY";
Subscription subscription = new Subscription();
subscription.PaymentMethod = PaymentMethod.Boleto;
subscription.Customer = new Customer() {
Name = "John Appleseed",
DocumentNumber = "92545278157",
Email = "[email protected]",
Address = new Address() {
Street = "Rua Dr. Geraldo Campos Moreira",
Neighborhood = "Cidade Monções",
Zipcode = "04571020",
StreetNumber = "240"
},
Phone = new Phone() {
Ddd = "11",
Number = "15510101"
}
};
subscription.Save();
import me.pagar.model.Customer;
import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Subscription;
PagarMe.init("SUA_API_KEY");
Phone phone = new Phone();
phone.setDdd("11");
phone.setDdi("55");
phone.setNumber("99999999");
String street = "Avenida Brigadeiro Faria Lima";
String streetNumber = "1811";
String neighborhood = "Jardim Paulistano";
String zipcode = "01451001";
Address address = new Address(street, streetNumber, neighborhood, zipcode);
String name = "Aardvark Silva";
String email = "[email protected]";
String documentNumber = "18152564000105";
Customer customer = new Customer(name, email);
customer.setAddress(address);
customer.setPhone(phone);
customer.setDocumentNumber(documentNumber);
Subscription subscription = new Subscription();
subscription.setBoletoSubscription("122539", customer);
subscription.save();
import pagarme from 'pagarme'
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
.then(client => client.subscriptions.create({
plan_id: 1337,
postback_url: 'http://requestb.in/zyn5obzy',
payment_method: 'boleto',
customer: {
email: '[email protected]',
name: 'Daenerys Targaryen',
document_number: '18152564000105',
address: {
zipcode: '04571020',
neighborhood: 'Dragon Village',
street: 'Rua Drogon',
street_number: '240'
},
phone: {
number: '987654321',
ddd: '11'
}
}
}))
import pagarme
pagarme.authentication_key('SUA_API_KEY')
plan_params = {
'amount': '10000',
'days': '30',
'trial_days': '0',
'name": 'Boleto Plan',
'payment_methods': ['boleto']
}
plan = pagarme.plan.create(plan_params)
customer_params = {
'email': '[email protected]',
'name': 'Daenerys Targaryen',
'document_number': '18152564000105',
'address': {
'zipcode': '04571020',
'neighborhood': 'Dragon Village',
'street': 'Rua Drogon',
'street_number': '240'
},
'phone': {
'number': '987654321',
'ddd': '11'
}
}
subscription_params = {
'plan_id': plan['id'],
'customer': customer_params,
'payment_method': 'boleto',
'postback_url': 'http://urlTeste.com'
}
subscription = pagarme.subscription.create(subscription_params)
print (subscription)
Alterando uma assinatura
Não é possível alterar os dados de um cliente em uma assinatura. Os únicos parâmetros que podem ser alterados são o método de pagamento, as informações do cartão de crédito a ser cobrado, as informações de juros e multa de boleto e o plano atrelados à ela. Sendo sempre recomendado realizar essas operações separadamente uma da outra.
Mais informações sobre o fluxo de atualização na seção Fluxos de cobrança e sobre a rota de atualização em Atualizando uma assinatura.
Caso deseje alterar algum outro parâmetro recomendamos que seja criada um nova assinatura.
Pulando cobranças de uma assinatura
Assim como foi mencionado no Overview , se uma assinatura estiver com o status unpaid ou pending_payment, é possível dar baixa em uma ou mais parcelas que não foram pagas. Quando você faz isso, a assinatura volta a ter status paid e novas cobranças serão feitas normalmente.
É possível negociar e cobrar diretamente com o cliente essas parcelas que você deu baixa, sem interferir no fluxo da assinatura. Veja o exemplo:
curl -X POST https://api.pagar.me/1/subscriptions/ID_DA_ASSINATURA/settle_charge -H 'content-type: application/json' -d '{
"api_key": "SUA_API_KEY"
}'
require 'pagarme'
PagarMe.api_key = "SUA_API_KEY"
subscription_id = "ID_DA_ASSINATURA"
subscription = PagarMe::Subscription.find_by_id(subscription_id)
subscription.settle_charge
<?php
require("vendor/autoload.php");
$pagarme = new PagarMe\Client('SUA_CHAVE_DE_API');
$settledCharges = $pagarme->subscriptions()->settleCharges([
'id' => ID_DA_ASSINATURA,
'charges' => 2
]);
import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Subscription;
PagarMe.init("SUA_API_KEY");
Subscription subs = new Subscription().find("ID_DA_ASSINATURA");
subs.settleCharges(NUMERO_DE_COBRANÇAS_A_SER_PULADA);
import pagarme
pagarme.authentication_key('SUA_API_KEY')
subscription = pagarme.subscription.settle_charges("ID_DA_ASSINATURA")
print (subscription)
Exemplo de resposta da requisição de settle_charge :
{
"object": "subscription",
"plan": {
"object": "plan",
"id": 384333,
"amount": 10000,
"days": 30,
"name": "Plano Ouro",
"trial_days": 0,
"date_created": "2020-06-03T16:15:05.093Z",
"payment_methods": [
"boleto"
],
"color": null,
"charges": null,
"installments": 1,
"invoice_reminder": null,
"payment_deadline_charges_interval": 1
},
"id": 496021,
"current_transaction": {
"object": "transaction",
"status": "waiting_payment",
"refuse_reason": null,
"status_reason": "acquirer",
"acquirer_response_code": null,
"acquirer_name": "pagarme",
"acquirer_id": "5d8ba002986fde717ic27557",
"authorization_code": null,
"soft_descriptor": null,
"tid": 8074332,
"nsu": 8074332,
"date_created": "2020-06-27T22:17:38.974Z",
"date_updated": "2020-06-27T22:17:39.257Z",
"amount": 10000,
"authorized_amount": 10000,
"paid_amount": 0,
"refunded_amount": 0,
"installments": 1,
"id": 8074332,
"cost": 0,
"card_holder_name": null,
"card_last_digits": null,
"card_first_digits": null,
"card_brand": null,
"card_pin_mode": null,
"card_magstripe_fallback": false,
"cvm_pin": null,
"postback_url": null,
"payment_method": "boleto",
"capture_method": "ecommerce",
"antifraud_score": null,
"boleto_url": "https://pagar.me",
"boleto_barcode": "1234 5678",
"boleto_expiration_date": "2020-06-28T22:17:38.867Z",
"referer": null,
"ip": null,
"subscription_id": 496021,
"metadata": {},
"antifraud_metadata": {},
"reference_key": null,
"device": null,
"local_transaction_id": null,
"local_time": null,
"fraud_covered": false,
"fraud_reimbursed": null,
"order_id": null,
"risk_level": "unknown",
"receipt_url": null,
"payment": null,
"addition": null,
"discount": null,
"private_label": null
},
"postback_url": "http://requestb.in/zyn5obzy",
"payment_method": "boleto",
"card_brand": null,
"card_last_digits": null,
"current_period_start": "2020-06-27T22:17:38.867Z",
"current_period_end": "2020-07-27T22:17:38.867Z",
"charges": 2,
"soft_descriptor": null,
"status": "pending_payment",
"date_created": "2020-06-03T16:16:10.721Z",
"date_updated": "2020-06-28T21:01:31.885Z",
"phone": null,
"address": null,
"customer": {
"object": "customer",
"id": 3063978,
"external_id": null,
"type": null,
"country": null,
"document_number": "92545278157",
"document_type": "cpf",
"name": "John Appleseed",
"email": "[email protected]",
"phone_numbers": null,
"born_at": null,
"birthday": null,
"gender": null,
"date_created": "2020-06-03T16:16:10.158Z",
"documents": []
},
"card": null,
"metadata": null,
"fine": {},
"interest": {},
"settled_charges": [
2
],
"manage_token": "test_subscription_w0lb9guxkZv6pk8l8pi0NPUbkzU3Aa",
"manage_url": "https://pagar.me/customers/#/subscriptions/496021?token=test_subscription_w0lb9guxkZv6pk8l8pi0NPUbkzU3Aa"
},
Perceba as seguintes mudanças na resposta:
- Status da assinatura: Volta para
paid. Current_transaction: Para assinaturas com cartão de crédito ela vai ficar como null e será preenchido somente quando o período da assinatura chegar ao fim, e a cobrança de renovação acontecer. Enquanto que para assinaturas de boleto, ela será preenchida com o próximo boleto a ser pago, sendo esse a nova transação gerada logo após a baixa na assinatura.Current_period_start: Vai para o dia em que foi dado baixa na assinatura.Current_period_end: Vira o dia em que foi dado baixa na assinatura acrescido do período do plano.Settled_charges: Mostra uma lista com as cobranças que tiveram baixa, durante todo o ciclo de vida da assinatura.
Excluindo uma assinatura
Não é possível excluir assinaturas criadas em nosso sistema, porém é possível atualizar ou cancelar uma assinatura. Para aprender mais sobre isso, veja: Atualizando uma assinatura e Cancelando uma assinatura.
Postbacks em assinaturas
Assinatura X Transação
Não enviamos postbacks para as transações criadas em uma assinatura, apesar de parecidos, os postbacks de assinatura são mais completos, tornando desnecessário o envio de postbacks para cada transação.
Os Postbacks são enviados toda vez que há uma alteração no status e/ou criação de transação em uma assinatura, conforme definido nas suas Configuração de Postback de assinatura.
Você pode obter mais informações sobre como os status são alterados na seção Fluxos de cobrança, mas, de forma geral, enviaremos um postback toda vez que alguma cobrança for gerada, quando ela for paga, quando ela não for paga, e qualquer outro evento que altere o status da assinatura.
Sendo importante ressaltar que o postback de uma assinatura não é o mesmo que o postback de uma transação, como descrito na seção formato de um postback, as informações contidas no postback de assinatura incluem também as informações da transação gerada por ela. Assim, nós não enviamos postbacks referentes as transações criadas por uma assinatura, pois entendemos que, as informações presentes no postback da assinatura são suficientes para atualizar seu sistema quanto a essas transações.
Por fim, vale lembrar que não enviamos postbacks no momento da criação da assinatura. Ou seja, assim que você cria sua assinatura não receberá nenhum postback sobre a primeira transação da mesma, já que todas as informações relevantes sobre essa transação estão contidas na resposta de nossa API. Assim, é necessário que seu sistema faça a leitura e tratamento dessas respostas para que você possa atualizar a condição inicial de sua assinatura em seu servidor.
Integrando assinaturas com Postback
Para fazer uso de nosso sistema de Postback basta adicionar o parâmetro postback_url, descrito na seção Parâmetros de uma assinatura, quando for criar sua assinatura. Assim, quando ela passar por qualquer evento de criação de postback, iremos enviar uma requisição para a url informada com as informações de sua assinatura, permitindo que você mantenha seu banco de dados atualizado.
Para que isso ocorra, você precisa garantir que o endpoint informado (postback_url) possa receber e interpretar nossas requisições de HTTP Method POST, incluindo o Body e o Header.
Sendo que o header “X-Hub-Signature” é particularmente importante para validar nossos postbacks, como descrito na seção Como validar um postback. Existem alguns passos que sua aplicação deve seguir para confirmar a legitimidade de nossos postbacks, afinal de contas, não queremos que uma pessoal mal intencionada atrapalhe o funcionamento de seu sistema enviando postbacks falsos.
Por fim, vale ressaltar que o processamento de requisições de criação de assinatura são sempre síncronos, ou seja, quando você nos envia uma requisição, nossa API irá processá-la e retornar para o seu servidor uma resposta que contém todas as informações da assinatura criada (ou uma mensagem de erro caso ela não seja criada), substituindo a utilidade de um “primeiro postback”, por isso foi decidido que não seria necessário o envio do postback após a criação da assinatura. Assim, é preciso que você implemente em seu sistema uma forma de interpretar o conteúdo das respostas de nossa API, para garantir que suas assinaturas foram criadas corretamente.
Formato de um postback
Na seção Formato do payload de um postback você pode ver como são estruturados e quais informações incluímos em nossos postbacks. Há algumas diferenças entre postbacks de transação e de assinatura, mas de forma geral, com esses exemplos de estrutura você será capaz de navegar entre os diferentes parâmetros que constam em nossos postbacks.
Porém, vale ressaltar que, ao contrario do postback de transação, você receberá um objeto de assinatura e será dentro desse objeto que haverá o parâmetro current_transaction que contém as informações da transação que foi paga.
Sendo que para assinaturas com pagamento por boleto, o current_transaction será referente a transação gerada após o pagamento do ultimo boleto.
Para aprender mais sobre isso, veja: Objeto-resposta Postback.
Configuração de Postback de assinatura
Para definir as configurações de postback das recorrências, basta acessar a página em sua Dashboard em Ver minha conta > Recorrência, e você verá as seguintes opções:
Nestes campos você pode definir se quer ou não receber as notificações de atualização de assinatura a cada mudança de status, a cada criação de nova transação ou ambos. Sendo que por padrão, iremos enviar os postbacks nas duas situações.
Depois de alterar todas os campos desejados, basta clicar sobre o botão “salvar alterações” para confirmar a atualização das informações.
Verificando seus Postbacks
Para verificar os status das entregas dos postbacks, você pode utilizar a nossa rota Lista de postbacks que retorna todos os postbacks de uma determinada transação ou assinatura. Cada tentativa de entrega é listada como um delivery possuindo tempo de resposta (response_time), status (que pode ser processing, success ou failed) e, quando existe, o código de resposta do endpoint (status_code). Pode encontrar mais detalhes sobre essa rota na nossa seção Verificando os postbacks.
Simulando um Postback de assinatura
Para simular um postback de uma assinatura em modo teste, você pode criar uma assinatura de boleto e simular o pagamento do mesmo, ou criar um plano com período de 1 dia e esperar a próxima cobrança no dia seguinte, ou até cancelar uma assinatura, assim haverá a mudança em seu status e a criação de transação, assim um postback é disparado.
Temos o postback de uma assinatura que você pode utilizar de exemplo:
Para realizar seus testes, é possível utilizar o programa request.bin ou o ngrok para gerar uma URL temporária (para servir de postback_url) capaz de receber nossas requisições de postback.
Cobranças em modo teste
Em assinaturas de boleto somente consideramos que foi realizada uma cobrança da assinatura após o pagamento de um de seus boletos, nesse momento também é gerado um novo boleto para essa assinatura referente a próxima cobrança, seguindo as limitações do parâmetro Charges. Assim, em ambiente de teste, é possível realizar quantas cobranças desejar, simplesmente simulando o pagamento dos boletos gerados.
Para simular o pagamentos de boletos, você pode utilizar de nossa rota da API Testando pagamento de Boletos ou então pressionando o botão presente em sua Dashboard, conforme a imagem abaixo.
Já para assinaturas de cartão, a primeira cobrança é realizada junto com a criação da assinatura, e as cobranças subsequentes serão feitas automaticamente por nosso sistema pelos próximos 60 dias após sua criação.
Você também pode simular a recusa de cobranças em sua assinatura de cartão, para isso, basta utilizar um plano de valor igual a R$789,11. Desta forma, somente a primeira cobrança será feita com sucesso. Mas vale lembrar que o valor deve ser especificado em centavos, amount = "78911".
Para simular as notificações de postback você pode tanto criar uma assinatura com um plano diário (days = 1), utilizar da simulação de pagamento em uma assinatura de boleto, de recusa de uma assinatura de cartão ou até mesmo cancelar sua assinatura.
Integração com outros produtos
Criando assinaturas com Split de pagamento
Além de cobrar o seu cliente de forma recorrente, você pode também fazer um split (divisão) dos valores gerados a cada transação criada. Para isso, além de passar os campos dos exemplos anteriores você deve passar também as regras de split. Veja o exemplo:
curl -X POST https://api.pagar.me/1/subscriptions -H "Content-Type: application/json" -d '{
"api_key":"SUA API KEY",
"card_number": "4242424242424242",
"card_cvv": "122",
"card_holder_name": "Aardvark Silva",
"card_expiration_date": "1220",
"customer":{
"email":"[email protected]",
"name":"nome",
"document_number":"35965816804",
"address":{
"zipcode":"06350270",
"neighborhood":"bairro",
"street":"rua",
"street_number":"122"
},
"phone": {
"number":"87654321",
"ddd":"11"
}
} ,
"plan_id":"89226",
"amount": 10000,
"split_rules": [
{
"recipient_id": "re_cj2wd5ul500d4946do7qtjrvk",
"percentage": 20,
"liable": true,
"charge_processing_fee": true
},{
"recipient_id": "re_cj2wd5u2600fecw6eytgcbkd0",
"percentage": 80,
"liable": true,
"charge_processing_fee": true
}
]
}'
require 'pagarme'
PagarMe.api_key = "SUA API KEY"
plan = PagarMe::Plan.find_by_id("12783")
subscription = PagarMe::Subscription.new({
:payment_method => 'credit_card',
:card_number => "4901720080344448",
:card_holder_name => "Jose da Silva",
:card_expiration_month => "10",
:card_expiration_year => "15",
:card_cvv => "314",
:postback_url => "http://test.com/postback",
:customer => {
:name => "John Appleseed",
:document_number => "92545278157",
:email => "[email protected]",
:address => {
:street => "Rua Dr. Geraldo Campos Moreira",
:neighborhood => "Cidade Monções",
:zipcode => "04571020",
:street_number => "240"
},
:phone => {
:ddd => "11"
:number => "15510101"
}
},
:split_rules: [
{
recipient_id: "re_cj2wd5ul500d4946do7qtjrvk",
percentage: 10,
liable: true,
charge_processing_fee: true
} ,
{
recipient_id: "re_cj2wd5u2600fecw6eytgcbkd0",
percentage: 90,
liable: true,
charge_processing_fee: true
}
])
subscription.plan = plan
subscription.create
<?php
require("vendor/autoload.php");
$pagarme = new PagarMe\Client('SUA_CHAVE_DE_API');
$subscription = $pagarme->subscriptions()->create([
'plan_id' => 123456,
'card_id' => 'card_abc123456',
'payment_method' => 'credit_card',
'postback_url' => 'http://www.pudim.com.br',
'customer' => [
'email' => '[email protected]',
'name' => 'Unix Time',
'document_number' => '75948706036',
'address' => [
'street' => 'Rua de Teste',
'street_number' => '100',
'complementary' => 'Apto 666',
'neighborhood' => 'Bairro de Teste',
'zipcode' => '88370801'
],
'phone' => [
'ddd' => '01',
'number' => '923456780'
],
'gender' => 'other',
'born_at' => '1970-01-01',
],
'amount' => 10000,
'split_rules' => [
[
'recipient_id' => 're_abc1234abc1234abc1234abc1',
'percentage' => 20,
'liable' => true,
'charge_processing_fee' => true,
],
[
'recipient_id' => 're_abc1234abc1234abc1234abc1',
'percentage' => 80,
'liable' => true,
'charge_processing_fee' => true,
]
],
'metadata' => [
'foo' => 'bar'
]
]);
const pagarme = require('pagarme')
pagarme.client.connect({ api_key: 'SUA API KEY' })
.then(client => client.subscriptions.create({
plan_id: 133163,
payment_method: 'boleto',
customer: {
email: '[email protected]',
name: 'Daenerys Targaryen',
document_number: '18152564000105',
address: {
zipcode: '04571020',
neighborhood: 'Dragon Village',
street: 'Rua Drogon',
street_number: '240'
},
phone: {
number: '987654321',
ddd: '11'
}
},
split_rules: [
{
'recipient_id': 're_ciyoloogb0100l46dy6f1iuww',
'liable': 'true',
'charge_processing_fee': 'true',
'percentage': '55',
},
{
'recipient_id': 're_ciyol0qac00xnlg6dkaftvn9j',
'liable': 'false',
'charge_processing_fee': 'false',
'percentage': '45',
}
]
}))
.then(subscription => console.log(subscription))
.catch(error => console.log(error))
import pagarme
pagarme.authentication_key('SUA_API_KEY')
subscription = pagarme.subscription.create({
"card_id": "card_cj6qvosem04w3nu6dm20nu8od",
"customer":{
"email":"[email protected]",
"name":"Sir Jorah Mormont",
"document_number":"18152564000105",
"address":{
"zipcode":"04571020",
"neighborhood":"Cidade Moncoes",
"street":"R. Dr. Geraldo Campos Moreira",
"street_number":"240"
},
"phone": {
"number":"987654321",
"ddd":"11"
}
},
"split_rules":[
{
"recipient_id": "re_cj6p5tpqj0bp3oi6euostjng1",
"percentage": "25"
},
{
"recipient_id": "re_cj6cbuz041cs5mx6dx2fh5asx",
"percentage": "75"
}
],
"payment_method": "credit_card",
"plan_id": "201836",
"postback_url": "http://requestb.in/zyn5obzy"
})
print (subscription)
Lembrando que não é possível alterar a regra de divisão dos valores depois que a assinatura é criada. Saiba mais sobre como funciona nosso Split de pagamento na seção Dividindo uma transação.
Criando assinaturas com o Checkout Pagar.me
Para usar o Checkout Pagar.me com o nosso sistema de assinaturas, você precisa utilizar a propriedade create-token como False. Isso possibilita a captura dos dados inseridos no formulário e o retorno deles para a sua plataforma. Dessa forma, já na sua plataforma, você consegue fazer as chamadas para a criação das assinaturas, assim como nos exemplos anteriores.
Para entender mais sobre a diferença entre create-token True e False, acesse Inserindo o Checkout.
Veja o exemplo abaixo com create-token = False:
<html>
<head>
<!-- SCRIPT PAGAR.ME -->
<script src="https://assets.pagar.me/checkout/checkout.js"></script>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
</head>
<body>
<button id="pay-button">Abrir modal de pagamento</button>
<script>
$(document).ready(function() {
var button = $('#pay-button');
button.click(function() {
// INICIAR A INSTÂNCIA DO CHECKOUT
// declarando um callback de sucesso
var checkout = new PagarMeCheckout.Checkout({"encryption_key":"ENCRYPTION KEY", success: function(data) {
console.log(data);
//Tratar aqui as ações de callback do checkout, como exibição de mensagem ou envio de token para captura da transação
}});
// DEFINIR AS OPÇÕES
// e abrir o modal
// É necessário passar os valores boolean em "var params" como string
var params = {"customerData":"false", "amount":"100000", "createToken": "false", "interestRate": 10 };
checkout.open(params);
});
});
</script>
</body>
</html>
<form method="POST" action="/comprar">
<script type="text/javascript"
src="https://assets.pagar.me/checkout/checkout.js"
data-button-text="Pagar"
data-encryption-key="ek_test_Ec8KhxISQ1tug1b8bCGxC2nXfxqRmk"
data-amount="1000"
data-create-token="false">
</script>
</form>
Usando essa configuração o Checkout captura as informações inseridas no formulário e envia para o action que você especificou, ou retorna no callback de sucesso, caso você esteja usando a versão JS.
Os dados retornados são: customer (incluindo nome, email e endereço), payment_method escolhido (boleto ou credit_card) e, caso Cartão de crédito tenha sido escolhido como método de pagamento, o Checkout também gera e envia um card_hash.
O próximo passo é tratar essas informações, e usar um dos exemplos anteriores para criar a assinatura.
Criando assinaturas com plataformas
Atualmente, as integrações disponibilizadas pelo Pagar.me para as plataformas Woocommerce e Magento não possuem suporte para utilizar de nosso produto de Recorrência.
Para as demais integrações consulte o responsável por sua plataforma.
Updated about 4 years ago
Agora que você já sabe como criar planos e assinaturas, é hora de aprender um pouco mais sobre o fluxo de cobrança de Recorrência. Começando por alguns conceitos e configurações importantes.