Bem-vindo à documentação pagar.me

Aqui você vai encontrar guias e exemplos para te ajudar
a integrar com a melhor API de Pagamentos do Brasil!

Começar

Você também pode buscar ou navegar pelas categorias

Você está na versão correta da documentação?

Verifique na sua Dashboard, em Ver minha conta > Configurações > API Keys, a versão da API que você está usando. Você deve usar a documentação correspondente. Para saber mais, veja: Versionamento

Ao integrar com a API do Pagar.me, você pode criar transações a partir dos pedidos feitos na sua plataforma. É possível usar os mecanismos de cartão de crédito e boleto para efetuar os pagamentos. Os itens a seguir explicam de forma mais detalhada como criar uma transação de cada tipo:

  1. Capturar os dados do cliente: Obtendo os dados do Cartão
  2. Criar a transação de Cartão de crédito ou Boleto bancário

É importante também entender os conceitos a seguir, para que a sua operação esteja alinhada com todos os detalhes do nosso produto.

1. Antifraude

O antifraude faz parte do fluxo de criação de uma transação com cartão de crédito, sendo responsável por impedir que uma compra ilegítima aconteça. É esse elemento que protege a sua plataforma contra perdas financeiras por chargeback.

Por uma questão de segurança para o seu negócio e também para o Pagar.me, o antifraude está habilitado por padrão na sua conta. Se você precisar desativar a ferramenta, entre em contato com o nosso atendimento pelo e-mail relacionamento@pagar.me para encontrar uma solução que atenda às suas necessidades de forma segura.

2. Dados do cliente

Quando o antifraude está habilitado na sua conta, é necessário enviar os dados do comprador final, o endereço de cobrança, o endereço de envio e algumas informações sobre itens vendidos (customer, billing, shipping e items, respectivamente).

Note que o endereço de entrega (shipping) não é obrigatório, mas é recomendado no caso de bens físicos. Para indicar um bem físico, a propriedade tangible, descrita dentro de items, deve ser configurada como "true". O exemplo abaixo demonstra como isso é feito:

  "customer": {
    "external_id": "#123456789",
    "name": "João das Neves",
    "type": "individual",
    "country": "br",
    "email": "joaoneves@norte.com",
    "documents": [
      {
        "type": "cpf",
        "number": "30621143049"
      }
    ],
    "phone_numbers": ["+5511999999999", "+5511888888888"],
    "birthday": "1985-01-01"
  },
  "billing": {
    "name": "João das Neves",
    "address": {
      "country": "br",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "Vila Carrao",
      "street": "Rua Lobo",
      "street_number": "999",
      "zipcode": "03424030"
    }
  },
  "shipping": {
    "name": "João das Neves",
    "fee": 1000,
    "delivery_date": "2017-12-25",
    "expedited": true,
    "address": {
      "country": "br",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "Vila Carrao",
      "street": "Rua Lobo",
      "street_number": "999",
      "zipcode": "03424030"
    }
  },
  "items": [
    {
      "id": "a123",
      "title": "Trono de Ferro",
      "unit_price": 120000,
      "quantity": 1,
      "tangible": true
    },
    {
      "id": "b123",
      "title": "Capa Negra de Inverno",
      "unit_price": 30000,
      "quantity": 1,
      "tangible": true
    }
  ]

Esses dados são necessários para a análise do antifraude, então é obrigatório que eles sejam fornecidos em transações com cartão de crédito.

Se, por alguma razão, a sua plataforma não puder pedir estes dados ao cliente na hora da compra, entre em contato com o nosso atendimento pelo e-mail relacionamento@pagar.me, para encontrarmos a melhor solução baseada na realidade do seu negócio.

Compradores estrangeiros

Ao contrário das versões 2013-03-01 e 2017-07-17 da nossa API, essa versão aceita documentos de compradores estrangeiros e endereços internacionais, e não apenas CPF/CNPJ e CEP. Dessa forma, é possível passar dados de customer com essas características para que o antifraude faça a análise corretamente.

