Overview

❗️

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, sendo responsável por impedir que uma compra ilegítima aconteça. É esse elemento que protege a sua plataforma contra perdas financeiras por chargeback. Para aprender mais sobre sobre o assunto, clique em: Como funciona o antifraude.

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 [email protected], para encontrar uma solução que atenda às suas necessidades de forma segura.

2. Dados de customer

Quando o antifraude está habilitado na sua conta, é necessário enviar os dados do comprador final, assim como é mostrado nesse exemplo:

"customer": {
  "name": "Aardvark Silva",
  "document_number": "18152564000105",
  "email": "[email protected]",
  "address":{
    "street": "Rua Dr. Geraldo Campos Moreira",
    "street_number": "240",
    "zipcode": "04571020",
    "neighborhood": "Cidade Monções"
  },
  "phone":{
    "ddd": "11",
    "number": "99999999"
  }
}

Os 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 pedir estes dados ao customer na hora da compra, entre em contato com o nosso atendimento pelo e-mail [email protected], para encontrarmos a melhor solução baseada na realidade do seu negócio.

Existência do CEP

Por padrão, existe uma verificação da existência do CEP (zipcode) informado sempre que uma transação é criada. Essa validação é feita para garantir que os dados existem e para completar a informação de endereço com sua respectiva cidade e estado.

Se a sua plataforma já fizer essa validação ou se, por outros motivos, você quiser desabilitar essa função na sua Dashboard Dashboard, é necessário que você envie os dados de cidade e estado dentro do escopo de customer. Isso é necessário por causa da camada de segurança do antifraude. Por exemplo:

"customer": {
  "name": "Aardvark Silva",
  "document_number": "18152564000105",
  "email": "[email protected]",
  "address":{
    "street": "Rua Dr. Geraldo Campos Moreira",
    "street_number": "240",
    "zipcode": "04571020",
    "neighborhood": "Cidade Monções",
    "city": "São Paulo",
    "state": "São Paulo"
  },
  "phone":{
    "ddd": "11",
    "number": "99999999"
  }
}

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?

Existem 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.