Criando uma transação

📘

Boleto em PDF

Além da versão HTML dos boletos retornada pela API, é possível gerar uma versão em PDF. Para tal basta adicionar o sufixo ?format=pdf na url retornada. Segue um exemplo:
URL ORIGINAL: https://api.pagar.me/1/boletos/test_ckj9yiyvy1obb0gm5g9yfpgbw
URL PDF: https://api.pagar.me/1/boletos/test_ckj9yiyvy1obb0gm5g9yfpgbw?format=pdf

📘

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, billing e shipping com essas características para que o antifraude faça a análise corretamente.

📘

Transações recusadas

Em ambiente de teste é possível simular uma transação recusada pela operadora do cartão usando um cvv iniciado com 6

📘

Não guardamos CVV

Em nosso card_id, não armazenamos o cvv do cartão. Mas você pode passar o campo na request, para adicionar uma camada de validação e segurança para a sua transação.

📘

Campo 'customer.name'

Para transações usando boleto como método de pagamento, o campo 'customer.name' é obrigatório.

📘

Campo 'session'

O campo 'session' permite que a visita do usuário à sua loja seja utilizada para análises de fraude. Ele funciona a partir do identificador de sessão do usuário no seu site. Você deve fornecê-lo se estiver com o antifraude habilitado e fizer uso do script de fingerprint na sua loja.

🚧

card_hash e card_id

Apesar de existir a possibilidade de colocar os dados do cartão diretamente na requisição, sugerimos não faze-lo por motivos de segurança. Por isso, é possível optar por usar o card_hash ou o card_id. Não é necessário informar os ambos, somente um.

🚧

Transação síncrona com postback

Se o parâmetro async for false e você passar uma postback_url, a transação continua sendo síncrona (isto é, a resposta é recebida na hora), mas o seu sistema mesmo assim recebe notificações para a mudança de status da transação.

🚧

card_hash

O card_hash, representação dos dados do cartão encriptados, não pode ser usado mais de uma vez e deve ser consumido em até 5 minutos! Veja mais neste link.

🚧

Antifraude

Dados do cliente e de compra (customer, billing e items) são obrigatórios para transações de Cartão de crédito, devido ao antifraude.

❗️

Parâmetro local_time

O campo local_time deve ser enviado apenas em transações de mundo físico, nas quais o método de captura seja EMV ou Magstripe. Ele representa o horário atual do dispositivo que está realizando a transação.

❗️

Análise manual pelo antifraude

Caso a sua loja esteja habilitada com análise manual pelo antifraude, é imprescindível que toda transação possua o campo async com o valor true. É necessário também fornecer um postback_url, através do qual você receberá atualizações sobre o status da transação.

❗️

Metadata

A API espera que o schema do metadata enviado seja consistente, ou seja, se em uma transação é enviado um metadado com o formato:

{
  ...
  "metadata": {
    "pedido": 1
  }
}

a seguinte mudança não deve ser feita (mudança do tipo de 'pedido'):

{
  ...
  "metadata": {
    "pedido": "2"
  }
}

Apesar disso não restringimos a adição de novas chaves em transações posteriores como:

{
  ...
  "metadata": {
    "pedido": 3,
    "cliente": 1
  }
}

❗️

Metadata 2

O metadata deve ser um objeto json. Logo os metadados a seguir são inválidos:

{
  ...
  "metadata": ["order", "cart"]
}

{
  ...
  "metadata": "order"
}