É importante notar que o comportamento de verificação da existência do CEP e do preenchimento dos campos de endereço a partir do CEP (antes presente nas versões 2013-03-01 e 2017-07-17) não ocorre mais.

3. Verificação de cartão

Existe uma validação de Cartão de crédito, que é feita em dois momentos independentes:

  • Ao criar um cartão em nossa API. Saiba mais em: Criando um cartão
  • Ao criar uma assinatura com período de trial e cobrança em Cartão de crédito. Saiba mais em: Criando assinaturas

Nos dois casos, a nossa API faz uma autorização no valor de R$1,23 em conjunto com o banco emissor para garantir que o cartão existe, e que uma cobrança real pode ser feita posteriormente. Após a confirmação da transação, nós já fazemos o estorno de forma automática.

Para aprender mais sobre esse processo, acesse: Cobrança de R$1,23.

4. O que é um card_hash?

Você vai ver esse termo muitas vezes ao longo da nossa documentação, então é importante entender o que ele representa.

Em transações por Cartão de crédito, o Pagar.me precisa passar para o banco emissor alguns dados sensíveis, como o número do cartão e data de expiração. Pensando na segurança de todos os envolvidos no processo, nós desenvolvemos uma maneira de criptografar esses dados. Ou seja, eles trafegam entre a sua plataforma e o Pagar.me de maneira extremamente segura.

Chamamos a criptografia dos dados de cartão card_hash. A sua plataforma deve enviar os dados neste formato para que uma transação seja criada.

Resumindo

O card_hash é uma representação segura dos dados de cartão, que pode ser usado para criar cartões, transações ou assinaturas junto à API Pagar.me.

Como criar um card_hash?

Caso você esteja usando o Checkout Pagar.Me, ele já cuida de todos os detalhes técnicos para sua plataforma, assim como nossas Bibliotecas. No entanto, se for necessário gerar um card_hash manualmente, isso é possível. Nós explicamos esse processo em: Gerando card_hash.

5. Autorização e captura

Ao criar uma transação com o Pagar.me, o sistema primeiro faz uma reserva e depois uma confirmação de cobrança no saldo do portador do cartão. Estes dois processos são respectivamente chamados de autorização e captura e podem ser feitos separadamente. Ou seja, pode ser interessante em algum momento de sua operação que uma transação seja apenas autorizada, enquanto a sua plataforma faz alguma validação de estoque, por exemplo.

Depois, uma vez que você queira confirmar essa transação, a sua plataforma deve pedir a captura para API Pagar.me. Depois da captura, o sistema solicita ao banco emissor a cobrança de fato da quantia na fatura do cartão de seu cliente. Você não precisa fazer esses dois processos separadamente, mas, se for necessário, isso é possível.

Como fazer?

Você pode aprender os detalhes desse procedimento em: Cartão de crédito

Funciona para boleto?

Sim. Ao confirmar a captura da transação a API Pagar.me vai gerar a URL e o código de barras do boleto, para que você consiga enviar essas informações ao seu cliente.

Até depois de quanto tempo posso fazer a captura?

Existe duas possibilidades para transações somente autorizadas:

  • Feitas com a sua API Key: nesse caso, a sua plataforma tem até 5 dias para confirmar a captura. Após esse período, o estorno é feito automaticamente pelo banco emissor para transações com cartão de crédito.

  • Feitas com o Checkout Pagar.Me: nesse caso, o tempo é menor, já que o Checkout usa como forma de autenticação a Encryption Key. Logo, o tempo para a captura é de no máximo 5 horas. Após esse período, a API Pagar.me realiza o estorno automaticamente e marca a transação como recusada. Além disso, é atribuída à transação o erro capture_timeout.


Próximo

Aprenda agora a obter os dados necessários para criar sua transação por Cartão de crédito. Ou, para uma transação mais simples, vejo Boleto bancário.

Obtendo os dados do Cartão
Boleto bancário

Overview


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.