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 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 [email protected] 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": "[email protected]",
    "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 [email protected], 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.