Princípios básicos

Você tem certeza de que 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.

Bem-vindo ao guia de referências da API do Pagar.me! É através desta API que você integra o seu sistema ao nosso. Além disso, você também pode recriar as funcionalidades existentes na nossa Dashboard, que são feitas consumindo a API que está aqui descrita.

Nossa API é RESTful, e todas suas respostas são em JSON, no endpoint base:


https://api.pagar.me/1/

A seguir, algumas convenções de nossa API:

Paginação

Há muitas rotas de listagem de entidades na API. Em todas elas é necessário lidar com um sistema de paginação para percorrer todas as instâncias. Esse sistema refere-se aos parâmetros count e page. Count representa quantos resultados por página deverão ser retornados — se não for informado um valor, o padrão é 10. Page é a página a ser retornada e se não for informado um valor, o padrão é 1.

Autenticação

Sempre que a sua aplicação chama algum de nossos endpoints, você deve passar como forma de autenticação a sua API Key, chave que pode ser encontrada na sua Dashboard.

A API Key pode ser informada de três forma diferentes:
1 - No corpo da requisição como valor do parâmetro api_key
2 - Na url (query param) como valor do parâmetro api_key
3 - Basic Auth com username igual à chave e senha igual a x (xis minúsculo)

Suggest Edits

Ambientes de teste e produção

Suggest Edits

Códigos de resposta

Suggest Edits

Erros

Os possíveis erros retornados pela API Pagar.Me são:

Tipo do erro

Significado

invalid_parameter

Quando algum parâmetro passado está incorreto/faltando.

action_forbidden

Quando o usuário não tem permissão para fazer determinada ação.

internal_error

Quando algum erro interno em nosso servidor ocorreu.

not_found

Quando o recurso procurado não foi encontrado/não existe.

Exemplo de retorno pela API:

JSON

{
    "errors": [
        {
            "message": "api_key está faltando",
            "parameter_name": "api_key",
            "type": "invalid_parameter"
        }
    ],
    "method": "get",
    "url": "/transactions"
}

Suggest Edits

Criando uma transação

Para fazer uma cobrança você deve usar a rota /transactions para criar a sua transação, que pode ser feita por Cartão de crédito ou por Boleto bancário.

No caso de Cartão de crédito é possível utilizar um card_id, card_hash ou todos os dados do cartão diretamente. A segunda opção é a mais indicada, por fatores de segurança.

posthttps://api.pagar.me/1/transactions

Body Params

amount

int32

required

Valor a ser cobrado. Deve ser passado em centavos. Ex: R$ 10.00 = 1000. Deve ser no mínimo 1 real (100)

card_hash

string

required

Informações do cartão do cliente criptografadas em sua aplicação. OBS: apenas para transações de Cartão de crédito você deve passar o card_hash ou card_id

card_id

string

required

Ao realizar uma transação, retornamos o card_id do cartão, para que nas próximas transações ele possa ser utilizado como forma de identificar os dados de pagamento. Exemplo de utilização: One-click buy. OBS: apenas para transações de Cartão de crédito você deve passar o card_hash ou card_id

card_holder_name

string

required

Nome do portador do cartão. OBS: apenas para transações de Cartão de crédito você deve passar o card_holder_name

card_expiration_date

string

required

Data de validade do cartão no formato MMAA. OBS: apenas para transações de Cartão de crédito você deve passar o card_expiration_date

card_number

string

required

Número do cartão. OBS: apenas para transações de Cartão de crédito você deve passar o card_number

card_cvv

string

required

Código verificador do cartão. OBS: apenas para transações de Cartão de crédito você deve passar o card_cvv

payment_method

string

required

Método de pagamento da transação. Aceita dois tipos: credit_card e boleto

postback_url

string

Endpoint do seu sistema que receberá informações a cada atualização da transação. Caso você defina este parâmetro, o processamento da transação se torna assíncrono.

async

boolean

Utilize false caso queira manter o processamento síncrono de uma transação. Ou seja, a resposta da transação é recebida na hora.

installments

string

Número de parcelas da transação, sendo mínimo: 1 e Máximo: 12. OBS: Se o pagamento for boleto, o padrão é 1

boleto_expiration_date

string

Prazo limite para pagamento do boleto. Deve ser passado no formato yyyy-MM-dd. Preencha com um dia mais em relação à data de vencimento desejado. Default: data atual + 7 dias

soft_descriptor

string

Descrição que aparecerá na fatura depois do nome de sua empresa. Máximo de 13 caracteres, sendo alfanuméricos e espaços.

capture

string

Após a autorização de uma transação, você pode escolher se irá capturar ou adiar a captura do valor. Caso opte por postergar a captura, atribua o valor false.

boleto_instructions

string

Campo instruções do boleto. Máximo de 255 caracteres

split_rules

array of objects

Regras de divisão da transação

liable

charge_processing_fee

percentage

amount

charge_remainder_fee

recipient_id

customer

json

required

Obrigatório com o antifraude habilitado. Define os dados do comprador, como nome, email e telefone

billing

object

required

Obrigatório com o antifraude habilitado. Define os dados de cobrança, como nome e endereço

shipping

object

Define os dados de envio da compra, como nome do recebedor, valor do envio e endereço de recebimento. Deve ser preenchido no caso da venda de bem físico (ver objeto items)

items

object

required

Obrigatório com o antifraude habilitado. Define os dados dos itens vendidos, como nome, preço unitário e quantidade

metadata

json

Você pode passar dados adicionais na criação da transação para facilitar uma futura análise de dados tanto em nossa dashboard, quanto por seus sistemas. Ex: metadata[ idProduto ]=13933139

session

string

Valor único que identifica a sessão do usuário acessando o site. Máximo de 100 caracteres

local_time

string

Data e hora do dispositivo que está efetuando a transação. Deve ser enviado no seguinte formato: yyyy-MM-dd'T'HH:mm:ss'Z. Por exemplo: 2017-10-31T14:53:00.000Z. OBS.: este campo é necessário para transações de mundo físico (com método de captura EMV e Magstripe)

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

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.

Boletos

Para transações por boleto, não aplicamos multa ou repasse de juros. Caso queira qualquer alteração na cobrança, é necessário criar uma nova transação.

Antifraude

Dados do cliente e de compra (customer, billing, shipping 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"
}

curl -X POST 'https://api.pagar.me/1/transactions' -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY",
    "amount": 21000,
    "card_number": "4111111111111111",
    "card_cvv": "123",
    "card_expiration_date": "0922",
    "card_holder_name": "Morpheus Fishburne",
    "customer": {
      "external_id": "#3311",
      "name": "Morpheus Fishburne",
      "type": "individual",
      "country": "br",
      "email": "mopheus@nabucodonozor.com",
      "documents": [
        {
          "type": "cpf",
          "number": "00000000000"
        }
      ],
      "phone_numbers": ["+5511999998888", "+5511888889999"],
      "birthday": "1965-01-01"
    },
    "billing": {
      "name": "Trinity Moss",
      "address": {
        "country": "br",
        "state": "sp",
        "city": "Cotia",
        "neighborhood": "Rio Cotia",
        "street": "Rua Matrix",
        "street_number": "9999",
        "zipcode": "06714360"
      }
    },
    "shipping": {
      "name": "Neo Reeves",
      "fee": 1000,
      "delivery_date": "2000-12-21",
      "expedited": true,
      "address": {
        "country": "br",
        "state": "sp",
        "city": "Cotia",
        "neighborhood": "Rio Cotia",
        "street": "Rua Matrix",
        "street_number": "9999",
        "zipcode": "06714360"
      }
    },
    "items": [
      {
        "id": "r123",
        "title": "Red pill",
        "unit_price": 10000,
        "quantity": 1,
        "tangible": true
      },
      {
        "id": "b123",
        "title": "Blue pill",
        "unit_price": 10000,
        "quantity": 1,
        "tangible": true
      }
    ]
}'

const pagarme = require('pagarme')

pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.transactions.create({
    "amount": 21000,
    "card_number": "4111111111111111",
    "card_cvv": "123",
    "card_expiration_date": "0922",
    "card_holder_name": "Morpheus Fishburne",
    "customer": {
      "external_id": "#3311",
      "name": "Morpheus Fishburne",
      "type": "individual",
      "country": "br",
      "email": "mopheus@nabucodonozor.com",
      "documents": [
        {
          "type": "cpf",
          "number": "00000000000"
        }
      ],
      "phone_numbers": ["+5511999998888", "+5511888889999"],
      "birthday": "1965-01-01"
    },
    "billing": {
      "name": "Trinity Moss",
      "address": {
        "country": "br",
        "state": "sp",
        "city": "Cotia",
        "neighborhood": "Rio Cotia",
        "street": "Rua Matrix",
        "street_number": "9999",
        "zipcode": "06714360"
      }
    },
    "shipping": {
      "name": "Neo Reeves",
      "fee": 1000,
      "delivery_date": "2000-12-21",
      "expedited": true,
      "address": {
        "country": "br",
        "state": "sp",
        "city": "Cotia",
        "neighborhood": "Rio Cotia",
        "street": "Rua Matrix",
        "street_number": "9999",
        "zipcode": "06714360"
      }
    },
    "items": [
      {
        "id": "r123",
        "title": "Red pill",
        "unit_price": 10000,
        "quantity": 1,
        "tangible": true
      },
      {
        "id": "b123",
        "title": "Blue pill",
        "unit_price": 10000,
        "quantity": 1,
        "tangible": true
      }
    ]
  }))
  .then(transaction => console.log(transaction))

import pagarme

pagarme.authentication_key('SUA_API_KEY')

params = {
		"amount": "21000",
    "card_number": "4111111111111111",
    "card_cvv": "123",
    "card_expiration_date": "0922",
    "card_holder_name": "Morpheus Fishburne",
    "customer": {
      "external_id": "#3311",
      "name": "Morpheus Fishburne",
      "type": "individual",
      "country": "br",
      "email": "mopheus@nabucodonozor.com",
      "documents": [
        {
          "type": "cpf",
          "number": "00000000000"
        }
      ],
      "phone_numbers": ["+5511999998888", "+5511888889999"],
      "birthday": "1965-01-01"
    },
    "billing": {
      "name": "Trinity Moss",
      "address": {
        "country": "br",
        "state": "sp",
        "city": "Cotia",
        "neighborhood": "Rio Cotia",
        "street": "Rua Matrix",
        "street_number": "9999",
        "zipcode": "06714360"
      }
    },
    "shipping": {
      "name": "Neo Reeves",
      "fee": "1000",
      "delivery_date": "2000-12-21",
      "expedited": True,
      "address": {
        "country": "br",
        "state": "sp",
        "city": "Cotia",
        "neighborhood": "Rio Cotia",
        "street": "Rua Matrix",
        "street_number": "9999",
        "zipcode": "06714360"
      }
    },
    "items": [
      {
        "id": "r123",
        "title": "Red pill",
        "unit_price": "10000",
        "quantity": "1",
        "tangible": True
      },
      {
        "id": "b123",
        "title": "Blue pill",
        "unit_price": "10000",
        "quantity": "1",
        "tangible": True
      }
    ]
}

trx = pagarme.transaction.create(params)

print(trx)

using System;
using PagarMe;

PagarMeService.DefaultApiKey = "API_KEY";
PagarMeService.DefaultEncryptionKey = "ENCRYPTION_KEY";

Transaction transaction = new Transaction();

transaction.Amount = 2100;
transaction.Card = new Card
{
  Id = "card_cj95mc28g0038cy6ewbwtwwx2"
};

transaction.Customer = new Customer
{
  ExternalId = "#3311",
  Name = "Rick",
  Type = CustomerType.Individual,
  Country = "br",
  Email = "rick@morty.com",
  Documents = new[]
  {
    new Document{
      Type = DocumentType.Cpf,
      Number = "11111111111"
    },
    new Document{
      Type = DocumentType.Cnpj,
      Number = "83134932000154"
    }
  },
  PhoneNumbers = new string[]
  {
    "+5511982738291",
    "+5511829378291"
  },
  Birthday = new DateTime(1991, 12, 12).ToString("yyyy-MM-dd")
};

transaction.Billing = new Billing 
{
  Name = "Morty",
  Address = new Address()
  {
    Country = "br",
    State = "sp",
    City = "Cotia",
    Neighborhood = "Rio Cotia",
    Street = "Rua Matrix",
    StreetNumber = "213",
    Zipcode = "04250000"
  }
};

var Today = DateTime.Now;

transaction.Shipping = new Shipping 
{ 
  Name = "Rick",
  Fee = 100,
  DeliveryDate = Today.AddDays(4).ToString("yyyy-MM-dd"),
  Expedited = false,
  Address = new Address()
  {
    Country = "br",
    State = "sp",
    City = "Cotia",
    Neighborhood = "Rio Cotia",
    Street = "Rua Matrix",
    StreetNumber = "213",
    Zipcode = "04250000"
  }
};

transaction.Item = new[]
{
  new Item()
  {
    Id = "1",
    Title = "Little Car",
    Quantity = 1,
    Tangible = true,
    UnitPrice = 1000
  },
  new Item()
  {
    Id = "2",
    Title = "Baby Crib",
    Quantity = 1,
    Tangible = true,
    UnitPrice = 1000
  }
};

transaction.Save();

import java.util.ArrayList;
import java.util.Collection;
import me.pagar.model.Address;
import me.pagar.model.Billing;
import me.pagar.model.Customer;
import me.pagar.model.Document;
import me.pagar.model.Item;
import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Shipping;
import me.pagar.model.Transaction;

Transaction transaction = new Transaction();
Customer customer = new Customer();
customer.setType(Customer.Type.INDIVIDUAL);
customer.setExternalId("1001");
customer.setName("Phineas Flynn");
customer.setBirthday("1999-07-09");
customer.setEmail("phineas@threestatearea.com");
customer.setCountry("br");

Collection<Document> documents = new ArrayList();
Document document = new Document();
document.setType(Document.Type.CPF);
document.setNumber("77551442758");
documents.add(document);
customer.setDocuments(documents);

Collection<String> phones = new ArrayList();
phones.add("+5511982657575");
customer.setPhoneNumbers(phones);

Billing billing = new Billing(); 
billing.setName("Phineas Flynn");
Address address  = new Address(); 
address.setCity("Santo Andre");
address.setCountry("br");
address.setState("sp");
address.setNeighborhood("Parque Miami");
address.setStreet("Rua Rio Jari");
address.setZipcode("09133180");
address.setStreetNumber("7");
billing.setAddress(address);

Shipping shipping = new Shipping();
shipping.setAddress(address);
shipping.setName("Phineas Flynn");
shipping.setFee(3200);

Collection<Item> items = new ArrayList();
Item item = new Item(); 
item.setId("OX890");
item.setQuantity(12);
item.setTangible(Boolean.TRUE);
item.setTitle("Rockets");
item.setUnitPrice(120);

transaction.setShipping(shipping);
transaction.setBilling(billing);
transaction.setItems(items);
transaction.setPaymentMethod(Transaction.PaymentMethod.CREDIT_CARD);
transaction.setAmount(4640);
transaction.setCardHolderName("Phineas Flynn");
transaction.setCardNumber("4242424242424242");
transaction.setCardCvv("909");
transaction.setCardExpirationDate("1119"); 
transaction.setCustomer(customer);
transaction.save();

<?php
  require __DIR__.'/pagarme-php/Pagarme.php';

  $transaction = new PagarMe_Transaction(array(
    "amount" => 1000,
    "card_number" => "4111111111111111",
    "card_cvv" => "123",
    "card_expiration_month" => "09",
    "card_expiration_year" => "22",
    "card_holder_name" => "John Doe",
    "payment_method" => "credit_card",
    "customer" => array(
      "external_id" => "1",
      "name" => "John Doe",
      "type" => "individual",
      "country" => "br",
      "documents" => array(
        array(
          "type" => "cpf",
          "number" => "00000000000"
        )
      ),
      "phone_numbers" => array( "+551199999999" ),
      "email" => "aardvark.silva@pagar.me"
    ),
    "billing" => array(
      "name" => "John Doe",
      "address" => array(
        "country" => "br",
        "street" => "Avenida Brigadeiro Faria Lima",
        "street_number" => "1811",
        "state" => "sp",
        "city" => "Sao Paulo",
        "neighborhood" => "Jardim Paulistano",
        "zipcode" => "01451001"
      )
    ),
    "items" => array(
      array(
        "id" => "r123",
        "title" => "Red pill",
        "unit_price" => 10000,
        "quantity" => 1,
        "tangible" => true
      ),
      array(
        "id" => "b123",
        "title" => "Blue pill",
        "unit_price" => 10000,
        "quantity" => 1,
        "tangible" => true
      )
    )
  ));
?>

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

{
    "object": "transaction",
    "status": "paid",
    "refse_reason": null,
    "status_reason": "acquirer",
    "acquirer_response_code": "0000",
    "acquirer_name": "pagarme",
    "acquirer_id": "5969170917bce0470c8bf099",
    "authorization_code": "65208",
    "soft_descriptor": null,
    "tid": 1830855,
    "nsu": 1830855,
    "date_created": "2017-08-14T20:35:46.046Z",
    "date_updated": "2017-08-14T20:35:46.455Z",
    "amount": 10000,
    "authorized_amount": 10000,
    "paid_amount": 10000,
    "refunded_amount": 0,
    "installments": 1,
    "id": 1830855,
    "cost": 50,
    "card_holder_name": "Morpheus Fishburne",
    "card_last_digits": "1111",
    "card_first_digits": "411111",
    "card_brand": "visa",
    "card_pin_mode": null,
    "postback_url": null,
    "payment_method": "credit_card",
    "capture_method": "ecommerce",
    "antifraud_score": null,
    "boleto_url": null,
    "boleto_barcode": null,
    "boleto_expiration_date": null,
    "referer": "api_key",
    "ip": "10.2.11.17",
    "subscription_id": null,
    "phone": null,
    "address": null,
    "customer": {
        "object": "customer",
        "id": 233238,
        "external_id": "#3311",
        "type": "individual",
        "country": "br",
        "document_number": null,
        "document_type": "cpf",
        "name": "Morpheus Fishburne",
        "email": "mopheus@nabucodonozor.com",
        "phone_numbers": [
            "+5511999998888",
            "+5511888889999"
        ],
        "born_at": null,
        "birthday": "1965-01-01",
        "gender": null,
        "date_created": "2017-08-14T20:35:45.963Z",
        "documents": [
            {
                "object": "document",
                "id": "doc_cj6cmcm2l01z5696dyamemdnf",
                "type": "cpf",
                "number": "00000000000"
            }
        ]
    },
    "billing": {
        "address": {
            "object": "address",
            "street": "Rua Matrix",
            "complementary": null,
            "street_number": "9999",
            "neighborhood": "Rio Cotia",
            "city": "Cotia",
            "state": "sp",
            "zipcode": "06714360",
            "country": "br",
            "id": 145818
        },
        "object": "billing",
        "id": 30,
        "name": "Trinity Moss"
    },
    "shipping": {
        "address": {
            "object": "address",
            "street": "Rua Matrix",
            "complementary": null,
            "street_number": "9999",
            "neighborhood": "Rio Cotia",
            "city": "Cotia",
            "state": "sp",
            "zipcode": "06714360",
            "country": "br",
            "id": 145819
        },
        "object": "shipping",
        "id": 25,
        "name": "Neo Reeves",
        "fee": 1000,
        "delivery_date": "2000-12-21",
        "expedited": true
    },
    "items": [
        {
            "object": "item",
            "id": "r123",
            "title": "Red pill",
            "unit_price": 10000,
            "quantity": 1,
            "category": null,
            "tangible": true,
            "venue": null,
            "date": null
        },
        {
            "object": "item",
            "id": "b123",
            "title": "Blue pill",
            "unit_price": 10000,
            "quantity": 1,
            "category": null,
            "tangible": true,
            "venue": null,
            "date": null
        }
    ],
    "card": {
        "object": "card",
        "id": "card_cj6cmcm4301z6696dt3wypskk",
        "date_created": "2017-08-14T20:35:46.036Z",
        "date_updated": "2017-08-14T20:35:46.524Z",
        "brand": "visa",
        "holder_name": "Morpheus Fishburne",
        "first_digits": "411111",
        "last_digits": "1111",
        "country": "UNITED STATES",
        "fingerprint": "3ace8040fba3f5c3a0690ea7964ea87d97123437",
        "valid": true,
        "expiration_date": "0922"
    },
    "split_rules": null,
    "metadata": {},
    "antifraud_metadata": {},
    "reference_key": null
}

Suggest Edits

Objeto transaction (transação)

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

Verifique na sua Dashboard a versão da API que você está usando. Você deve usar a documentação correspondente. Para saber mais, veja: Versionamento.

Ao criar ou atualizar uma transação, este é o objeto que você recebe como resposta em cada etapa do processo de efetivação da transação.

Propriedade

Descrição

object
String

Nome do tipo do objeto criado/modificado.
Valor retornado: transaction

status
String

Representa o estado da transação. A cada atualização no processamento da transação, esta propriedade é alterada e, caso você esteja usando uma postback_url, os seus servidores são notificados desses updates.
Valores possíveis: processing, authorized, paid, refunded, waiting_payment, pending_refund, refused .

refuse_reason
String

Motivo pelo qual a transação foi recusada.
Valores possíveis: acquirer, antifraud, internal_error, no_acquirer, acquirer_timeout

status_reason
String

Agente responsável pela validação ou anulação da transação.
Valores possíveis: acquirer, antifraud, internal_error, no_acquirer, acquirer_timeout

acquirer_name
String

Adquirente responsável pelo processamento da transação.
Valores possíveis: development (em ambiente de testes), pagarme (adquirente Pagar.me), stone, cielo, rede.

acquirer_id
String

ID da adquirente responsável pelo processamento da transação.

acquirer_response_code
String

Mensagem de resposta da adquirente referente ao status da transação.

authorization_code
String

Código de autorização retornado pela bandeira.

soft_descriptor
String

Texto que irá aparecer na fatura do cliente depois do nome da loja.
OBS: Limite de 13 caracteres.

tid
String

Código que identifica a transação na adquirente.

nsu
String

Código que identifica a transação na adquirente.

date_created
String

Data de criação da transação no formato ISODate

date_updated
String

Data de atualização da transação no formato ISODate

amount
Integer**

Valor, em centavos, da transação.
Exemplo: R$100,00 = 10000

authorized_amount
Integer

Valor em centavos autorizado na transação, sempre menor ou igual a amount.

paid_amount
Integer

Valor em centavos capturado na transação, sempre menor ou igual a authorized_amount.

refunded_amount
Integer

Valor em centavos estornado até o momento na transação, sempre menor ou igual a paidamount

installments
Integer

Número de parcelas a serem cobradas.
OBS: Mínimo 1 e Máximo 12.

id
Integer

Número identificador da transação

cost
Integer

Custo da transação para o lojista, envolvendo processamento e antifraude.

card_holder_name
String

Nome do portador do cartão.

card_last_digits
String

Últimos 4 dígitos do cartão.

card_first_digits
String

Primeiros 5 dígitos do cartão

card_brand
String

Bandeira do cartão.

card_pin_mode
String

Usado em transações EMV, define se a validação do cartão aconteceu online(com banco emissor), ou offline( através do chip).

postback_url
String

URL (endpoint) de seu sistema que recebe notificações a cada mudança no status da transação.

payment_method
String

Método de pagamento, com os possíveis valores: credit_card e boleto.

capture_method
String

Define qual foi a forma de captura dos dados de pagamento. Valores possíveis: magstripe, emv, ecommerce.

antifraud_score
String

Define qual foi a nota de antifraude atribuída a transação. Lembrando que por padrão, transações com score >= 95 são recusadas.

boleto_url
String

URL do boleto para impressão

boleto_barcode
String

Código de barras do boleto gerado na transação

boleto_expiration_date
String

Data de expiração do boleto (em ISODate)

referer
String

Mostra se a transação foi criada utilizando a API Key ou Encryption Key

ip
String

IP de origem que criou a transação, podendo ser diretamente de seu cliente, caso a requisição venha diretamente do client-side, ou de seus servidores, caso tudo esteja centralizando em sua aplicação no server-side.

subscription_id
Integer

Caso essa transação tenha sido originada na cobrança de uma assinatura, o id desta será o valor dessa propriedade.

customer
Object

Dados do cliente. Obrigatório com o antifraude habilitado. O objetocustomer é descrito aqui

billing
Object

Dados de cobrança da transação. Obrigatório com o antifraude habilitado. O objetobilling é descrito aqui

shipping
Object

Dados de envio do que foi comprado. Deve ser preenchido no caso de venda de bem físico. O objetoshipping é descrito aqui

items
Object

Dados sobre os produtos comprados. Obrigatório com o antifraude habilitado. O objetoitems é descrito aqui

address
Object

Dados de endereço, presente em shipping e billing. Obrigatório com o antifraude habilitado. O objetoaddress é descrito aqui

documents
Array of objects

Informações de documentos do comprador. Obrigatório com o antifraude habilitado. O objetodocuments é descrito aqui

metadata
Object

Objeto com dados adicionais informados na criação da transação.

split_rules
Object

Objeto com as regras de split definidas para essa transação.

antifraud_metadata
Object

Objeto com dados usados na integração com antifraude.

session
String

Valor único que identifica a sessão do usuário acessando o site

Segue abaixo um exemplo de objeto de resposta.

JSON

{
    "object": "transaction",
    "status": "paid",
    "refuse_reason": null,
    "status_reason": "acquirer",
    "acquirer_response_code": "0000",
    "acquirer_name": "pagarme",
    "acquirer_id": "5969170917bce0470c8bf099",
    "authorization_code": "65208",
    "soft_descriptor": null,
    "tid": 1830855,
    "nsu": 1830855,
    "date_created": "2017-08-14T20:35:46.046Z",
    "date_updated": "2017-08-14T20:35:46.455Z",
    "amount": 10000,
    "authorized_amount": 10000,
    "paid_amount": 10000,
    "refunded_amount": 0,
    "installments": 1,
    "id": 1830855,
    "cost": 50,
    "card_holder_name": "Morpheus Fishburne",
    "card_last_digits": "1111",
    "card_first_digits": "411111",
    "card_brand": "visa",
    "card_pin_mode": null,
    "postback_url": null,
    "payment_method": "credit_card",
    "capture_method": "ecommerce",
    "antifraud_score": null,
    "boleto_url": null,
    "boleto_barcode": null,
    "boleto_expiration_date": null,
    "referer": "api_key",
    "ip": "10.2.11.17",
    "subscription_id": null,
    "phone": null,
    "address": null,
    "customer": {
        "object": "customer",
        "id": 233238,
        "external_id": "#3311",
        "type": "individual",
        "country": "br",
        "document_number": null,
        "document_type": "cpf",
        "name": "Morpheus Fishburne",
        "email": "mopheus@nabucodonozor.com",
        "phone_numbers": [
            "+5511999998888",
            "+5511888889999"
        ],
        "born_at": null,
        "birthday": "1965-01-01",
        "gender": null,
        "date_created": "2017-08-14T20:35:45.963Z",
        "documents": [
            {
                "object": "document",
                "id": "doc_cj6cmcm2l01z5696dyamemdnf",
                "type": "cpf",
                "number": "00000000000"
            }
        ]
    },
    "billing": {
        "address": {
            "object": "address",
            "street": "Rua Matrix",
            "complementary": null,
            "street_number": "9999",
            "neighborhood": "Rio Cotia",
            "city": "Cotia",
            "state": "sp",
            "zipcode": "06714360",
            "country": "br",
            "id": 145818
        },
        "object": "billing",
        "id": 30,
        "name": "Trinity Moss"
    },
    "shipping": {
        "address": {
            "object": "address",
            "street": "Rua Matrix",
            "complementary": null,
            "street_number": "9999",
            "neighborhood": "Rio Cotia",
            "city": "Cotia",
            "state": "sp",
            "zipcode": "06714360",
            "country": "br",
            "id": 145819
        },
        "object": "shipping",
        "id": 25,
        "name": "Neo Reeves",
        "fee": 1000,
        "delivery_date": "2000-12-21",
        "expedited": true
    },
    "items": [
        {
            "object": "item",
            "id": "r123",
            "title": "Red pill",
            "unit_price": 10000,
            "quantity": 1,
            "category": null,
            "tangible": true,
            "venue": null,
            "date": null
        },
        {
            "object": "item",
            "id": "b123",
            "title": "Blue pill",
            "unit_price": 10000,
            "quantity": 1,
            "category": null,
            "tangible": true,
            "venue": null,
            "date": null
        }
    ],
    "card": {
        "object": "card",
        "id": "card_cj6cmcm4301z6696dt3wypskk",
        "date_created": "2017-08-14T20:35:46.036Z",
        "date_updated": "2017-08-14T20:35:46.524Z",
        "brand": "visa",
        "holder_name": "Morpheus Fishburne",
        "first_digits": "411111",
        "last_digits": "1111",
        "country": "UNITED STATES",
        "fingerprint": "3ace8040fba3f5c3a0690ea7964ea87d97123437",
        "valid": true,
        "expiration_date": "0922"
    },
    "split_rules": null,
    "metadata": {},
    "antifraud_metadata": {},
    "reference_key": null
}

Suggest Edits

Objeto billing (dados de cobrança)

Suggest Edits

Objeto shipping (dados de envio)

Os dados de envio devem ser fornecidos dentro do objeto shipping. O campo shipping deve ser preenchido para transações de cartão de crédito de companhias com antifraude habilitado em que o item vendido é um bem físico (veja o objeto items). Abaixo segue a descrição deste objeto.

Propriedade

Descrição

name
String

Obrigatório. Nome da entidade de cobrança

fee
Number

Obrigatório. Taxa de envio cobrada do comprador. Por exemplo, se a taxa de envio é de dez reais e três centavos (R$10,03), o valor deve ser fornecido como ‘1003’

delivery_date
String

Data de entrega. Estimativa fornecida no formato AAAA-MM-DD

expedited
Boolean

Entrega expressa. Se for entrega expressa, deve conter ‘true’ (sim). Caso contrário, deve conter ‘false’ (não)

address
Object

Obrigatório. Dados do endereço de envio. Objeto descrito aqui.

Suggest Edits

Objeto items (itens)

Os dados sobre os produtos vendidos devem ser fornecidos dentro do objeto items. O campo items é obrigatório para todas as transações de cartão de crédito de companhias com antifraude habilitado. Abaixo segue a descrição do objeto items.

Propriedade

Descrição

id
String

Obrigatório. SKU (unidade de manutenção de estoque) ou número de identificação na loja

title
String

Obrigatório. Nome do item vendido.

unit_price
Number

Obrigatório. Preço por unidade. Por exemplo, se o preço de cada item é vinte reais e seis centavos (R$20,06), o valor deve ser fornecido como ‘2006’

quantity
Number

Obrigatório. Número de unidades vendidas do produto

tangible
Boolean

Obrigatório. Caracteriza o produto como bem físico ou não. Por bem físico, entende-se produtos que devem ser enviados fisicamente ao comprador, como calçados, eletrônicos e brinquedos.
Se for um bem físico deve conter true (sim). Caso contrário, deve conter false (não)

category
String

venue
String

Local (se evento).

date
String

Data (se evento). Estimativa fornecida no formato AAAA-MM-DD

Suggest Edits

Objeto address (endereço)

Os dados sobre endereço devem ser fornecidos dentro do objeto address. O campo address é obrigatório para todas as transações de cartão de crédito de companhias com antifraude habilitado. Abaixo segue a descrição deste objeto.

Propriedade

Descrição

street
String

Obrigatório. Rua

street_number
String

Obrigatório. Número

zipcode
String

Obrigatório. CEP. Para endereço brasileiro, deve conter uma numeração de 8 dígitos

country
String

Obrigatório. País. Duas letras minúsculas. Deve seguir o padão ISO 3166-1 alpha-2

state
String

Obrigatório. Estado

city
String

Obrigatório. Cidade

neighborhood
String

Bairro

complementary
String

Complemento

Suggest Edits

Objeto documents (documentos)

Suggest Edits

Status das transações

Ao criar uma transação, a sua aplicação pode receber uma série de status. Entre eles está processing, caso a requisição tenha sido feita de forma assíncrona, ou seja, usando uma postback_url que serve como endereço para futuras notificações de mudança nesta mesma transação. Pode ser também um status definitivo como authorized, paid ou refused, em caso de request síncrona usando async=false. A seguir está a descrição de cada status, e em qual etapa passa a ser utilizado.

Status

Significado

processing

Transação está em processo de autorização.

authorized

Transação foi autorizada. Cliente possui saldo na conta e este valor foi reservado para futura captura, que deve acontecer em até 5 dias para transações criadas com api_key. Caso não seja capturada, a autorização é cancelada automaticamente pelo banco emissor, e o status dela permanece como authorized.

paid

Transação paga. Foi autorizada e capturada com sucesso. Para Boleto, significa que nossa API já identificou o pagamento de seu cliente.

refunded

Transação estornada completamente.

waiting_payment

Transação aguardando pagamento (status válido para Boleto bancário).

pending_refund

Transação do tipo Boleto e que está aguardando confirmação do estorno solicitado.

refused

Transação recusada, não autorizada.

chargedback

Transação sofreu chargeback. Veja mais sobre isso em nossa central de ajuda

Suggest Edits

Capturando uma transação posteriormente

Essa rota é utilizada para capturar uma transação, após aprovada, utilizando o token ou o ID da transação.

posthttps://api.pagar.me/1/transactions/id_ou_token/capture

Path Params

id_ou_token

string

required

Id ou o token da transação a ser capturada

Query Params

amount

int32

required

Valor a ser capturado. Deve ser passado em centavos. Ex: R$ 10.00 = 1000.

split_rules

array of objects

Regras de divisão da transação

liable

charge_processing_fee

percentage

amount

charge_remainder_fee

recipient_id

metadata

json

Metadata de informações adicionais, caso queira incluir, i.e: Id do pedido, nome do produto, etc.

O que é uma captura?

Captura de uma transação

O processo de captura representa a confirmação junto ao banco emissor de uma autorização previamente criada. Significa dizer: "Confirmo a cobrança deste valor na fatura do portador deste cartão", ou seja, o valor de fato será cobrado. Caso não seja executada, o próprio banco emissor cancela a operação de autorização e devolve o saldo reservado ao cartão do portador.

Restrições ao tempo para captura de uma transação

Tempo para captura de uma transação

Para uma transação que tenha sido criada através de uma api_key, sua plataforma tem até 5 dias para solicitar o processo de captura através desta rota. Mas para transações criadas com encryption_key, a sua plataforma tem agora apenas 5 horas para executar a captura. Caso não execute a operação, nossa API faz automaticamente o cancelamento do processo de autorização e sinaliza o status_reason da transação como capture_timeout.

Captura em transações de boleto

Ao chamar a rota /capture para uma transação de boleto, você na verdade está solicitando a criação as informações pertinentes ao boleto, observe:

Captura de boleto

Uma transação de boleto apenas autorizada não gera os dados de boleto: url e código de barras. Apenas após a captura essas informações são criadas.

Captura parcial

Você pode passar o parâmetro amount na rota de /capture de uma transação, mas é importante seguir esta observação:

Valores para captura

Nossa API permite que sua aplicação capture um valor menor ou igual ao que foi autorizado em sua transação, entretanto, isso é válido apenas para transações criadas com sua api_key. Para os casos que uma encryption_key tenha sido usada, o valor de autorização deve ser o mesmo para captura, sendo que ambos devem refletir o valore do seu carrinho de compras.

curl -X POST https://api.pagar.me/1/transactions/id_ou_token/capture -H 'content-type: application/json' -d '{
  "amount": "3100",
  "api_key": "SUA_API_KEY"
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

transaction = PagarMe::Transaction.find_by_id("1627822")

transaction.capture({:amount => 3100})

<?php
    require("pagarme-php/Pagarme.php");

    Pagarme::setApiKey("SUA_API_KEY");

    $transaction = PagarMe_Transaction::findById("1627822");

    $transaction->capture(3100);

PagarMeService.DefaultApiKey = "SUA_API_KEY";

var transaction = PagarMeService.GetDefaultService().Transactions.Find("1627822");

transaction.Capture(3100);

import java.util.HashMap;
import java.util.Map;

import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Transaction;
import me.pagar.model.Transaction.PaymentMethod;

PagarMe.init("SUA_API_KEY");

Transaction tx = new Transaction().find(1627822);

tx.capture(3100);

<?php
	require __DIR__.'/vendor/autoload.php';

	$pagarMe = new \PagarMe\Sdk\PagarMe('SUA_API_KEY');
  $transaction = $pagarMe->transaction()->get("1627822");
	$captureAmount = 3100;
  $pagarMe->transaction()->capture($transaction, $captureAmount);

const pagarme = require('pagarme')

pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.transactions.capture({ id: '1627822' }))

// Using Promise chain:
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => {
    client.transactions.create({
      capture: false,
      amount: 100,
      card_number: '4111111111111111',
      card_holder_name: 'abc',
      card_expiration_date: '1225',
      card_cvv: '123',
    })
      .then(client.transactions.capture)
  })

import pagarme

pagarme.authentication_key("SUA_API_KEY")

transaction = pagarme.transaction.find_by({
    "id": "TRANSACTION_ID"
})

print(pagarme.transaction.capture(
    transaction[0]['id'],
    {"amount": "Valor a ser capturado"}
))

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

{
    "object": "transaction",
    "status": "paid",
    "refuse_reason": null,
    "status_reason": "acquirer",
    "acquirer_response_code": "0000",
    "acquirer_name": "pagarme",
    "acquirer_id": "58a49047916d40fa539ba926",
    "authorization_code": "716244",
    "soft_descriptor": null,
    "tid": 1835859,
    "nsu": 1835859,
    "date_created": "2017-08-15T15:51:56.180Z",
    "date_updated": "2017-08-15T15:54:11.366Z",
    "amount": 10000,
    "authorized_amount": 10000,
    "paid_amount": 1000,
    "refunded_amount": 0,
    "installments": 1,
    "id": 1835859,
    "cost": 50,
    "card_holder_name": "Morpheus Fishburne",
    "card_last_digits": "1111",
    "card_first_digits": "411111",
    "card_brand": "visa",
    "card_pin_mode": null,
    "postback_url": null,
    "payment_method": "credit_card",
    "capture_method": "ecommerce",
    "antifraud_score": null,
    "boleto_url": null,
    "boleto_barcode": null,
    "boleto_expiration_date": null,
    "referer": "api_key",
    "ip": "10.2.11.17",
    "subscription_id": null,
    "phone": null,
    "address": null,
    "customer": {
        "object": "customer",
        "id": 234257,
        "external_id": "#3311",
        "type": "individual",
        "country": "br",
        "document_number": null,
        "document_type": "cpf",
        "name": "Morpheus Fishburne",
        "email": "mopheus@nabucodonozor.com",
        "phone_numbers": [
            "+5511999998888",
            "+5511888889999"
        ],
        "born_at": null,
        "birthday": "1965-01-01",
        "gender": null,
        "date_created": "2017-08-15T15:51:56.025Z",
        "documents": [
            {
                "object": "document",
                "id": "doc_cj6drngcv0lnx6m6dt00twpnv",
                "type": "cpf",
                "number": "00000000000"
            }
        ]
    },
    "billing": {
        "address": {
            "object": "address",
            "street": "Rua Matrix",
            "complementary": null,
            "street_number": "9999",
            "neighborhood": "Rio Cotia",
            "city": "Cotia",
            "state": "sp",
            "zipcode": "06714360",
            "country": "br",
            "id": 146607
        },
        "object": "billing",
        "id": 33,
        "name": "Trinity Moss"
    },
    "shipping": {
        "address": {
            "object": "address",
            "street": "Rua Matrix",
            "complementary": null,
            "street_number": "9999",
            "neighborhood": "Rio Cotia",
            "city": "Cotia",
            "state": "sp",
            "zipcode": "06714360",
            "country": "br",
            "id": 146608
        },
        "object": "shipping",
        "id": 27,
        "name": "Neo Reeves",
        "fee": 3311,
        "delivery_date": "2000-12-21",
        "expedited": true
    },
    "items": [
        {
            "object": "item",
            "id": "1",
            "title": "Red pill",
            "unit_price": 12000,
            "quantity": 1,
            "category": null,
            "tangible": true,
            "venue": null,
            "date": null
        },
        {
            "object": "item",
            "id": "a123",
            "title": "Blue pill",
            "unit_price": 12000,
            "quantity": 1,
            "category": null,
            "tangible": true,
            "venue": null,
            "date": null
        }
    ],
    "card": {
        "object": "card",
        "id": "card_cj6drngg90lny6m6djo0coq4p",
        "date_created": "2017-08-15T15:51:56.169Z",
        "date_updated": "2017-08-15T15:51:56.619Z",
        "brand": "visa",
        "holder_name": "Morpheus Fishburne",
        "first_digits": "411111",
        "last_digits": "1111",
        "country": "UNITED STATES",
        "fingerprint": "3ace8040fba3f5c3a0690ea7964ea87d97123437",
        "valid": true,
        "expiration_date": "0922"
    },
    "split_rules": null,
    "metadata": {},
    "antifraud_metadata": {},
    "reference_key": null
}

Suggest Edits

Estorno de transação

Essa rota é utilizada quando se deseja estornar uma transação realizada por uma cobrança via Cartão de crédito ou Boleto bancário.

Em caso de estorno de uma transação realizada com Cartão de crédito, apenas o ID da transação é necessário para efetivação do estorno.

Caso a compra tenha sido feita por boleto bancário, você precisa informar os dados da conta bancária que irá receber o valor estornado ou o ID desta conta, que pode ser gerado através da rota /bank_accounts.

posthttps://api.pagar.me/1/transactions/transaction_id/refund

Path Params

transaction_id

string

required

ID da transação

Body Params

bank_account_id

string

required

ID da conta bancária. Necessário apenas para estorno de boleto. É possível passar todos os dados da conta também.

bank_code

string

required

Dígitos que identificam cada banco. Confira a lista dos bancos aqui: http://www.febraban.org.br/arquivo/bancos/sitebancos2-0.asp

agencia

string

required

Número da agência bancária

agencia_dv

string

required

Dígito verificador da agência. Obrigatório caso o banco o utilize

conta

string

required

Número da conta

conta_dv

string

required

Dígito verificador da conta. Obrigatório caso o banco o utilize.

document_number

string

required

CPF ou CNPJ do favorecido

legal_name

string

required

Nome/razão social do favorecido, Até 30 caracteres

async

boolean

Define se a operação deve ser feita de maneira assíncrona ou não. Caso true(default), a reposta de sua request será enviada via post para sua postback_url cadastrada na respectiva transação. Caso false, no response será enviado o status final de refunded.

type

string

Tipo da conta bancária. Valores possíveis: conta_corrente, conta_poupanca, conta_corrente_conjunta, conta_poupanca_conjunta

metadata

json

Você pode passar dados adicionais no estorno da transação para facilitar uma futura análise de dados por seus sistemas.

curl -X POST https://api.pagar.me/1/transactions/id_ou_token/refund -H 'content-type: application/json' 
-d '{
  "api_key": "SUA_API_KEY"
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

transaction = PagarMe::Transaction.find_by_id("1627830")

transaction.refund

<?php
    require("pagarme-php/Pagarme.php");
		
		PagarMe::setApiKey("SUA API KEY");

 		try{
      
    	$transaction = PagarMe_Transaction::findById("1627830");
    	
      $transaction->refund();
    
 		} catch (Exception $ex) {
      
  			echo $ex->getMessage();
      
 		}

PagarMeService.DefaultApiKey = "SUA_API_KEY";

var transaction = PagarMeService.GetDefaultService().Transactions.Find("1627830");

transaction.Refund();

import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Transaction;
import me.pagar.model.Transaction.PaymentMethod;

PagarMe.init("SUA_API_KEY");

Transaction tx = new Transaction().find(1627830);

tx.refund(100000);

<?php
	require __DIR__.'/vendor/autoload.php';

	$pagarMe = new \PagarMe\Sdk\PagarMe('SUA_API_KEY');
  $transaction = $pagarMe->transaction()->get("1627830");
  $transaction = $pagarMe->transaction()->creditCardRefund(
    $transaction
  );

const pagarme = require('pagarme')

pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.transactions.refund({
    id: 1627830
  }))

import pagarme

pagarme.authentication_key("SUA_API_KEY")

transaction = pagarme.transaction.find_by({
    "id": "TRANSACTION_ID"
})

print(pagarme.transaction.refund(
    transaction[0]['id'],
    {"amount": "Valor a ser estornado"}
))

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

{
    "object": "transaction",
    "status": "refunded",
    "refuse_reason": null,
    "status_reason": "acquirer",
    "acquirer_response_code": "0000",
    "acquirer_name": "pagarme",
    "acquirer_id": "58a49047916d40fa539ba926",
    "authorization_code": "716244",
    "soft_descriptor": null,
    "tid": 1835859,
    "nsu": 1835859,
    "date_created": "2017-08-15T15:51:56.180Z",
    "date_updated": "2017-08-15T15:57:32.266Z",
    "amount": 10000,
    "authorized_amount": 10000,
    "paid_amount": 1000,
    "refunded_amount": 1000,
    "installments": 1,
    "id": 1835859,
    "cost": 0,
    "card_holder_name": "Morpheus Fishburne",
    "card_last_digits": "1111",
    "card_first_digits": "411111",
    "card_brand": "visa",
    "card_pin_mode": null,
    "postback_url": null,
    "payment_method": "credit_card",
    "capture_method": "ecommerce",
    "antifraud_score": null,
    "boleto_url": null,
    "boleto_barcode": null,
    "boleto_expiration_date": null,
    "referer": "api_key",
    "ip": "10.2.11.17",
    "subscription_id": null,
    "phone": null,
    "address": null,
    "customer": {
        "object": "customer",
        "id": 234257,
        "external_id": "#3311",
        "type": "individual",
        "country": "br",
        "document_number": null,
        "document_type": "cpf",
        "name": "Morpheus Fishburne",
        "email": "mopheus@nabucodonozor.com",
        "phone_numbers": [
            "+5511999998888",
            "+5511888889999"
        ],
        "born_at": null,
        "birthday": "1965-01-01",
        "gender": null,
        "date_created": "2017-08-15T15:51:56.025Z",
        "documents": [
            {
                "object": "document",
                "id": "doc_cj6drngcv0lnx6m6dt00twpnv",
                "type": "cpf",
                "number": "00000000000"
            }
        ]
    },
    "billing": {
        "address": {
            "object": "address",
            "street": "Rua Matrix",
            "complementary": null,
            "street_number": "9999",
            "neighborhood": "Rio Cotia",
            "city": "Cotia",
            "state": "sp",
            "zipcode": "06714360",
            "country": "br",
            "id": 146607
        },
        "object": "billing",
        "id": 33,
        "name": "Trinity Moss"
    },
    "shipping": {
        "address": {
            "object": "address",
            "street": "Rua Matrix",
            "complementary": null,
            "street_number": "9999",
            "neighborhood": "Rio Cotia",
            "city": "Cotia",
            "state": "sp",
            "zipcode": "06714360",
            "country": "br",
            "id": 146608
        },
        "object": "shipping",
        "id": 27,
        "name": "Neo Reeves",
        "fee": 3311,
        "delivery_date": "2000-12-21",
        "expedited": true
    },
    "items": [
        {
            "object": "item",
            "id": "1",
            "title": "Red pill",
            "unit_price": 12000,
            "quantity": 1,
            "category": null,
            "tangible": true,
            "venue": null,
            "date": null
        },
        {
            "object": "item",
            "id": "a123",
            "title": "Blue pill",
            "unit_price": 12000,
            "quantity": 1,
            "category": null,
            "tangible": true,
            "venue": null,
            "date": null
        }
    ],
    "card": {
        "object": "card",
        "id": "card_cj6drngg90lny6m6djo0coq4p",
        "date_created": "2017-08-15T15:51:56.169Z",
        "date_updated": "2017-08-15T15:51:56.619Z",
        "brand": "visa",
        "holder_name": "Morpheus Fishburne",
        "first_digits": "411111",
        "last_digits": "1111",
        "country": "UNITED STATES",
        "fingerprint": "3ace8040fba3f5c3a0690ea7964ea87d97123437",
        "valid": true,
        "expiration_date": "0922"
    },
    "split_rules": null,
    "metadata": {},
    "antifraud_metadata": {},
    "reference_key": null
}

Suggest Edits

Estorno Parcial de uma transação

O estorno parcial obedece as mesmas regras de um estorno total, e usa o parâmetro amount como referência para o valor a ser estornado. É bom observar que o status da transação vai permanecer paid até que o valor total da transação tenha sido estornado.

Caso a compra tenha sido feita por Boleto bancário, você precisa informar os dados da conta bancária que irá receber o valor estornado ou mesmo o id desta conta, que pode ser gerado através da rota /bank_accounts.

posthttps://api.pagar.me/1/transactions/transaction_id/refund

Path Params

transaction_id

string

required

ID da transação

Body Params

amount

string

required

Valor desejado para o estorno da transação. Deve ser passado em centavos. Ex: R$ 10.00 = 1000.

bank_account_id

string

required

ID da conta bancária. Necessário apenas para estorno de boleto.

bank_account

object

Objeto bank_account que contém os dados da conta bancária para onde o estorno será feito.

bank_account.bank_code

string

required

Código do banco da conta

bank_account.agencia

string

required

Agencia do banco da conta

bank_account.agencia_dv

string

Apenas números, deve conter somente 1 dígito

bank_account.conta

string

required

Número da conta

bank_account.type

string

Tipo da conta. Pode ser: conta_corrente, conta_poupanca, conta_corrente_conjunta, conta_poupanca_conjunta

bank_account.conta_dv

string

required

Dígito verificador da conta

bank_account.document_number

string

required

CPF/CNPJ atrelado à conta

bank_account.legal_name

string

required

Nome/Razão social do dono da conta

metadata

json

Você pode passar dados adicionais no estorno da transação para facilitar uma futura análise de dados por seus sistemas.

curl -X POST 'https://api.pagar.me/1/transactions/:id/refund' -H 'content-type: application/json' -d '{
    "amount": "6153",
    "api_key": "SUA_API_KEY"
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

transaction = PagarMe::Transaction.find_by_id("1627835")

transaction.refund(amount: 20000)

<?php
    require("pagarme-php/Pagarme.php");

    Pagarme::setApiKey("SUA_API_KEY");

    $t = PagarMe_Transaction::findById("1627835");

    $params = array("amount" => 20000);

    $t->refund($params);

?>

PagarMeService.DefaultApiKey = "SUA_API_KEY";

var transaction = PagarMeService.GetDefaultService().Transactions.Find("1627835");

transaction.Refund(20000);

import java.util.HashMap;
import java.util.Map;

import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Transaction;
import me.pagar.model.Transaction.PaymentMethod;

PagarMe.init("SUA_API_KEY");

Transaction tx = new Transaction().find(1627835);

tx.refund(20000);

<?php
	require __DIR__.'/vendor/autoload.php';

	$pagarMe = new \PagarMe\Sdk\PagarMe('SUA_API_KEY');
  $transaction = $pagarMe->transaction()->get("1627835");
	$amountRefunded = 20000;
  $transaction = $pagarMe->transaction()->creditCardRefund(
    $transaction,
    $amountRefunded
  );

const pagarme = require('pagarme')
  
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.transactions.find({ id: '1627835' }))
	.then(transaction => client.transactions.refund({
	    	id: transaction.id,
      	amount: 20000
      })
  )

import pagarme

pagarme.authentication_key("SUA_API_KEY")

transaction = pagarme.transaction.find_by({
    "id": "TRANSACTION_ID"
})

print(pagarme.transaction.refund(
    transaction[0]['id'],
    {"amount": "Valor a ser estornado"}
))

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

{
    "object": "transaction",
    "status": "authorized",
    "refuse_reason": null,
    "status_reason": "acquirer",
    "acquirer_response_code": "0000",
    "acquirer_name": "pagarme",
    "acquirer_id": "58a49047916d40fa539ba926",
    "authorization_code": "688274",
    "soft_descriptor": null,
    "tid": 1835912,
    "nsu": 1835912,
    "date_created": "2017-08-15T15:58:31.733Z",
    "date_updated": "2017-08-15T15:58:53.177Z",
    "amount": 10000,
    "authorized_amount": 10000,
    "paid_amount": 0,
    "refunded_amount": 1200,
    "installments": 1,
    "id": 1835912,
    "cost": 0,
    "card_holder_name": "Morpheus Fishburne",
    "card_last_digits": "1111",
    "card_first_digits": "411111",
    "card_brand": "visa",
    "card_pin_mode": null,
    "postback_url": null,
    "payment_method": "credit_card",
    "capture_method": "ecommerce",
    "antifraud_score": null,
    "boleto_url": null,
    "boleto_barcode": null,
    "boleto_expiration_date": null,
    "referer": "api_key",
    "ip": "10.2.14.195",
    "subscription_id": null,
    "phone": null,
    "address": null,
    "customer": {
        "object": "customer",
        "id": 234265,
        "external_id": "#3311",
        "type": "individual",
        "country": "br",
        "document_number": null,
        "document_type": "cpf",
        "name": "Morpheus Fishburne",
        "email": "mopheus@nabucodonozor.com",
        "phone_numbers": [
            "+5511999998888",
            "+5511888889999"
        ],
        "born_at": null,
        "birthday": "1965-01-01",
        "gender": null,
        "date_created": "2017-08-15T15:58:31.636Z",
        "documents": [
            {
                "object": "document",
                "id": "doc_cj6drvxlw0lqn696dtbbwri6y",
                "type": "cpf",
                "number": "00000000000"
            }
        ]
    },
    "billing": {
        "address": {
            "object": "address",
            "street": "Rua Matrix",
            "complementary": null,
            "street_number": "9999",
            "neighborhood": "Rio Cotia",
            "city": "Cotia",
            "state": "sp",
            "zipcode": "06714360",
            "country": "br",
            "id": 146609
        },
        "object": "billing",
        "id": 34,
        "name": "Trinity Moss"
    },
    "shipping": {
        "address": {
            "object": "address",
            "street": "Rua Matrix",
            "complementary": null,
            "street_number": "9999",
            "neighborhood": "Rio Cotia",
            "city": "Cotia",
            "state": "sp",
            "zipcode": "06714360",
            "country": "br",
            "id": 146610
        },
        "object": "shipping",
        "id": 28,
        "name": "Neo Reeves",
        "fee": 3311,
        "delivery_date": "2000-12-21",
        "expedited": true
    },
    "items": [
        {
            "object": "item",
            "id": "1",
            "title": "Red pill",
            "unit_price": 12000,
            "quantity": 1,
            "category": null,
            "tangible": true,
            "venue": null,
            "date": null
        },
        {
            "object": "item",
            "id": "a123",
            "title": "Blue pill",
            "unit_price": 12000,
            "quantity": 1,
            "category": null,
            "tangible": true,
            "venue": null,
            "date": null
        }
    ],
    "card": {
        "object": "card",
        "id": "card_cj6drvxnm0lqo696dirob3ibk",
        "date_created": "2017-08-15T15:58:31.714Z",
        "date_updated": "2017-08-15T15:58:32.098Z",
        "brand": "visa",
        "holder_name": "Morpheus Fishburne",
        "first_digits": "411111",
        "last_digits": "1111",
        "country": "UNITED STATES",
        "fingerprint": "3ace8040fba3f5c3a0690ea7964ea87d97123437",
        "valid": true,
        "expiration_date": "0922"
    },
    "split_rules": null,
    "metadata": {},
    "antifraud_metadata": {},
    "reference_key": null
}

Suggest Edits

Estorno parcial com split

Além de estornos parciais regulares, em que você pode especificar apenas o valor, existe também o estorno com split. Neste caso, é possível especificar quanto e quem será responsável pelo valor sendo estornado. Isto é particularmente importante para quando parte da venda não foi finalizada ( e.g: produto devolvido), e o respectivo valor precisa ser estornado, mas somente do recebedor responsável. A seguir alguns exemplos de como executar esta operação.

Vale ressaltar que caso a transação seja por boleto, a regra de estorno permanece, e torna-se necessário enviar os dados de conta bancária de quem deve receber o estorno.

posthttps://api.pagar.me/1/transactions/id/refund

Path Params

string

required

ID da transação a ser estornada.

Body Params

amount

int32

required

Valor desejado para o estorno da transação. Deve ser passado em centavos. Ex: R$ 10.00 = 1000.

async

boolean

Determina se a requisição deve ser síncrona (false), ou assíncrona, em que a resposta final do estorno é enviada através de sua postback_url.

split_rules

array of objects

required

Define as regras de split para o estorno.

percentage

amount

recipient_id

charge_processing_fee

bank_account_id

string

required

ID de uma conta bancária já cadastrada no Pagar.me

bank_account

object

required

Objeto que contém os dados da conta bancária de quem deve receber o estorno.

bank_account.bank_code

string

required

Código do banco da conta

bank_account.agencia

string

required

Agencia do banco da conta

bank_account.agencia_dv

string

Apenas números, deve conter somente 1 dígito

bank_account.conta

string

required

Número da conta

bank_account.type

string

Tipo da conta. Pode ser: conta_corrente, conta_poupanca, conta_corrente_conjunta, conta_poupanca_conjunta

bank_account.conta_dv

string

required

Dígito verificador da conta

bank_account.document_number

string

required

CPF/CNPJ atrelado à conta

bank_account.legal_name

string

required

Nome/Razão social do dono da conta

metadata

json

Você pode passar dados adicionais no estorno da transação para facilitar uma futura análise de dados por seus sistemas.

curl -X POST 'https://api.pagar.me/1/transactions/:id/refund' -H 'content-type: application/json' -d '{
    "amount": "6153",
    "async": "false",
    "api_key": "SUA_API_KEY",
    "split_rules": [
        {
            "id": "sr_cj41w9m4d01ta316d02edaqav",
            "amount": "3000",
            "recipient_id": "re_cj2wd5ul500d4946do7qtjrvk"
        },
        {
            "id": "sr_cj41w9m4e01tb316dl2f2veyz",
            "amount": "3153",
            "recipient_id": "re_cj2wd5u2600fecw6eytgcbkd0",
            "charge_processing_fee": "true"
        }
    ]
}'

require 'pagarme'

PagarMe.api_key = 'SUA API KEY'

transaction = PagarMe::Transaction.find_by_id("1627836")

transaction.refund({
  async: false,
  amount: 71000,
  split_rules:[
    {
      "id": "sr_cj41w9m4d01ta316d02edaqav",
      "amount": "60000",
      "recipient_id": "re_cj2wd5ul500d4946do7qtjrvk"
    },
    {
      "id": "sr_cj41w9m4e01tb316dl2f2veyz",
      "amount": "11000",
      "recipient_id": "re_cj2wd5u2600fecw6eytgcbkd0",
      "charge_processing_fee": "true"
     }
  ]
})

<?php
    require("pagarme-php/Pagarme.php");

    Pagarme::setApiKey("SUA_API_KEY");

    $t = PagarMe_Transaction::findById("1627836");

    $params = array(
      "async" => false,
      "amount" => 20000,
      "split_rules" => array(
        array(
          "id" => "sr_cj41w9m4d01ta316d02edaqav",
          "amount" => "60000",
          "recipient_id" => "re_cj2wd5ul500d4946do7qtjrvk"
        ),
        array(
          "id" => "sr_cj41w9m4e01tb316dl2f2veyz",
          "amount" => "11000",
          "recipient_id" => "re_cj2wd5u2600fecw6eytgcbkd0",
          "charge_processing_fee" => true
        )
      )
    );

    $t->refund($params);

?>

Oops, ainda não temos essa feature no SDK.

Oops, ainda não temos essa feature no SDK.

Oops, ainda não temos essa feature no SDK.

Oops, ainda não temos essa feature no SDK.

import pagarme

pagarme.authentication_key("SUA_API_KEY")

transaction = pagarme.transaction.find_by({
    "id": "TRANSACTION_ID"
})

print(pagarme.transaction.refund(
    transaction[0]['id'],
    {
        "amount": "Valor a ser estornado",
        "split_rules": [
            {
                "id": "sr_cj41w9m4d01ta316d02edaqav",
                "amount": "60000",
                "recipient_id": "re_cj2wd5ul500d4946do7qtjrvk"
            },
            {
                "id": "sr_cj41w9m4e01tb316dl2f2veyz",
                "amount": "11000",
                "recipient_id": "re_cj2wd5u2600fecw6eytgcbkd0",
                "charge_processing_fee": "true"
            }
        ]
    }
))

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

{
    "object": "transaction",
    "status": "authorized",
    "refuse_reason": null,
    "status_reason": "acquirer",
    "acquirer_response_code": "0000",
    "acquirer_name": "pagarme",
    "acquirer_id": "58a49047916d40fa539ba926",
    "authorization_code": "737870",
    "soft_descriptor": null,
    "tid": 1836030,
    "nsu": 1836030,
    "date_created": "2017-08-15T16:14:58.903Z",
    "date_updated": "2017-08-15T16:14:59.179Z",
    "amount": 10000,
    "authorized_amount": 10000,
    "paid_amount": 0,
    "refunded_amount": 0,
    "installments": 1,
    "id": 1836030,
    "cost": 0,
    "card_holder_name": "Morpheus Fishburne",
    "card_last_digits": "1111",
    "card_first_digits": "411111",
    "card_brand": "visa",
    "card_pin_mode": null,
    "postback_url": null,
    "payment_method": "credit_card",
    "capture_method": "ecommerce",
    "antifraud_score": null,
    "boleto_url": null,
    "boleto_barcode": null,
    "boleto_expiration_date": null,
    "referer": "api_key",
    "ip": "10.2.13.68",
    "subscription_id": null,
    "phone": null,
    "address": null,
    "customer": {
        "object": "customer",
        "id": 234275,
        "external_id": "#3311",
        "type": "individual",
        "country": "br",
        "document_number": null,
        "document_type": "cpf",
        "name": "Morpheus Fishburne",
        "email": "mopheus@nabucodonozor.com",
        "phone_numbers": [
            "+5511999998888",
            "+5511888889999"
        ],
        "born_at": null,
        "birthday": "1965-01-01",
        "gender": null,
        "date_created": "2017-08-15T16:14:58.815Z",
        "documents": [
            {
                "object": "document",
                "id": "doc_cj6dsh3bj0mlj6m6dmm39mqmb",
                "type": "cpf",
                "number": "00000000000"
            }
        ]
    },
    "billing": {
        "address": {
            "object": "address",
            "street": "Rua Matrix",
            "complementary": null,
            "street_number": "9999",
            "neighborhood": "Rio Cotia",
            "city": "Cotia",
            "state": "sp",
            "zipcode": "06714360",
            "country": "br",
            "id": 146613
        },
        "object": "billing",
        "id": 35,
        "name": "Trinity Moss"
    },
    "shipping": {
        "address": {
            "object": "address",
            "street": "Rua Matrix",
            "complementary": null,
            "street_number": "9999",
            "neighborhood": "Rio Cotia",
            "city": "Cotia",
            "state": "sp",
            "zipcode": "06714360",
            "country": "br",
            "id": 146614
        },
        "object": "shipping",
        "id": 29,
        "name": "Neo Reeves",
        "fee": 3311,
        "delivery_date": "2000-12-21",
        "expedited": true
    },
    "items": [
        {
            "object": "item",
            "id": "1",
            "title": "Red pill",
            "unit_price": 12000,
            "quantity": 1,
            "category": null,
            "tangible": true,
            "venue": null,
            "date": null
        },
        {
            "object": "item",
            "id": "a123",
            "title": "Blue pill",
            "unit_price": 12000,
            "quantity": 1,
            "category": null,
            "tangible": true,
            "venue": null,
            "date": null
        }
    ],
    "card": {
        "object": "card",
        "id": "card_cj6dsh3d90mlk6m6d951q4wil",
        "date_created": "2017-08-15T16:14:58.894Z",
        "date_updated": "2017-08-15T16:14:59.261Z",
        "brand": "visa",
        "holder_name": "Morpheus Fishburne",
        "first_digits": "411111",
        "last_digits": "1111",
        "country": "UNITED STATES",
        "fingerprint": "3ace8040fba3f5c3a0690ea7964ea87d97123437",
        "valid": true,
        "expiration_date": "0922"
    },
    "split_rules": [
        {
            "object": "split_rule",
            "id": "sr_cj6dsh3eg0mlm6m6dh6r036bk",
            "liable": true,
            "amount": null,
            "percentage": 50,
            "recipient_id": "re_cj6dsgxiz0mlh6m6d6e20rvuy",
            "charge_remainder": false,
            "charge_processing_fee": true,
            "date_created": "2017-08-15T16:14:58.936Z",
            "date_updated": "2017-08-15T16:14:58.936Z"
        },
        {
            "object": "split_rule",
            "id": "sr_cj6dsh3ef0mll6m6dxk40wxw8",
            "liable": true,
            "amount": null,
            "percentage": 50,
            "recipient_id": "re_cj6dsc0i90o56yy6erybyxs9p",
            "charge_remainder": true,
            "charge_processing_fee": true,
            "date_created": "2017-08-15T16:14:58.936Z",
            "date_updated": "2017-08-15T16:14:58.936Z"
        }
    ],
    "metadata": {},
    "antifraud_metadata": {},
    "reference_key": null
}

Suggest Edits

Retornando transações

Retorna um Array contendo objetos de transações, ordenadas a partir da transação realizada mais recentemente.

gethttps://api.pagar.me/1/transactions

Query Params

count

int32

Retorna n objetos de transação

page

int32

Útil para implementação de uma paginação de resultados

status

string

Filtro para um dos status: processing, authorized, paid, refunded, waiting_payment, pending_refund, refused

date_created

date-time

Filtro para data de criação

date_updated

date-time

Filtro para data de último update

amount

string

Filtro pelo valor da transação

installments

string

Filtro de parcelas da transação

string

Filtro de id

tid

string

Filtro de tid

nsu

string

Filtro de nsu

card_holder_name

string

Filtro de nome do detentor do cartão

card_last_digits

string

Filtro dos últimos 4 dígitos do cartão

card_brand

string

Filtro da bandeira do cartão: amex, aura, discover, elo, hipercard, jcb, visa, mastercard

postback_url

string

Filtro de postback_url

payment_method

string

Filtro de método de pagamento: credit_card, boleto

capture_method

string

Filtro de método de captura

boleto_url

string

Filtro de boleto_url

antifraud_score

string

Filtro de score de antifraud

boleto_barcode

string

Filtro de código de barras de boletos

subscription_id

string

Filtro de subscription

customer

object

Filtro de todos os atributos do cliente

address

object

Filtro de todos os atributos de endereço

phone

object

Filtro de todos os atributos do telefone

metadata

object

Filtro de todos os parâmetros de metadata. Depende do metadata.

Filtros

Todos os filtros mencionados podem ser usados para buscas em ranges usando os prefixos:

Prefixo	Significado
<	menor que
>	maior que
<=	menor ou igual a
>=	maior ou igual a

Por exemplo, para buscar em um range de date_created:

curl -X GET https://api.pagar.me/1/transactions \
-d 'api_key=ak_test_grXijQ4GicOa2BLGZrDRTR5qNQxJW0'
-d 'date_created=>=1483236000000'
-d 'date_created=<=1484689847590'

Para campos que sejam strings, a comparação é lexicográfica, letras maiúsculas sendo 'maiores' que minúsculas.

Filtro de data

É importante notar que a filtragem por data utiliza unixTimeStamp para representá-la. Para gerar o unixTimeStamp de uma data, é possível utilizar o console do Google Chrome com o seguinte código em Javascript : new Date("2017-12-25T02:00:00.000Z").getTime() que retornará 1514167200000

curl -X GET https://api.pagar.me/1/transactions -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY"
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

transactions = PagarMe::Transaction.all(3, 3)

<?php
    require("pagarme-php/Pagarme.php");

    Pagarme::setApiKey("SUA_API_KEY");

    $transaction = PagarMe_Transaction::all(3, 3)

PagarMeService.DefaultApiKey = "SUA_API_KEY";

var transaction = PagarMeService.GetDefaultService().Transactions.FindAll(new Transaction());

import java.util.Collection;

import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Transaction;

PagarMe.init("SUA_API_KEY");

Collection<Transaction> txs = new Transaction().findCollection(10, 1);

<?php
	require __DIR__.'/vendor/autoload.php';

	$pagarMe = new \PagarMe\Sdk\PagarMe('SUA_API_KEY');

	$page = 1;
	$count = 10;
	$transactionList = $pagarMe->transaction()->getList($page, $count);

const pagarme = require('pagarme')
  
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.transactions.all())
  .then(transactions => console.log(transactions))

import pagarme

pagarme.authentication_key("SUA_API_KEY")

transaction = pagarme.transaction.find_all()

print(transaction)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

[
    {
        "object": "transaction",
        "status": "authorized",
        "refuse_reason": null,
        "status_reason": "acquirer",
        "acquirer_response_code": "0000",
        "acquirer_name": "pagarme",
        "acquirer_id": "58a49047916d40fa539ba926",
        "authorization_code": "737870",
        "soft_descriptor": null,
        "tid": 1836030,
        "nsu": 1836030,
        "date_created": "2017-08-15T16:14:58.903Z",
        "date_updated": "2017-08-15T16:14:59.179Z",
        "amount": 10000,
        "authorized_amount": 10000,
        "paid_amount": 0,
        "refunded_amount": 0,
        "installments": 1,
        "id": 1836030,
        "cost": 0,
        "card_holder_name": "Morpheus Fishburne",
        "card_last_digits": "1111",
        "card_first_digits": "411111",
        "card_brand": "visa",
        "card_pin_mode": null,
        "postback_url": null,
        "payment_method": "credit_card",
        "capture_method": "ecommerce",
        "antifraud_score": null,
        "boleto_url": null,
        "boleto_barcode": null,
        "boleto_expiration_date": null,
        "referer": "api_key",
        "ip": "10.2.13.68",
        "subscription_id": null,
        "phone": null,
        "address": null,
        "customer": {
            "object": "customer",
            "id": 234275,
            "external_id": "#3311",
            "type": "individual",
            "country": "br",
            "document_number": null,
            "document_type": "cpf",
            "name": "Morpheus Fishburne",
            "email": "mopheus@nabucodonozor.com",
            "phone_numbers": [
                "+5511999998888",
                "+5511888889999"
            ],
            "born_at": null,
            "birthday": "1965-01-01",
            "gender": null,
            "date_created": "2017-08-15T16:14:58.815Z",
            "documents": [
                {
                    "object": "document",
                    "id": "doc_cj6dsh3bj0mlj6m6dmm39mqmb",
                    "type": "cpf",
                    "number": "00000000000"
                }
            ]
        },
        "billing": {
            "address": {
                "object": "address",
                "street": "Rua Matrix",
                "complementary": null,
                "street_number": "9999",
                "neighborhood": "Rio Cotia",
                "city": "Cotia",
                "state": "sp",
                "zipcode": "06714360",
                "country": "br",
                "id": 146613
            },
            "object": "billing",
            "id": 35,
            "name": "Trinity Moss"
        },
        "shipping": {
            "address": {
                "object": "address",
                "street": "Rua Matrix",
                "complementary": null,
                "street_number": "9999",
                "neighborhood": "Rio Cotia",
                "city": "Cotia",
                "state": "sp",
                "zipcode": "06714360",
                "country": "br",
                "id": 146614
            },
            "object": "shipping",
            "id": 29,
            "name": "Neo Reeves",
            "fee": 3311,
            "delivery_date": "2000-12-21",
            "expedited": true
        },
        "items": [],
        "card": {
            "object": "card",
            "id": "card_cj6dsh3d90mlk6m6d951q4wil",
            "date_created": "2017-08-15T16:14:58.894Z",
            "date_updated": "2017-08-15T16:14:58.894Z",
            "brand": "visa",
            "holder_name": "Morpheus Fishburne",
            "first_digits": "411111",
            "last_digits": "1111",
            "country": "UNITED STATES",
            "fingerprint": "3ace8040fba3f5c3a0690ea7964ea87d97123437",
            "valid": null,
            "expiration_date": "0922"
        },
        "split_rules": [
            {
                "object": "split_rule",
                "id": "sr_cj6dsh3eg0mlm6m6dh6r036bk",
                "liable": true,
                "amount": null,
                "percentage": 50,
                "recipient_id": "re_cj6dsgxiz0mlh6m6d6e20rvuy",
                "charge_remainder": false,
                "charge_processing_fee": true,
                "date_created": "2017-08-15T16:14:58.936Z",
                "date_updated": "2017-08-15T16:14:58.936Z"
            },
            {
                "object": "split_rule",
                "id": "sr_cj6dsh3ef0mll6m6dxk40wxw8",
                "liable": true,
                "amount": null,
                "percentage": 50,
                "recipient_id": "re_cj6dsc0i90o56yy6erybyxs9p",
                "charge_remainder": true,
                "charge_processing_fee": true,
                "date_created": "2017-08-15T16:14:58.936Z",
                "date_updated": "2017-08-15T16:14:58.936Z"
            }
        ],
        "antifraud_metadata": {},
        "reference_key": null,
        "metadata": {}
    },
    {
        "object": "transaction",
        "status": "authorized",
        "refuse_reason": null,
        "status_reason": "acquirer",
        "acquirer_response_code": "0000",
        "acquirer_name": "pagarme",
        "acquirer_id": "58a49047916d40fa539ba926",
        "authorization_code": "688274",
        "soft_descriptor": null,
        "tid": 1835912,
        "nsu": 1835912,
        "date_created": "2017-08-15T15:58:31.733Z",
        "date_updated": "2017-08-15T15:58:53.177Z",
        "amount": 10000,
        "authorized_amount": 10000,
        "paid_amount": 0,
        "refunded_amount": 1200,
        "installments": 1,
        "id": 1835912,
        "cost": 0,
        "card_holder_name": "Morpheus Fishburne",
        "card_last_digits": "1111",
        "card_first_digits": "411111",
        "card_brand": "visa",
        "card_pin_mode": null,
        "postback_url": null,
        "payment_method": "credit_card",
        "capture_method": "ecommerce",
        "antifraud_score": null,
        "boleto_url": null,
        "boleto_barcode": null,
        "boleto_expiration_date": null,
        "referer": "api_key",
        "ip": "10.2.14.195",
        "subscription_id": null,
        "phone": null,
        "address": null,
        "customer": {
            "object": "customer",
            "id": 234265,
            "external_id": "#3311",
            "type": "individual",
            "country": "br",
            "document_number": null,
            "document_type": "cpf",
            "name": "Morpheus Fishburne",
            "email": "mopheus@nabucodonozor.com",
            "phone_numbers": [
                "+5511999998888",
                "+5511888889999"
            ],
            "born_at": null,
            "birthday": "1965-01-01",
            "gender": null,
            "date_created": "2017-08-15T15:58:31.636Z",
            "documents": [
                {
                    "object": "document",
                    "id": "doc_cj6drvxlw0lqn696dtbbwri6y",
                    "type": "cpf",
                    "number": "00000000000"
                }
            ]
        },
        "billing": {
            "address": {
                "object": "address",
                "street": "Rua Matrix",
                "complementary": null,
                "street_number": "9999",
                "neighborhood": "Rio Cotia",
                "city": "Cotia",
                "state": "sp",
                "zipcode": "06714360",
                "country": "br",
                "id": 146609
            },
            "object": "billing",
            "id": 34,
            "name": "Trinity Moss"
        },
        "shipping": {
            "address": {
                "object": "address",
                "street": "Rua Matrix",
                "complementary": null,
                "street_number": "9999",
                "neighborhood": "Rio Cotia",
                "city": "Cotia",
                "state": "sp",
                "zipcode": "06714360",
                "country": "br",
                "id": 146610
            },
            "object": "shipping",
            "id": 28,
            "name": "Neo Reeves",
            "fee": 3311,
            "delivery_date": "2000-12-21",
            "expedited": true
        },
        "items": [
            {
                "object": "item",
                "id": "1",
                "title": "Red pill",
                "unit_price": 12000,
                "quantity": 1,
                "category": null,
                "tangible": true,
                "venue": null,
                "date": null
            },
            {
                "object": "item",
                "id": "a123",
                "title": "Blue pill",
                "unit_price": 12000,
                "quantity": 1,
                "category": null,
                "tangible": true,
                "venue": null,
                "date": null
            }
        ],
        "card": {
            "object": "card",
            "id": "card_cj6drvxnm0lqo696dirob3ibk",
            "date_created": "2017-08-15T15:58:31.714Z",
            "date_updated": "2017-08-15T15:58:32.098Z",
            "brand": "visa",
            "holder_name": "Morpheus Fishburne",
            "first_digits": "411111",
            "last_digits": "1111",
            "country": "UNITED STATES",
            "fingerprint": "3ace8040fba3f5c3a0690ea7964ea87d97123437",
            "valid": true,
            "expiration_date": "0922"
        },
        "split_rules": null,
        "antifraud_metadata": {},
        "reference_key": null,
        "metadata": {}
    }
]

Suggest Edits

Retornando uma transação

Retorna os dados de uma transação em específico, com as informações em um único objeto.

gethttps://api.pagar.me/1/transactions/transaction_id

Path Params

transaction_id

string

required

Id da transação

Retornando uma transação com Reference Key

Caso tenha sido enviado o parâmetro reference_key na criação da transação, será possível utilizá-lo para retornar os dados da mesma.

curl -X GET https://api.pagar.me/1/transactions/1835855 -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY"
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

transaction = PagarMe::Transaction.find_by_id("1627864")

<?php
    require("pagarme-php/Pagarme.php");

    Pagarme::setApiKey("SUA_API_KEY");

    $transaction = PagarMe_Transaction::findById("1627864");

PagarMeService.DefaultApiKey = "SUA_API_KEY";

var transaction = PagarMeService.GetDefaultService().Transactions.Find("1627864");

import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Transaction;

PagarMe.init("SUA_API_KEY");

Transaction tx = new Transaction().find(1627864);

<?php
	require __DIR__.'/vendor/autoload.php';

	$pagarMe = new \PagarMe\Sdk\PagarMe('SUA_API_KEY');

	$transactionId = "1627864";
	$transaction = $pagarMe->transaction()->get($transactionId);

const pagarme = require('pagarme')
  
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.transactions.find({ id: '1627864' }))
	.then(transaction => console.log(transaction))

import pagarme

pagarme.authentication_key("SUA_API_KEY")

transaction = pagarme.transaction.find_by({"id":"ID_DA_TRANSAÇÃO"})

print(transaction)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

{
    "object": "transaction",
    "status": "paid",
    "refuse_reason": null,
    "status_reason": "acquirer",
    "acquirer_response_code": "0000",
    "acquirer_name": "pagarme",
    "acquirer_id": "58a49047916d40fa539ba926",
    "authorization_code": "448887",
    "soft_descriptor": null,
    "tid": 1835855,
    "nsu": 1835855,
    "date_created": "2017-08-15T15:47:44.686Z",
    "date_updated": "2017-08-15T15:47:45.175Z",
    "amount": 10000,
    "authorized_amount": 10000,
    "paid_amount": 10000,
    "refunded_amount": 0,
    "installments": 1,
    "id": 1835855,
    "cost": 50,
    "card_holder_name": "Morpheus Fishburne",
    "card_last_digits": "1111",
    "card_first_digits": "411111",
    "card_brand": "visa",
    "card_pin_mode": null,
    "postback_url": null,
    "payment_method": "credit_card",
    "capture_method": "ecommerce",
    "antifraud_score": null,
    "boleto_url": null,
    "boleto_barcode": null,
    "boleto_expiration_date": null,
    "referer": "api_key",
    "ip": "10.2.13.68",
    "subscription_id": null,
    "phone": null,
    "address": null,
    "customer": {
        "object": "customer",
        "id": 234253,
        "external_id": "#3311",
        "type": "individual",
        "country": "br",
        "document_number": null,
        "document_type": "cpf",
        "name": "Morpheus Fishburne",
        "email": "mopheus@nabucodonozor.com",
        "phone_numbers": [
            "+5511999998888",
            "+5511888889999"
        ],
        "born_at": null,
        "birthday": "1965-01-01",
        "gender": null,
        "date_created": "2017-08-15T15:47:43.817Z",
        "documents": [
            {
                "object": "document",
                "id": "doc_cj6dri2ay0n7ryy6eff0c3oyh",
                "type": "cpf",
                "number": "71404665560"
            }
        ]
    },
    "billing": {
        "address": {
            "object": "address",
            "street": "Rua Matrix",
            "complementary": null,
            "street_number": "9999",
            "neighborhood": "Rio Cotia",
            "city": "Cotia",
            "state": "sp",
            "zipcode": "06714360",
            "country": "br",
            "id": 146605
        },
        "object": "billing",
        "id": 32,
        "name": "Trinity Moss"
    },
    "shipping": {
        "address": {
            "object": "address",
            "street": "Rua Matrix",
            "complementary": null,
            "street_number": "9999",
            "neighborhood": "Rio Cotia",
            "city": "Cotia",
            "state": "sp",
            "zipcode": "06714360",
            "country": "br",
            "id": 146606
        },
        "object": "shipping",
        "id": 26,
        "name": "Neo Reeves",
        "fee": 3311,
        "delivery_date": "2000-12-21",
        "expedited": true
    },
    "items": [
        {
            "object": "item",
            "id": "1",
            "title": "Red pill",
            "unit_price": 12000,
            "quantity": 1,
            "category": null,
            "tangible": true,
            "venue": null,
            "date": null
        },
        {
            "object": "item",
            "id": "a123",
            "title": "Blue pill",
            "unit_price": 12000,
            "quantity": 1,
            "category": null,
            "tangible": true,
            "venue": null,
            "date": null
        }
    ],
    "card": {
        "object": "card",
        "id": "card_cj6dri2e90n7syy6e11lthfha",
        "date_created": "2017-08-15T15:47:44.673Z",
        "date_updated": "2017-08-15T15:47:45.237Z",
        "brand": "visa",
        "holder_name": "Morpheus Fishburne",
        "first_digits": "411111",
        "last_digits": "1111",
        "country": "UNITED STATES",
        "fingerprint": "3ace8040fba3f5c3a0690ea7964ea87d97123437",
        "valid": true,
        "expiration_date": "0922"
    },
    "split_rules": null,
    "metadata": {},
    "antifraud_metadata": {},
    "reference_key": null
}

Suggest Edits

Retornando recebíveis de uma transação

Retorna um array com objetos recebíveis (payables). Os recebíveis são os dados de pagamento referentes a uma transação.

gethttps://api.pagar.me/1/transactions/transaction_id/payables

Path Params

transaction_id

string

required

ID da transação a que os recebíveis pertencem.

Status de um recebível

É possível verificar os status de um recebível aqui

Transação por boleto

Criou uma transação por boleto e sua transação não possui recebível? Esse comportamento é normal, o recebível será criado assim que o boleto estiver pago.

curl -X GET https://api.pagar.me/1/transactions/1665560/payables -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY"
}'

require 'pagarme'

PagarMe.api_key = 'SUA_API_KEY'

payables = PagarMe::Transaction.find('1665560').payables

<?php
    require("vendor/pagarme/pagarme-php/Pagarme.php");

    Pagarme::setApiKey("SUA_API_KEY");

    $transaction = PagarMe_Payable::findAllByTransactionId(1665560);

    print_r($transaction);
?>

PagarMeService.DefaultApiKey = "SUA_API_KEY";
var payables = PagarMeService.GetDefaultService().Transactions.Find("1665560").Payables;

import java.util.Collection;

import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Payable;
import me.pagar.model.Transaction;

PagarMe.init("SUA_API_KEY");

Collection<Payable> payables = new Transaction().find(1665560).payables();

const pagarme = require('pagarme')

pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.payables.find({
    transactionId: '1665560'
  }))
  .then(payables => console.log(payables))

Não temos essa funcionalidade :(

import pagarme

pagarme.authentication_key("SUA_API_KEY")

transaction = pagarme.transaction.find_by({"id":"ID_DA_TRANSAÇÃO"})

payables = pagarme.transaction.payables(transaction[0]['id'])
print(payables)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

[
  {
    "object": "payable",
    "id": 1714903,
    "status": "waiting_funds",
    "amount": 24000,
    "fee": 6000,
    "anticipation_fee": 0,
    "installment": 1,
    "transaction_id": 1665560,
    "split_rule_id": "sr_cj4ir4qks00p8tp6ey5eoovhs",
    "bulk_anticipation_id": null,
    "recipient_id": "re_cj2wd5u2600fecw6eytgcbkd0",
    "payment_date": "2017-08-01T03:00:00.000Z",
    "original_payment_date": null,
    "type": "credit",
    "payment_method": "credit_card",
    "accrual_date": "2017-06-29T18:16:49.303Z",
    "date_created": "2017-06-29T18:16:49.411Z"
  },
  {
    "object": "payable",
    "id": 1714902,
    "status": "waiting_funds",
    "amount": 96000,
    "fee": 0,
    "anticipation_fee": 0,
    "installment": 1,
    "transaction_id": 1665560,
    "split_rule_id": "sr_cj4ir4qkr00p7tp6ehtrr3tij",
    "bulk_anticipation_id": null,
    "recipient_id": "re_cj2wd5ul500d4946do7qtjrvk",
    "payment_date": "2017-08-01T03:00:00.000Z",
    "original_payment_date": null,
    "type": "credit",
    "payment_method": "credit_card",
    "accrual_date": "2017-06-29T18:16:49.303Z",
    "date_created": "2017-06-29T18:16:49.411Z"
  }
]

Suggest Edits

Retornando um recebível da transação

Retorna um objeto recebível (payable) informando os dados de um pagamento referente a uma transação em específico.

gethttps://api.pagar.me/1/transactions/transaction_id/payables/payable_id

Path Params

transaction_id

string

required

ID da transação a que o recebível pertence.

payable_id

string

required

ID do recebível que deseja retornar

curl -X GET https://api.pagar.me/1/transactions/1665560/payables/1714902 -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY"
}'

PagarMeService.DefaultApiKey = "SUA_API_KEY";
var payable = PagarMeService.GetDefaultService().Transactions.Find("1665560").Payables.Find("1714902");

const pagarme = require('pagarme')

pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.payables.find({
    transactionId: '1665560',
  	id: '1714902'
  }))
  .then(payables => console.log(payables))

<?php
    require("vendor/pagarme/pagarme-php/Pagarme.php");

    Pagarme::setApiKey("SUA_API_KEY");

    $payable = PagarMe_Payable::findTrasactionById(1665560,1714902);

    print_r($payable);
?>

Não temos essa funcionalidade ainda :(

import me.pagar.model.PagarMe;
import me.pagar.model.Transaction;
import me.pagar.model.PagarMeException;
import me.pagar.model.Payable;

PagarMe.init("SUA_API_KEY");
    	
Payable p = new Transaction().find(1665560).payables(1714902);

Não temos essa funcionalidade :(

import pagarme

pagarme.authentication_key("SUA_API_KEY")

transaction = pagarme.transaction.find_by({"id":"ID_DA_TRANSACAO"})

payable = pagarme.transaction.specific_payable(transaction[0]['id'], "ID_DO_RECEBIVEL")
print(payable)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

{
  "object": "payable",
  "id": 1714902,
  "status": "waiting_funds",
  "amount": 96000,
  "fee": 0,
  "anticipation_fee": 0,
  "installment": 1,
  "transaction_id": 1665560,
  "split_rule_id": "sr_cj4ir4qkr00p7tp6ehtrr3tij",
  "bulk_anticipation_id": null,
  "recipient_id": "re_cj2wd5ul500d4946do7qtjrvk",
  "payment_date": "2017-08-01T03:00:00.000Z",
  "original_payment_date": null,
  "type": "credit",
  "payment_method": "credit_card",
  "accrual_date": "2017-06-29T18:16:49.303Z",
  "date_created": "2017-06-29T18:16:49.411Z"
}

Suggest Edits

Retornando histórico de uma transação

Retorna todo o histórico de uma transação, ou seja, toda e qualquer operação que já aconteceu com ela.

Ex: autorização, análise antifraude, captura, estorno, chargeback, emissão de boleto, conciliação, etc.

gethttps://api.pagar.me/1/transactions/transaction_id/operations

Path Params

transaction_id

string

required

Id da transação

curl -X GET https://api.pagar.me/1/transactions/1627864/operations -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY"
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

transaction = PagarMe::Transaction.find_by_id("1627864")

transaction.operations

Oops, ainda não temos essa feature no SDK.

Oops, ainda não temos essa feature no SDK.

Oops, ainda não temos essa feature no SDK.

const pagarme = require('pagarme')
  
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.gatewayOperations.find({ transactionId: 1627864 }))
  .then(gatewayOperations => console.log(gatewayOperations))

Oops, ainda não temos essa feature no SDK.

import pagarme

pagarme.authentication_key("SUA_API_KEY")

operations = pagarme.transaction.operations(1912601)

print(operations)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

[
  {
    "id": "go_cj423rfvs1co0023tb95ip38i",
    "date_created": "2017-06-18T02:38:18.664Z",
    "date_updated": "2017-06-18T02:38:18.909Z",
    "status": "success",
    "fail_reason": null,
    "type": "capture",
    "rollbacked": false,
    "model": "transaction",
    "model_id": "1627864",
    "group_id": "gog_cj423rfvs1co1023tgmuch6f0",
    "next_group_id": null,
    "request_id": "gr_cj423rfvc1cnz023tjleg2wp6",
    "started_at": 1497753498775,
    "ended_at": 1497753498909,
    "processor": "pagarme",
    "processor_response_code": null,
    "metadata": {
      "environment": {
        "captured_amount": 75000
      }
    }
  },
  {
    "id": "go_cj423rfvz1co2023tznwhz9lk",
    "date_created": "2017-06-18T02:38:18.671Z",
    "date_updated": "2017-06-18T02:38:18.768Z",
    "status": "success",
    "fail_reason": null,
    "type": "authorize",
    "rollbacked": false,
    "model": "transaction",
    "model_id": "1627864",
    "group_id": "gog_cj423rfvz1co3023tep5sw66m",
    "next_group_id": "gog_cj423rfvs1co1023tgmuch6f0",
    "request_id": "gr_cj423rfvc1cnz023tjleg2wp6",
    "started_at": 1497753498691,
    "ended_at": 1497753498768,
    "processor": "pagarme",
    "processor_response_code": "0000",
    "metadata": {
      "environment": {
        "response_code": "0000",
        "authorization_code": "713332",
        "authorized_amount": 75000,
        "tid": "1627864",
        "nsu": "1627864"
      }
    }
  }
]

Suggest Edits

Tipos de operações

Quando uma transação é criada ela passa por uma série de operações, que são procedimentos internos ao fluxo de uma transação. Entre tais operações existem:

Authorize: Feito para todo e qualquer tipo de transação. É usado para autorizar a quantia pedida junto com o Pagar.me
Analyze: Operação feita junto ao antifraude, com o intuito de analisar os dados passados.
Issue: Apenas para boletos, tem o intuito de gerar o código de barras e url do boleto
Capture: Usada para cartões de crédito, é a operação que confirma a cobrança da quantia no cartão do portador junto ao banco emissor.
Conciliate: É a operação que identifica pagamento de boletos e chargebacks para transações de cartão de crédito junto ao banco emissor.
Refund: Operação de estorno, válida para qualquer tipo de transação.

Ao fazer um GET na rota /transactions/:id/operations, como na seção anterior, você irá receber um objeto do tipo:

Exemplo de retorno

JSON

[
    {
        "id": "go_cj25j5fbw07p7p03slfyxhxh7",
        "date_created": "2017-05-01T02:52:59.228Z",
        "date_updated": "2017-05-01T02:52:59.520Z",
        "status": "success",
        "fail_reason": null,
        "type": "capture",
        "rollbacked": false,
        "model": "transaction",
        "model_id": "1489647",
        "group_id": "gog_cj25j5fbw07p8p03sxjid6ybt",
        "next_group_id": null,
        "request_id": "gr_cj25j5fbi07p6p03su8bisxfe",
        "started_at": 1493607179383,
        "ended_at": 1493607179520,
        "processor": "pagarme",
        "processor_response_code": null,
        "metadata": {
            "environment": {
                "captured_amount": 150000
            }
        }
    },
    {
        "id": "go_cj25j5fc407p9p03sfq1xa2y0",
        "date_created": "2017-05-01T02:52:59.236Z",
        "date_updated": "2017-05-01T02:52:59.375Z",
        "status": "success",
        "fail_reason": null,
        "type": "analyze",
        "rollbacked": false,
        "model": "transaction",
        "model_id": "1489647",
        "group_id": "gog_cj25j5fc407pap03s5aa8nv96",
        "next_group_id": "gog_cj25j5fbw07p8p03sxjid6ybt",
        "request_id": "gr_cj25j5fbi07p6p03su8bisxfe",
        "started_at": 1493607179326,
        "ended_at": 1493607179375,
        "processor": "antifraud",
        "processor_response_code": null,
        "metadata": {
            "environment": {
            },
            "kind": "rule"
        }
    },
    {
        "id": "go_cj25j5ff107pgp03s7gjghx3c",
        "date_created": "2017-05-01T02:52:59.341Z",
        "date_updated": "2017-05-01T02:52:59.368Z",
        "status": "failed",
        "fail_reason": "environment_error",
        "type": "analyze",
        "rollbacked": false,
        "model": "transaction",
        "model_id": "1489647",
        "group_id": "gog_cj25j5fc407pap03s5aa8nv96",
        "next_group_id": "gog_cj25j5fbw07p8p03sxjid6ybt",
        "request_id": "gr_cj25j5fbi07p6p03su8bisxfe",
        "started_at": 1493607179339,
        "ended_at": 1493607179368,
        "processor": "development",
        "processor_response_code": null,
        "metadata": {
            "environment": {
            },
            "kind": "analyze",
            "antifraud_analysis_id": 297636
        }
    },
    {
        "id": "go_cj25j5fca07pbp03s0hnvc21q",
        "date_created": "2017-05-01T02:52:59.242Z",
        "date_updated": "2017-05-01T02:52:59.320Z",
        "status": "success",
        "fail_reason": null,
        "type": "authorize",
        "rollbacked": false,
        "model": "transaction",
        "model_id": "1489647",
        "group_id": "gog_cj25j5fca07pcp03sn5jqj0lh",
        "next_group_id": "gog_cj25j5fc407pap03s5aa8nv96",
        "request_id": "gr_cj25j5fbi07p6p03su8bisxfe",
        "started_at": 1493607179261,
        "ended_at": 1493607179320,
        "processor": "pagarme",
        "processor_response_code": "0000",
        "metadata": {
            "environment": {
                "response_code": "0000",
                "authorization_code": "416762",
                "authorized_amount": 150000,
                "tid": "1489647",
                "nsu": "1489647"
            }
        }
    }
]

Significado de cada propriedade

Propriedade

Descrição

ID da operação realizada

date_created

Data(ISODate) em que a operação foi criada

date_updated

Data(ISODate) em que a operação foi atualizada.

status

Estado da operação. Valores possíveis: waiting, processing, deferred, failed, success, dropped.

fail_reason

Em caso de falha, essa propriedade mostra a sua respectiva causa.

type

Cada operação tem uma responsabilidade no fluxo de uma transação, tal característica é definida por seu tipo. Valores possíveis: authorize, analyze, capture, issue, conciliate, refund.

rollbacked

Define se a operação foi revertida ou não.

model

Define a qual modelo está operação pertence. Valores possíveis: transaction, subscription, card.

model_id

ID do respectivo modelo da operação.

group_id

Operações são executadas em grupo, e essa propriedade define a qual pertence a respectiva operação.

next_group_id

Operações seguem um fluxo, e você pode identificar qual foi o próximo grupo a ser executado por meio dessa propriedade. Ex: O próximo group de uma operação que envolve uma transação por boleto, pode ser a operação de issue, que pega um grupo de transações e gera as informações necessárias para seus respectivos boletos.

request_id

A propriedade define à qual request a respectiva operação tem origem.

started_at

Data(ISODate) em que a operação foi criada

ended_at

Data(ISODate) em que a operação foi finalizada.

processor

Define qual entidade no fluxo da operação foi responsável pelo procedimento.

processor_response_code

Corresponde ao código de retorno da entidade responsável por executar a operação.

metadata[environment][nsu]

Para a operação de authorize, o Pagar.me irá retornar o identificador NSU para transação.

metadata[environment][tid]

Para a operação de authorize, o Pagar.me irá retornar o identificador TID para transação.

metadata[environment][authorized_amount]

Para a operação de authorize, o Pagar.me irá confirmar o valor autorizado através desta propriedade.

metadata[environment][authorization_code]

Para a operação de authorize, o Pagar.me irá retornar um código correspondente ao processo de autorização junto ao banco emissor.

metadata[environment][response_code]

Corresponde ao código Pagar.me em relação ao status da operação.

metadata[kind]

Para operação de analyze, esta propriedade define o que está sendo executado em relação ao processo. Para kind = rule, a regra de antifraude em sua company está sendo executada, e para kind = analyze, o resultado da análise está sendo processado.

metadata[antifraud_analysis_id]

ID da análise de antifraude executada.

metadata[environment][captured_amount]

Para operação de capture, representa o valor capturado junto ao banco emissor, para cartões de crédito. OBS: Boletos não tem operação de capture, apenas issue, em que o valor de captura é confirmado.

metadata[environment][boleto_id]

ID do boleto, gerado da operação de issue.

metadata[environment][boleto_url]

URL do boleto, gerada da operação de issue.

metadata[environment][boleto_barcode]

Código de barras do boleto, gerado da operação de issue.

metadata[conciliation][type]

Está propriedade representa o tipo de conciliação feita junto ao banco emissor para esta transação. Valores possíveis: boleto_paid e chargeback

Suggest Edits

Notificando cliente sobre boleto a ser pago

Envia o link de um boleto pendente para o cliente.

posthttps://api.pagar.me/1/transactions/transaction_id/collect_payment

Path Params

transaction_id

string

required

ID da transação previamente criada

Body Params

email

string

required

email a ser enviado o link do boleto

Somente produção

Essa rota não funciona em ambiente de testes.

curl -X POST "https://api.pagar.me/1/transactions/ID_TRANSAÇÃO/collect_payment" -H "Content-Type: application/json" -d '{                 
		"api_key":"SUA_API_KEY",
    "email": "EMAIL_DO_SEU_CLIENTE"
}'

const pagarme = require('pagarme')
  
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.transactions.collectPayment({
    id: 314578,
    email: 'email=aardvark.silva@pagar.me',
  }))

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

transaction = PagarMe::Transaction.find_by_id("314578")

transaction.collect_payment

Oops, ainda não temos essa feature no SDK.

Oops, ainda não temos essa feature no SDK.

Oops, ainda não temos essa feature no SDK.

Oops, ainda não temos essa feature no SDK.

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

Try the API to see results

Suggest Edits

Retornando eventos de uma transação

Retorna todos os eventos de mudança de status de uma transação.

gethttps://api.pagar.me/1/transactions/transaction_id/events

Path Params

transaction_id

string

required

id da transação

curl -X GET https://api.pagar.me/1/transactions/1627864/events -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY"
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

transaction = PagarMe::Transaction.find_by_id("1627864")

transaction.events

Oops, ainda não temos essa feature no SDK.

PagarMeService.DefaultApiKey = "ak_test_grXijQ4GicOa2BLGZrDRTR5qNQxJW0";
var events = PagarMeService.GetDefaultService().Transactions.Find("1627864").Events;

<?php
	require __DIR__.'/vendor/autoload.php';

	$pagarMe = new \PagarMe\Sdk\PagarMe('SUA_API_KEY');

	$transactionId = "1627864";
	$transaction = $pagarMe->transaction()->get($transactionId);
	$transactionEvents = $pagarMe->transaction()->events($transaction);

const pagarme = require('pagarme')
  
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.events.find({ transactionId: 1627864 }))
	.then(events => console.log(events))

import pagarme

pagarme.authentication_key("SUA_API_KEY")

events = pagarme.transaction.events("transaction_id")

print(events)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

[
  {
    "object": "event",
    "id": "ev_cj425qedh01us316d9fl09djb",
    "name": "transaction_status_changed",
    "model": "transaction",
    "model_id": "1627864",
    "payload": {
      "old_status": "paid",
      "desired_status": "refunded",
      "current_status": "refunded"
    },
    "date_created": "2017-06-18T03:33:29.285Z",
    "date_updated": "2017-06-18T03:33:29.285Z"
  },
  {
    "object": "event",
    "id": "ev_cj423rjq901o4cd6epsphao29",
    "name": "transaction_status_changed",
    "model": "transaction",
    "model_id": "1627864",
    "payload": {
      "old_status": "processing",
      "desired_status": "paid",
      "current_status": "paid"
    },
    "date_created": "2017-06-18T02:38:23.649Z",
    "date_updated": "2017-06-18T02:38:23.649Z"
  }
]

Suggest Edits

Calculando Pagamentos Parcelados

Essa rota é utilizada para calcular o valor de cada uma das parcelas de uma compra e o valor final após aplicar os juros.

gethttps://api.pagar.me/1/transactions/calculate_installments_amount

Query Params

amount

int32

required

Valor do produto/serviço vendido

free_installments

string

Número de parcelas isentas de juros

max_installments

string

Valor máximo de parcelas

interest_rate

int32

required

Valor da taxa de juros

Juros?

Essa rota é uma recomendação, para que seja possível calcular juros como uma função das parcelas e uma porcentagem.
As contas utilizadas são:

for x in params[free_installments]..params[max_installments]
 | installment = x
 | amount = params[amount] * (1 + interest_rate * params[max_installments]  / 100))
 | installment_amount = amount / x

Lembrando que a Pagar.me NÃO cobra juros, essa rota é apenas uma rota de conveniência.

curl -X GET https://api.pagar.me/1/transactions/calculate_installments_amount -H 'content-type: application/json' -d '{
    "amount": "10000", 
    "api_key": "SUA_API_KEY", 
    "free_installments": "1", 
    "interest_rate": "13", 
    "max_installments": "3"
}'

require 'pagarme'

PagarMe.api_key = "ak_test_grXijQ4GicOa2BLGZrDRTR5qNQxJW0"

installments_result = PagarMe::Transaction.calculate_installments({
    amount: 10000,
    interest_rate: 13
})

<?php
require __DIR__.'/vendor/autoload.php';
$pagarMe = new \PagarMe\Sdk\PagarMe('SUA_API_KEY');

$amount = 10000;
$rate = 13;
$rateFreeInstallments = 1;
$maxInstallments = 12;
$installments = $pagarMe->calculation()->calculateInstallmentsAmount(
		$amount,
		$rate,
		$rateFreeInstallments,
		$maxInstallments
		);

$totalAmount = $installments[2]["total_amount"];
$installmentAmount = $installments[2]["installment_amount"];

const pagarme = require('pagarme')
  
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.transactions.calculateInstallmentsAmount({
    id: 1234,
    max_installments: 3,
    free_installments: 2,
    interest_rate: 13,
    amount: 1000
  }))
  .then(installments => console.log(installments))

<?php
 require ("vendor/pagarme/pagarme-php/Pagarme.php");

 PagarMe::setApiKey("SUA_API_KEY");

 $ObjectInstallments = Pagarme_Transaction::calculateInstallmentsAmount($amount, $interest_rate, $max_installments);

 ?>

Oops, ainda não temos essa feature no SDK.

import pagarme

pagarme.authentication_key("SUA_API_KEY")

installments = pagarme.transaction.calculate_installments_amount({
    "amount": "10000",
    "free_installments": "1",
    "interest_rate": "13",
    "max_installments": "3"
})

print(installments)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

{
    "installments": {
        "1": {
            "installment": 1,
            "amount": 10000,
            "installment_amount": 10000
        },
        "2": {
            "installment": 2,
            "amount": 10598,
            "installment_amount": 5299
        },
        "3": {
            "installment": 3,
            "amount": 10897,
            "installment_amount": 3632
        }
    }
}

Suggest Edits

Testando pagamento de Boletos

Usado apenas em ambiente de Teste para simular o pagamento de um Boleto.

puthttps://api.pagar.me/1/transactions/transaction_id

Path Params

transaction_id

string

required

Id da transação

Body Params

status

string

Utilize o valor paid para simular o pagamento

Cadê o link do boleto?

Em teste o link "gerado" para a transação de boleto sempre será 'https://pagar.me', não sendo possível gerar um boleto real.

curl -X PUT https://api.pagar.me/1/transactions/1627871 -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY", 
    "status": "paid"
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

transaction = PagarMe::Transaction.find_by_id("1627871")
transaction.status = 'paid'
transaction.save

<?php
    require("pagarme-php/Pagarme.php");

    Pagarme::setApiKey("SUA_API_KEY");

    $transaction = PagarMe_Transaction::findById("1627871");
    $transaction->setStatus('paid');
    $transaction->save();

PagarMeService.DefaultApiKey = "ak_test_grXijQ4GicOa2BLGZrDRTR5qNQxJW0";
var transaction = PagarMeService.GetDefaultService().Transactions.Find("1627871");
transaction.Status = TransactionStatus.Paid;
transaction.Save();

const pagarme = require('pagarme')

pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => {
    client.transactions.find({ id: '2193246' })
      .then(transaction => {
        client.transactions.update({
          id: transaction.id,
          status: 'paid',
        })
      })
  })

<?php
	require __DIR__.'/vendor/autoload.php';

$pagarMe = new \PagarMe\Sdk\PagarMe('SUA_API_KEY');
$transaction = $pagarMe->transaction()->payTransaction(1627871);

Oops, ainda não temos essa feature no SDK.

import pagarme

pagarme.authentication_key("SUA_API_KEY")

transaction_data = {
    "amount": "1000",
    "payment_method": "boleto",
    "customer":{
        "name": "Daario Naharis",
        "email": "daario.naharis@gmail.com",
        "document_number": "48517615387"
    }
}

transaction = pagarme.transaction.create(transaction_data)

pay_boleto = pagarme.transaction.pay_boleto(
    transaction['id'],
    {"status": "paid"}
)

print(pay_boleto)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

{
   “object”:“transaction”,
   “status”:“paid”,
   “refuse_reason”:null,
   “status_reason”:“acquirer”,
   “acquirer_response_code”:null,
   “acquirer_name”:“pagarme”,
   “acquirer_id”:“59d6af21fdc71686302b2464",
   “authorization_code”:null,
   “soft_descriptor”:null,
   “tid”:2190051,
   “nsu”:2190051,
   “date_created”:   “2017-10-05T22:22:11.949   Z”,
   “date_updated”:   “2017-10-05T22:59:52.287   Z”,
   “amount”:290,
   “authorized_amount”:290,
   “paid_amount”:0,
   “refunded_amount”:0,
   “installments”:1,
   “id”:2190051,
   “cost”:380,
   “card_holder_name”:null,
   “card_last_digits”:null,
   “card_first_digits”:null,
   “card_brand”:null,
   “card_pin_mode”: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”:   “2017-10-12T03:00:00.000   Z”,
   “referer”:“api_key”,
   “ip”:“179.191.110.178”,
   “subscription_id”:null,
   “phone”:null,
   “address”:null,
   “customer”:{
      “object”:“customer”,
      “id”:333567,
      “external_id”:null,
      “type”:“individual”,
      “country”:“br”,
      “document_number”:null,
      “document_type”:“cpf”,
      “name”:“Morpheus Fishburne”,
      “email”:null,
      “phone_numbers”:null,
      “born_at”:null,
      “birthday”:null,
      “gender”:null,
      “date_created”:      “2017-10-05T22:22:11.913      Z”,
      “documents”:[
         {
            “object”:“document”,
            “id”:“doc_cj8f11s5x00gsl26ea2kcgmy1",
            “type”:“cpf”,
            “number”:“00000000000"
         }
      ]
   },
   “billing”:null,
   “shipping”:null,
   “items”:[

   ],
   “card”:null,
   “split_rules”:null,
   “metadata”:{

   },
   “antifraud_metadata”:{

   },
   “reference_key”:null,
   “device”:null
}

Suggest Edits

Gerando uma nova chave para encriptação do card_hash

Caso você queira/precise criar o card_hash manualmente, essa rota deverá ser utilizada para obtenção de uma chave pública de encriptação dos dados do cartão de seu cliente.

gethttps://api.pagar.me/1/transactions/card_hash_key

curl -X GET https://api.pagar.me/1/transactions/card_hash_key -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY"
}'

import pagarme

pagarme.authentication_key("SUA_API_KEY")

card_hash_key = pagarme.transaction.generate_card_hash_key()

print(card_hash_key)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

{
  "date_created": "2017-06-29T18:27:35.266Z",
  "id": 652477,
  "ip": "000.000.000.000",
  "public_key": "-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----\n"
}

Suggest Edits

Gerando card_hash manualmente

O card_hash representa uma versão criptografada das dados holder_name, expiration date, cvv, e number de um cartão. Nesta seção você vai aprender mais sobre como o hash é criado, e quais algoritmos utilizar.

Utilizando a Pagar.me JS

const pagarme = require('pagarme')

pagarme.client.connect({ encryption_key: 'SUA_ENCRYPTION_KEY' })
  .then(client => {
    return client.security.encrypt({
      card_number: '4111111111111111',
      card_holder_name: 'abc',
      card_expiration_date: '1225',
      card_cvv: '123',
    })
  })
  .then(card_hash => console.log(card_hash))

A maneira mais fácil de gerar um card_hash é utilizando a nossa biblioteca de Javascript Pagar.me JS. O método acima funciona tanto com api quanto com encryption key. Como essa operação normalmente é feita no cliente, utilize a encryption key para proteger a sua chave de api.

Passo a passo

O card_hash consiste de uma string gerada a partir dos dados do cartão de crédito. Essa string é encriptada por RSA usando uma chave pública que deve ser requisitada ao servidor a cada novo card_hash gerado. Essa chave é invalidada assim que o servidor lê as informações contidas no card_hash, e por isso só pode ser utilizada uma única vez. Ela também é temporária, expirando 5 minutos após ter sido gerada. As bibliotecas do Pagar.me sempre utilizam o card_hash para enviar os dados para o servidor, o que aumenta consideravelmente a segurança da transação.

1. Gerando uma nova chave para encriptação

Essa rota deverá ser utilizada para obtenção de uma chave pública de encriptação dos dados do cartão de seu cliente:

Shell

curl -X GET https://api.pagar.me/1/transactions/card_hash_key -H 'content-type: application/json' -d '{
    "encryption_key": "SUA_ENCRYPTION_KEY"
}'

A resposta terá o formato:

JSON

{
  "date_created": "2017-06-29T18:27:35.266Z",
  "id": 652477,
  "ip": "000.000.000.000",
  "public_key": "-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----\n"
}

Sendo:

Propriedade

Descrição

id
Number

id retornado e que será utilizado para compor o card_hash, logo, é importante que você o reserve.

public_key
String

Chave pública utilizada para criptografar os dados do cartão.

ip
String

IP de onde a request foi originada.

2. Encriptando os dados do cartão de crédito

Agora você vai ter que criar uma QueryString com valores URLEncoded para os parâmetros do cartão de crédito. Vamos pegar os seguintes dados abaixo como exemplo:

card_number = 4901720080344448
card_holder_name = "Aardvark Silva"
card_expiration_date = 1213
card_cvv = 314

A querystring ficará composta na seguinte forma:

querystring data

card_number=4901720080344448&card_holder_name=AardvarK%20Silva&card_expiration_date=1213&card_cvv=314

Agora você vai fazer uma criptografia pública com RSA e o padding PKCS1Padding usando a public_key que você recebeu na request passando a QueryString construída.

Após criptografar esses dados você deve converter o resultado para base64. Como resultado você terá:

hash criado a partir de RSA e PKCS1Padding

FFtwikzg/FC1mH7XLFU5fjPAzDsP0ogeAQh3qXRpHzkIrgDz64lITBUGwio67zm2CQXwbKRjGdRi5J1xFNpQLWnxQsUJAQELcTSGaGtF6RGSu6sq1stp8OLRSNG7wp+xGe8poqxw4S1gOL5JYO7XZp/Uz7rTpKXh3IcRshmX36hh66J6+7l5j0803cGIfMZu3T7nbMjQYIf+yLi8r0O6vL9DQPmqSZ9FBerqFGxWHrxScneaaMVzMpNX/5eneqveVBt88RccytyJG5+HYRHcRyKIbLfmX48L/C22HJeAm3PyzehGHdOmDcsxPtVB+Fgq7SDuB4tHWBT8j6wihOO7ww==

Agora com o id vindo da request inicial, e os dados criptografados convertidos para base64, seu card_hash deverá ser formatado da seguinte maneira:

card_hash = id + "_" + encrypted_string_base64, com o resultado na seguinte forma:

card_hash - formato final

111111_FFtwikzg/FC1mH7XLFU5fjPAzDsP0ogeAQh3qXRpHzkIrgDz64lITBUGwio67zm2CQXwbKRjGdRi5J1xFNpQLWnxQsUJAQELcTSGaGtF6RGSu6sq1stp8OLRSNG7wp+xGe8poqxw4S1gOL5JYO7XZp/Uz7rTpKXh3IcRshmX36hh66J6+7l5j0803cGIfMZu3T7nbMjQYIf+yLi8r0O6vL9DQPmqSZ9FBerqFGxWHrxScneaaMVzMpNX/5eneqveVBt88RccytyJG5+HYRHcRyKIbLfmX48L/C22HJeAm3PyzehGHdOmDcsxPtVB+Fgq7SDuB4tHWBT8j6wihOO7ww==

Por que preciso do card_hash?

Partindo da definição do card_hash: 'uma string gerada a partir dos dados de cartão', a principal função do card_hash é criar uma forma de transmissão segura para dados tão sensíveis quanto o que estamos tratando. Ou seja, sempre que as informações de cobrança do cartão precisarem trafegar entre o client-side e seus servidores, indicamos a utilização de card_hash, para uma camada a mais de segurança.

Suggest Edits

Retornando estornos

Retorna os dados de todos os estornos realizados pela sua companhia.

gethttps://api.pagar.me/1/refunds

Query Params

transaction_id

string

Filtro pelo ID da transação

date_created

date-time

Filtro pela data de criação do estorno

date_updated

date-time

Filtro pela data de atualização do estorno

Estornos

É importante notar que serão retornados apenas os dados referentes a estornos criados à partir de 08/05/2017.

curl -X GET https://api.pagar.me/1/refunds -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY"
}'

import pagarme

pagarme.authentication_key('SUA_API_KEY')

refunds = pagarme.refund.refunds()

print (refunds)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

[
  {
    "object": "refund",
    "id": "rf_cj5yddfhl2f8ujx3tp68ig835",
    "amount": 1000,
    "type": "credit_card",
    "status": "refunded",
    "charge_fee_recipient_id": null,
    "bank_account_id": null,
    "transaction_id": "1793531",
    "date_created": "2017-08-04 21:15:41.097+00",
    "metadata": {
      "idProduto": "13933139"
    }
  },
  {
    "object": "refund",
    "id": "rf_cj5yd3hx608m0km3s550mbbqf",
    "amount": 1390,
    "type": "credit_card",
    "status": "refunded",
    "charge_fee_recipient_id": null,
    "bank_account_id": null,
    "transaction_id": "1793468",
    "date_created": "2017-08-04 21:02:28.71+00",
    "metadata": {
      "idProduto": "13933140"
    }
  }
]

Suggest Edits

Objeto de resposta

Ao buscar os estornos realizados pela sua companhia, as seguintes informações compõem o objeto retornado:

Propriedade

Descrição

object
String

Nome do tipo do objeto criado/modificado.
Valor retornado: refund

id
String

Número identificador do estorno.

amount
Int

Valor, em centavos, do estorno.
Exemplo: R$100,00 = 10000

type
String

Tipo de pagamento da transação estornada.
Valores possíveis: credit_card, debit_card, boleto.

status
String

Representa o estado do estorno.
Valores possíveis: refunded, pending_refund.

charge_fee_recipient_id
String

Número identificador do recebedor responsável pela taxa de processamento.

bank_account_id
Int

Número identificador da conta bancária de destino do estorno.

transaction_id
Int

Número identificador da transação estornada.

date_created
Date

Data de criação do estorno no formato ISODate

metadata
JSON

Objeto com dados adicionais informados na criação do estorno.

Suggest Edits

Criando um cartão

Você pode armazenar os dados do cartão do seu cliente através da rota /cards, assim você poderá usar o id do objeto gerado para realizar futuras transações, no lugar do card_hash.

posthttps://api.pagar.me/1/cards

Body Params

card_number

string

required

Número do cartão

card_expiration_date

string

required

Data de expiração do cartão

card_cvv

string

required

Código de segurança do cartão

card_holder_name

string

required

Nome no cartão do portador

customer_id

string

Informações do cliente do card a ser gerado

card_hash

string

required

Dados criptografados do cartão

One Click Buy

Essa é a melhor forma de implementar One Click Buy no seu site. Com o card_id em nosso servidor, o seu cliente não precisará digitar os dados do cartão novamente e conseguirá comprar com apenas um clique. Sensacional né?

curl -X  POST https://api.pagar.me/1/cards -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY", 
    "card_expiration_date": "1122", 
    "card_number": "4018720572598048",
    "card_cvv": "123", 
    "card_holder_name": "Aardvark Silva"
}'

require 'pagarme'

PagarMe.api_key = "ak_test_grXijQ4GicOa2BLGZrDRTR5qNQxJW0"


card = PagarMe::Card.new({
	:card_number => '4018720572598048',
  :card_holder_name => 'Aardvark Silva',
	:card_expiration_month => '11',
	:card_expiration_year => '22',
	:card_cvv => '123'
})

card.create

<?php
    require("pagarme-php/Pagarme.php");

    Pagarme::setApiKey("ak_test_grXijQ4GicOa2BLGZrDRTR5qNQxJW0");

	$card = new PagarMe_Card(array(
		"card_number" => "4018720572598048",
		"card_holder_name" => "Aardvark Silva",
		"card_expiration_month" => 11,
		"card_expiration_year" => 22,
		"card_cvv" => "123",
	));

	$card->create();

PagarMeService.DefaultApiKey = "SUA_API_KEY";
PagarMeService.DefaultEncryptionKey = "SUA_ENCRYPTION_KEY";

Card card = new Card();
card.Number = "4018720572598048";
card.HolderName = "Aardvark Silva";
card.ExpirationDate = "1122";
card.Cvv = "123";

card.Save();

import java.util.Collection;

import me.pagar.model.Card;
import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;

PagarMe.init("SUA_API_KEY");

Card card = new Card();
card.setNumber("4018720572598048");
card.setHolderName("Aardvark Silva");
card.setExpiresAt("1122");
card.setCvv(123);
card.save();

<?php
	require __DIR__.'/vendor/autoload.php';
	$pagarMe = new \PagarMe\Sdk\PagarMe('SUA_API_KEY');

	//Create with card datas
  $cardNumber = '4018720572598048';
  $cardHolderName = 'Aardvark Silva';
  $cardExpirationDate = '1122';
  $card = $pagarMe->card()->create(
    $cardNumber,
    $cardHolderName,
    $cardExpirationDate
  );

  //Create with card_hash
  $card = $pagarMe->card()->createFromHash('card_hash');

const pagarme = require('pagarme')

pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.cards.create({
    card_number: '4018720572598048',
    card_holder_name: 'Aardvark Silva',
    card_expiration_date: '1122',
    card_cvv: '123',
  }))
  .then(card => console.log(card.id))

import pagarme

pagarme.authentication_key('SUA_API_KEY')

card_data = {
    "card_expiration_date": "1122",
    "card_number": "4018720572598048",
    "card_cvv": "123",
    "card_holder_name": "Cersei Lannister"
}

print (pagarme.card.create(card_data))

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

{
  "object": "card",
  "id": "card_cj428xxsx01dt3f6dvre6belx",
  "date_created": "2017-06-18T05:03:19.907Z",
  "date_updated": "2017-06-18T05:03:20.318Z",
  "brand": "visa",
  "holder_name": "Aardvark Silva",
  "first_digits": "401872",
  "last_digits": "8048",
  "country": "RU",
  "fingerprint": "TaApkY+9emV9",
  "customer": null,
  "valid": true,
  "expiration_date": "1122"
}

Suggest Edits

Objeto cartão

Sempre que você faz uma requisição através da nossa API, nós guardamos as informações do portador do cartão, para que, futuramente, você possa utilizá-las em novas cobranças, ou até mesmo implementar features como one-click-buy.

Propriedade

Descrição

object
String

Nome do tipo do objeto criado/modificado.
Valor retornado: card

id
String

Identificador do cartão

date_created
String

Data de criação do objeto card

date_updated
String

Data de atualização do objeto card

brand
String

Bandeira do cartão

holder_name
String

Nome do portador do cartão

first_digits
String

6 primeiros dígitos do cartão

last_digits
String

4 últimos dígitos do cartão

fingerprint
String

Hash que permite comparar dois cartões através de seus fingerprints para saber se são o mesmo.

customer
Object

Objeto com dados do comprador

valid
Boolean

Propriedade para verificar a validade do cartão, ou seja, caso true, é possível cobrar o cartão em condições normais, para false, não pode ser utilizado.

expiration_date
String

Data de expiração do cartão.

JSON

  {
    "object": "card",
    "id": "card_cj41mpuhc01bb3f6d8exeo072",
    "date_created": "2017-06-17T18:41:10.801Z",
    "date_updated": "2017-06-17T18:41:11.257Z",
    "brand": "visa",
    "holder_name": "Aardvark da Silva",
    "first_digits": "455636",
    "last_digits": "2122",
    "country": "AR",
    "fingerprint": "SK+CuBxPYsE7",
    "customer": null,
    "valid": true,
    "expiration_date": "1220"
  }

Suggest Edits

Cobrança de R$1,23

Essa cobrança é realizada para validar o cartão que pode vir a ser utilizado na criação de uma transação (objeto transaction) ou de uma assinatura (subscription). Para isso, a API Pagar.me envia uma requisição ao banco emissor pedindo autorização de reserva no valor de R$1,23 e, caso seja feita com sucesso, cria um novo cartão em nossa base marcando como válido. Isso retorna o seguinte objeto:

JSON

{
  "object": "card",
  "id": "card_cj428xxsx01dt3f6dvre6belx",
  "date_created": "2017-06-18T05:03:19.907Z",
  "date_updated": "2017-06-18T05:03:20.318Z",
  "brand": "visa",
  "holder_name": "Aardvark Silva",
  "first_digits": "401872",
  "last_digits": "8048",
  "country": "RU",
  "fingerprint": "TaApkY+9emV9",
  "customer": null,
  "valid": true,
  "expiration_date": "1122"
}

Em que o id card_ci6y37hc00030a416wrxsmzyi pode ser reutilizado para futuras compras.

É importante notar que o valor de R$1,23 é estornado para o portador do cartão no exato momento após a validação dos dados.

Suggest Edits

Retornando cartões

Use a rota /cards/ para retornar todos os cartões salvos

gethttps://api.pagar.me/1/cards

Query Params

created_at

date

Filtro pela data de criação

brand

string

Filtro pela bandeira do cartão. Pode ser: mastercard, visa, elo, amex, discover, aura, jcb, hipercard

holder_name

string

Filtro pelo nome do detentor do cartão

first_digits

string

Filtro pelos 6 primeiros dígitos do cartão

last_digits

string

Filtro pelos 4 últimos dígitos do cartão

customer_id

string

Filtro pelo id do customer atrelado ao cartão

valid

boolean

Filtro pela validade do cartão

country

string

Filtro pelo país de origem do cartão no formato ISO 3166-1 alpha-2

expiration_date

string

Filtro pela data de validade do cartão no formato MMYY

fingerprint

string

Filtros

Todos os filtros mencionados podem ser usados para buscas em ranges usando os prefixos:

Prefixo	Significado
<	menor que
>	maior que
<=	menor ou igual a
>=	maior ou igual a

Por exemplo, para buscar em um range de date_created:

curl -X GET https://api.pagar.me/1/cards \
-d 'api_key=ak_test_grXijQ4GicOa2BLGZrDRTR5qNQxJW0'
-d 'created_at=>=1483236000000'
-d 'created_at=<=1484689847590'

Para campos que sejam strings, a comparação é lexicográfica, letras maiúsculas sendo 'maiores' que minúsculas.

Filtros de data

É importante notar que a filtragem por data utiliza unix timestamp para representá-la. Para gerar o timestamp de uma data, é possível utilizar o console do Google Chrome e utilizar o seguinte código em Javascript :
new Date().getTime()
que retornará algo no formato:
1484689847590

curl -X GET 'https://api.pagar.me/1/cards' -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY",
    "count": "3"
}'

PagarMeService.DefaultApiKey = "ak_test_grXijQ4GicOa2BLGZrDRTR5qNQxJW0";

var cards = PagarMeService.GetDefaultService().Cards.FindAll(new Card());

const pagarme = require('pagarme')

pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.cards.all())
  .then(cards => console.log(cards))

<?php
    require("pagarme-php/Pagarme.php");

    Pagarme::setApiKey("SUA_API_KEY");

    $transaction = PagarMe_Card::all(3, 3)

Oops, ainda não temos essa feature no SDK.

Oops, ainda não temos essa feature no SDK.

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

transactions = PagarMe::Card.all

import pagarme

pagarme.authentication_key('SUA_API_KEY')

cards = pagarme.card.find_all()

print (cards)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

[
  {
    "object": "card",
    "id": "card_cj42a0tku01mmc16eiovsbuxl",
    "date_created": "2017-06-18T05:33:34.016Z",
    "date_updated": "2017-06-18T05:33:34.434Z",
    "brand": "visa",
    "holder_name": "Susan Alexis",
    "first_digits": "424242",
    "last_digits": "4242",
    "country": "US",
    "fingerprint": "jxWu6KT6pjNc",
    "customer": null,
    "valid": true,
    "expiration_date": "1123"
  },
  {
    "object": "card",
    "id": "card_cj429yy5v01o8cd6eqgslolec",
    "date_created": "2017-06-18T05:32:06.646Z",
    "date_updated": "2017-06-18T05:33:03.995Z",
    "brand": "visa",
    "holder_name": "Chuck Silva",
    "first_digits": "424242",
    "last_digits": "4242",
    "country": "US",
    "fingerprint": "Ntjtk/Hk/QnY",
    "customer": null,
    "valid": true,
    "expiration_date": "1122"
  },
  {
    "object": "card",
    "id": "card_cj428xxsx01dt3f6dvre6belx",
    "date_created": "2017-06-18T05:03:19.907Z",
    "date_updated": "2017-06-18T05:03:20.318Z",
    "brand": "visa",
    "holder_name": "Aardvark Silva",
    "first_digits": "401872",
    "last_digits": "8048",
    "country": "RU",
    "fingerprint": "TaApkY+9emV9",
    "customer": null,
    "valid": true,
    "expiration_date": "1122"
  }
]

Suggest Edits

Retornando um cartão salvo

Use a rota /cards/:id para retornar os dados de um cartão previamente criado.

gethttps://api.pagar.me/1/cards/card_id

Path Params

card_id

string

required

Id do cartão que deseja consultar os dados

curl -X  GET https://api.pagar.me/1/cards/card_cj428xxsx01dt3f6dvre6belx -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY"
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

card = PagarMe::Card.find_by_id("card_cj428xxsx01dt3f6dvre6belx")

<?php
    require("pagarme-php/Pagarme.php");

    Pagarme::setApiKey("SUA_API_KEY");

    $card = PagarMe_Card::findById("card_cj428xxsx01dt3f6dvre6belx");

PagarMeService.DefaultApiKey = "SUA_API_KEY";

var card = PagarMeService.GetDefaultService().Cards.Find("card_cj428xxsx01dt3f6dvre6belx");

import me.pagar.model.Card;
import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;

PagarMe.init("SUA_API_KEY");

Card cards = new Card().find("card_cj428xxsx01dt3f6dvre6belx");

<?php
	require __DIR__.'/vendor/autoload.php';

	$pagarMe = new \PagarMe\Sdk\PagarMe('SUA_API_KEY');
	$cardId = 'card_cj428xxsx01dt3f6dvre6belx';
	$cards = $pagarMe->card()->get(cardId);

const pagarme = require('pagarme')

pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.cards.find({ id: 'card_cj428xxsx01dt3f6dvre6belx' }))
  .then(card => console.log(card))

import pagarme

pagarme.authentication_key('SUA_API_KEY')

card = pagarme.card.find_by({"id": "card_id"})

print (card)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

{
  "object": "card",
  "id": "card_cj428xxsx01dt3f6dvre6belx",
  "date_created": "2017-06-18T05:03:19.907Z",
  "date_updated": "2017-06-18T05:03:20.318Z",
  "brand": "visa",
  "holder_name": "Aardvark Silva",
  "first_digits": "401872",
  "last_digits": "8048",
  "country": "RU",
  "fingerprint": "TaApkY+9emV9",
  "customer": null,
  "valid": true,
  "expiration_date": "1122"
}

Suggest Edits

Criando Planos

posthttps://api.pagar.me/1/plans

Body Params

amount

int32

required

Valor que será cobrado recorrentemente (em centavos). Ex: R$49,90 = 4990

days

string

required

Prazo, em dias, para cobrança das parcelas

name

string

required

Nome do plano

trial_days

int32

default: 0 Dias para teste gratuito do produto. Valor começará a ser cobrado no dia trial_days + 1

payment_methods

string

Meios de pagamentos aceitos. Pode ser boleto, cartão de crédito ou ambos

color

string

Armazena o valor de uma cor para o plano

charges

string

Número de cobranças que poderão ser feitas nesse plano. Ex: Plano cobrado 1x por ano, válido por no máximo 3 anos. Nesse caso, nossos parâmetros serão: days = 365, installments = 1, charges=2 (cartão de crédito) ou charges=3 (boleto). OBS: No caso de cartão de crédito, a cobrança feita na ativação da assinatura não é considerada. OBS: null irá cobrar o usuário indefinidamente, ou até o plano ser cancelado

installments

string

Número de parcelas entre cada cobrança (charges). Ex: Plano anual, válido por 2 anos, sendo que cada transação será dividida em 12 vezes. Nesse caso, nossos parâmetros serão: days = 365, installments = 12, charges=2 (cartão de crédito) ou charges=3 (boleto). OBS: Boleto sempre terá installments = 1

invoice_reminder

int32

Define em até quantos dias antes o cliente será avisado sobre o vencimento do boleto.

curl -X POST https://api.pagar.me/1/plans -H 'content-type: application/json' -d '{
    "amount": "15000", 
    "api_key": "SUA_API_KEY", 
    "days": "30", 
    "name": "The Pro Plan - Platinum  - Best Ever"
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

plan = PagarMe::Plan.new({
    :name => "The Pro Plan - Platinum  - Best Ever",
    :days => 30,
    :amount => 15000
}

plan.create

<?php
    require("pagarme-php/Pagarme.php");

    Pagarme::setApiKey("SUA_API_KEY");

    $plan = new PagarMe_Plan(array(
        "amount" => 15000,
        "days" => 30,
        "name" => "The Pro Plan - Platinum  - Best Ever"
    ));

    $plan->create();

PagarMeService.DefaultApiKey = "SUA_API_KEY";

Plan plan = new Plan
{
  	Name = "The Pro Plan - Platinum  - Best Ever",
		Amount = 15000,
		Days = 30
};

plan.Save();

import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Plan;

PagarMe.init("SUA_API_KEY");

Plan plan = new Plan();
Integer amount = 15000;
Integer days = 30;
String name = "The Pro Plan - Platinum  - Best Ever";
plan.setCreationParameters(amount, days, name);
plan.save();

<?php
require __DIR__.'/vendor/autoload.php';

$pagarMe = new \PagarMe\Sdk\PagarMe('SUA_API_KEY');

$amount = 15000;
$days = 30;
$name = 'The Pro Plan - Platinum  - Best Ever';
$trialDays = 0;
$paymentsMethods = ['credit_card', 'boleto'];
$charges = null;
$installments = 1;
$plan = $pagarMe->plan()->create(
		$amount,
		$days,
		$name,
		$trialDays,
		$paymentsMethods,
		$charges,
		$installments
		);

const pagarme = require('pagarme')
  
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.plans.create({
      amount: 15000,
      days: 30,
      name: 'The Pro Plan - Platinum  - Best Ever',
      payment_methods: ['boleto', 'credit_card']
  }))
  .then(plan => console.log(plan))

import pagarme

pagarme.authentication_key('SUA_API_KEY')

plan_data = {
    "amount": "15000",
    "days": "30",
    "name": "Curso com o Alto Pardal"
}

plan = pagarme.plan.create(plan_data)

print (plan)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

{
  "object": "plan",
  "id": 164526,
  "amount": 15000,
  "days": 30,
  "name": "The Pro Plan - Platinum  - Best Ever",
  "trial_days": 0,
  "date_created": "2017-06-09T22:43:08.048Z",
  "payment_methods": [
    "boleto",
    "credit_card"
  ],
  "color": null,
  "charges": null,
  "installments": 1,
  "invoice_reminder": null
}

Suggest Edits

Objeto Plano

Representa uma configuração de recorrência a qual um cliente consegue assinar.
É a entidade que define o preço, nome e periodicidade da recorrência

Propriedade

Descrição

object
String

Nome do tipo do objeto criado/modificado.
Valor retornado: plan

id
Int

Número identificador do plano

amount
Int

Preço do plano, em centavos

days
Int

Período de dias entre uma cobrança e outra de uma assinatura atrelada. Ex: Para um plano mensal, o valor de days = 30.

name
String

Nome do plano

trial_days
Int

Dias que o usuário poderá testar o serviço gratuitamente

date_created
String

Data da criação do plano ISODate

payment_methods
String array

Array de Strings contendo os possíveis métodos de pagamento deste plano.
Valores possíveis: credit_card, boleto

charges
Int

Número de cobranças que devem ser feitas em uma assinatura.
OBS: No caso de pagamento com cartão de crédito, esse valor não inclui a cobrança feita na criação da assinatura.
Ex: Plano anual com no máximo 3 cobranças, days = 365 e charges = 2 (cartão de crédito) ou charges = 3 (boleto)
OBS²: Caso queira cobrar o plano indefinidamente, não é preciso passar este campo na criação do plano.

installments
Int

Informa em quantas vezes o pagamento será parcelado para cada cobrança.

invoice_reminder
Int

Define em até quantos dias antes o cliente será avisado sobre o vencimento do boleto.

Suggest Edits

Retornando planos

Retorna todos os planos previamente criados levando em consideração os filtros e a paginação

gethttps://api.pagar.me/1/plans

Query Params

count

string

Retorna n objetos de plano

page

string

Útil para implementação de uma paginação de resultados

string

Filtro de id

amount

string

Filtro de valor do plano

days

string

Filtro de 'days' do plano

name

string

Filtro de nome do plano

trial_days

string

Filtro de quantidade de dias de trial do plano

date_created

date-time

Filtro da data de criação do plano

created_at

date-time

Alias de date_created

Filtros

Todos os filtros mencionados podem ser usados para buscas em ranges usando os prefixos:

Prefixo	Significado
<	menor que
>	maior que
<=	menor ou igual a
>=	maior ou igual a

Por exemplo, para buscar em um range de date_created:

curl -X GET https://api.pagar.me/1/plans \
-d 'api_key=ak_test_grXijQ4GicOa2BLGZrDRTR5qNQxJW0'
-d 'date_created=>=1483236000000'
-d 'date_created=<=1484689847590'

Para campos que sejam strings, a comparação é lexicográfica, letras maiúsculas sendo 'maiores' que minúsculas.

Filtros de data

É importante notar que a filtragem por data utiliza unixTimeStamp para representá-la. Para gerar o unixTimeStamp de uma data, é possível utilizar o console do Google Chrome e utilizar o seguinte código em Javascript : new Date("2017-12-25T02:00:00.000Z").getTime() que retornará 1514167200000

curl -X GET https://api.pagar.me/1/plans -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY", 
    "count": "10", 
    "page": "1"
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

plans = PagarMe::Plan.all(1, 10)

<?php
    require("pagarme-php/Pagarme.php");

    Pagarme::setApiKey("SUA_API_KEY");

    $plans = PagarMe_Plan::all(1, 10);

PagarMeService.DefaultApiKey = "SUA_API_KEY";

var plans = PagarMeService.GetDefaultService().Plans.FindAll(new Plan());

import java.util.Collection;

import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Plan;

PagarMe.init("SUA_API_KEY");

Collection<Plan> plans = new Plan().findCollection(10, 1);

<?php
	require __DIR__.'/vendor/autoload.php';

	$pagarMe = new \PagarMe\Sdk\PagarMe('SUA_API_KEY');

	$plans = $pagarMe->plan()->getList(1, 10);

const pagarme = require('pagarme')
  
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.plans.all({ count: 10, page: 1 }))
  .then(plans => console.log(plans))

import pagarme

pagarme.authentication_key('SUA_API_KEY')

print(pagarme.plan.find_all())

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

[
  {
    "object": "plan",
    "id": 164526,
    "amount": 15000,
    "days": 30,
    "name": "The Pro Plan - Platinum  - Best Ever",
    "trial_days": 0,
    "date_created": "2017-06-09T22:43:08.048Z",
    "payment_methods": [
      "boleto",
      "credit_card"
    ],
    "color": null,
    "charges": null,
    "installments": 1,
    "invoice_reminder": null
  },
  {
    "object": "plan",
    "id": 164252,
    "amount": 1000000,
    "days": 30,
    "name": "The Pro Plan - Platinum Boleto",
    "trial_days": 0,
    "date_created": "2017-06-09T12:34:50.211Z",
    "payment_methods": [
      "boleto"
    ],
    "color": null,
    "charges": null,
    "installments": 1,
    "invoice_reminder": null
  },
  {
    "object": "plan",
    "id": 163871,
    "amount": 500000,
    "days": 30,
    "name": "The Pro Plan - Susan",
    "trial_days": 0,
    "date_created": "2017-06-07T14:00:23.871Z",
    "payment_methods": [
      "credit_card"
    ],
    "color": null,
    "charges": null,
    "installments": 12,
    "invoice_reminder": null
  }
]

Suggest Edits

Retornando um plano

Retorna um plano previamente criado.

gethttps://api.pagar.me/1/plans/plan_id

Path Params

plan_id

string

required

id de identificação do plano previamente criado

curl -X GET https://api.pagar.me/1/plans/164526 -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY"
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

plan = PagarMe::Plan.find_by_id("164526")

<?php
    require("pagarme-php/Pagarme.php");

    Pagarme::setApiKey("SUA_API_KEY");

    $plan = PagarMe_Plan::findById("164526");

PagarMeService.DefaultApiKey = "SUA_API_KEY";

var plan = PagarMeService.GetDefaultService().Plans.Find("164526");

import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Plan;

PagarMe.init("SUA_API_KEY");
Plan plan = new Plan().find("164526");

<?php
	require __DIR__.'/vendor/autoload.php';

	$pagarMe = new \PagarMe\Sdk\PagarMe('SUA_API_KEY');

	$plan = $pagarMe->plan()->get(164526);

const pagarme = require('pagarme')
  
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.plans.find({ id: 164526 }))
  .then(plan => console.log(plan))

import pagarme

pagarme.authentication_key('SUA_API_KEY')

print(pagarme.plan.find_by({"id":"PLAN_ID"}))

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

{
  "object": "plan",
  "id": 164526,
  "amount": 15000,
  "days": 30,
  "name": "The Pro Plan - Platinum  - Best Ever",
  "trial_days": 0,
  "date_created": "2017-06-09T22:43:08.048Z",
  "payment_methods": [
    "boleto",
    "credit_card"
  ],
  "color": null,
  "charges": null,
  "installments": 1,
  "invoice_reminder": null
}

Suggest Edits

Atualizando um plano

Atualiza um plano previamente criado

puthttps://api.pagar.me/1/plans/plan_id

Path Params

plan_id

string

required

id de identificação do plano previamente criado

Body Params

name

string

Nome do plano

trial_days

string

Dias para testar o produto/serviço gratuitamente

invoice_reminder

int32

Define em até quantos dias antes o cliente será avisado sobre o vencimento do boleto.

Possíveis alterações no plano

Não é possível alterar outros parâmetros além do nome, invoice_reminder e de trial_days do plano

curl -X  PUT https://api.pagar.me/1/plans/163871 -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY", 
    "name": "The Pro Plan - Susan", 
    "trial_days": "7"
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

plan = PagarMe::Plan.find_by_id("163871")

plan.name = "The Pro Plan - Susan"
plan.trial_days = 7

plan.save

<?php
    require("pagarme-php/Pagarme.php");

    Pagarme::setApiKey("SUA_API_KEY");

    $plan = PagarMe_Plan::findById("163871");

    $plan->setName("The Pro Plan - Susan");
    $plan->setTrialDays("7");
		
		$plan->save();

PagarMeService.DefaultApiKey = "SUA_API_KEY";
var plan = PagarMeService.GetDefaultService().Plans.Find("163871");
plan.Name = "The Pro Plan - Susan";
plan.TrialDays = 7;
plan.Save();

import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Plan;

PagarMe.init("SUA_API_KEY");
Plan planF = new Plan();
planF.setName("The Pro Plan - John");
planF.setTrialDays(7500);
planF.setId("ID DO PLANO A SER ATUALIZADO");
planF.save();

<?php
	require __DIR__.'/vendor/autoload.php';

	$pagarMe = new \PagarMe\Sdk\PagarMe('SUA_API_KEY');

	$oldPlan = $pagarMe->plan()->get(163871);
	$oldPlan->setName('The Pro Plan - Susan');
  $oldPlan->setTrialDays('7'); 
	$newPlan = $pagarMe->plan()->update($oldPlan);

const pagarme = require('pagarme')
  
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.plans.update({
    id: 163871,
    name: 'The Pro Plan - Susan',
    trial_days: '7'
	}))
  .then(plan => console.log(plan))

import pagarme

pagarme.authentication_key('SUA_API_KEY')

print(pagarme.plan.update(
    "plan_id",
    {
        "name": "Esgrima com Syrio Forel",
        "trial_days": "7"
    })
)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

  {
    "object": "plan",
    "id": 163871,
    "amount": 500000,
    "days": 30,
    "name": "The Pro Plan - Susan",
    "trial_days": 7,
    "date_created": "2017-06-07T14:00:23.871Z",
    "payment_methods": [
      "credit_card"
    ],
    "color": null,
    "charges": 0,
    "installments": 12,
    "invoice_reminder": null
  }

Suggest Edits

Criando assinaturas

Para efetivamente cobrar seu cliente de forma recorrente, você deve criar uma assinatura atrelada a um plano, que então conterá os dados de cobrança.

A criação de uma subscription (assinatura) é parecida com a criação de uma transação. Se for uma assinatura paga com Cartão de crédito, é possível usar um card_id, card_hash ou todos os dados do cartão. Para pagamento por Boleto bancário, você precisa especificar apenas o payment_method.

posthttps://api.pagar.me/1/subscriptions

Body Params

plan_id

string

required

ID do plano a ser associado a uma assinatura

payment_method

string

Método de pagamento da assinatura. Aceita dois tipos: credit_card e boleto

card_hash

string

required

Dados encriptados do cartão do cliente. Você também pode usar o card_id ao invés do card_hash

card_number

string

required

Número do cartão, se for uma assinatura de cartão

card_cvv

string

required

CVV do cartão, se for uma assinatura paga com cartão

card_holder_name

string

required

Nome do detentor do cartão se for uma assinatura paga com cartão

card_expiration_date

string

required

Data de expiração do cartão, se for uma assinatura paga com cartão

card_id

string

required

ID do cartão a ser cobrado, se for uma assinatura paga com cartão

postback_url

string

URL para a qual nossa API irá enviar requisições informando alterações de status da assinatura em questão.

customer

object

customer.email

string

required

E-mail do cliente

customer.name

string

Nome completo ou razão social do cliente que está realizando a transação

customer.document_number

string

CPF ou CNPJ do cliente, sem separadores

customer.address

object

customer.address.street

string

logradouro (rua, avenida, etc) do cliente

customer.address.street_number

string

Número da residência/estabelecimento do cliente

customer.address.complementary

string

complemento do endereço do cliente

customer.address.neighborhood

string

bairro de localização do cliente

customer.address.zipcode

string

CEP do imóvel do cliente, sem separadores

customer.phone

object

customer.phone.ddd

string

DDD do telefone do cliente

customer.phone.number

string

número de telefone do cliente

customer.sex

string

sexo do cliente

customer.born_at

date

Data de nascimento do cliente. Ex: 11-02-1985

metadata

json

Você pode passar dados adicionais na criação da transação para facilitar uma futura análise de dados tanto em nossa dashboard, quanto por seus sistemas. Ex: metadata[ idProduto ]=13933139

Dados necessários para uma assinatura

Dados obrigatórios

O e-mail do cliente é uma informação obrigatória, uma vez que utilizamos ele para enviar e-mails de assinatura.

Antifraude

A primeira transação criada em uma assinatura passa por antifraude, logo, é obrigatório enviar todos os dados de customer.

Valores de uma assinatura

Dando descontos na assinatura

Só é possível dar descontos na assinatura através de troca para um plano mais barato, mas vale ressaltar que isso gera uma nova periodicidade. Mais em: Fluxo de cobrança.

Observações

ID do plano

Lembre-se de passar o ID de seu plano em todas as requests, para que não seja necessário recriar todas assinaturas que ficaram com plan_id = null.

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": {
        "email": "api@test.com"
    }, 
    "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 => 'boleto',
    :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 => {
        email: 'api@test.com'
})
subscription.plan = plan

subscription.create

<?php
    require("pagarme-php/Pagarme.php");

    Pagarme::setApiKey("SUA_API_KEY");

    $plan = PagarMe_Plan::findById("13850");

    $subscription = new PagarMe_Subscription(array(
        "plan" => $plan,
        "card_number" => "4901720080344448",
        "card_holder_name" => "Jose da Silva",
        "card_expiration_month" => 12,
        "card_expiration_year" => 15,
        "card_cvv" => "123",
        'customer' => array(
            'email' => 'api@test.com'
        )));

    $subscription->create();

?>

PagarMeService.DefaultApiKey = "SUA_API_KEY";

Subscription subscription = new Subscription
{
		PaymentMethod = PaymentMethod.CreditCard,
  	CardNumber = "4901720080344448",
		CardHolderName = "Jose da Silva",
		CardExpirationDate = "1215",
		CardCvv = "123"
};

Customer customer = new Customer
{
		Email = "api@test.com"  
};

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 = "aardvark.silva@pagar.me";
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();

<?php
require __DIR__.'/vendor/autoload.php';

date_default_timezone_set('America/Sao_Paulo');
$pagarMe = new \PagarMe\Sdk\PagarMe('SUA_API_KEY');

$planId = 136869;
$plan = $pagarMe->plan()->get($planId);

$cardId = 'card_cizri9czn00csfi6e1ygzw9vz';
$card = $pagarMe->card()->get($cardId);
$customer = new \PagarMe\Sdk\Customer\Customer(
		[
		'name' => 'John Dove',
		'email' => 'john@site.com',
		'document_number' => '09130141095',
		'address' => new \PagarMe\Sdk\Customer\Address([
			'street'        => 'rua teste',
			'street_number' => 42,
			'neighborhood'  => 'centro',
			'zipcode'       => '01227200',
			'complementary' => 'Apto 42',
			'city'          => 'São Paulo',
			'state'         => 'SP',
			'country'       => 'Brasil'
		]),
		'phone' => new \PagarMe\Sdk\Customer\Phone([
			'ddd'    => "15",
			'number' =>"987523421"
		]),
		'born_at' => '15021994',
		'sex' => 'M'
		]
		);

		$subscription = $pagarMe->subscription()->createCardSubscription(
				$plan,
				$card,
				$customer,
				'http://requestb.in/zyn5obzy',
				['idProduto' => 13933139]
				);
		var_dump($subscription);

const pagarme = require('pagarme')
  
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.subscriptions.create({
    plan_id: 1337,
    card_number: '4111111111111111',
    card_holder_name: 'abc',
    card_expiration_date: '1225',
    card_cvv: '123',
    customer: {
      email: 'someone@somewhere.com'
    }
	}))
  .then(subscription => console.log(subscription))

import pagarme

pagarme.authentication_key('SUA_API_KEY')

subscription = pagarme.subscription.create({
    "card_id": "card_cj6qvosem04w3nu6dm20nu8od",
    "customer":{
        "email":"jorah.mormont@gameofthrones.com",
        "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"
        }
    },
    "payment_method": "credit_card",
    "plan_id": "201836",
    "postback_url": "http://requestb.in/zyn5obzy"
})

print (subscription)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

{
    "object": "subscription",
    "plan": {
        "object": "plan",
        "id": 12783,
        "amount": 31000,
        "days": 30,
        "name": "Plano Ouro",
        "trial_days": 0,
        "date_created": "2015-03-03T16:56:32.000Z",
        "payment_methods": ["boleto", "credit_card"],
        "color": null,
        "charges": null,
        "installments": 1
    },
    "id": 16892,
    "current_transaction": {
        "object": "transaction",
        "status": "waiting_payment",
        "refuse_reason": null,
        "status_reason": "acquirer",
        "acquirer_response_code": null,
        "acquirer_name": "development",
        "authorization_code": null,
        "soft_descriptor": null,
        "tid": null,
        "nsu": null,
        "date_created": "2015-04-14T20:17:18.000Z",
        "date_updated": "2015-04-14T20:17:19.000Z",
        "amount": 31000,
        "installments": 1,
        "id": 194402,
        "cost": 0,
        "card_holder_name": null,
        "card_last_digits": null,
        "card_first_digits": null,
        "card_brand": null,
        "postback_url": null,
        "payment_method": "boleto",
        "antifraud_score": null,
        "boleto_url": "https://pagar.me",
        "boleto_barcode": "1234 5678",
        "boleto_expiration_date": "2015-04-21T20:17:18.000Z",
        "referer": "api_key",
        "ip": "179.185.132.108",
        "subscription_id": 16892,
        "metadata": {}
    },
    "postback_url": "http://requestb.in/zyn5obzy",
    "payment_method": "boleto",
    "current_period_start": null,
    "current_period_end": null,
    "charges": 0,
    "status": "unpaid",
    "date_created": "2015-04-14T20:17:19.000Z",
    "phone": null,
    "address": null,
    "customer": {
        "object": "customer",
        "document_number": null,
        "document_type": "cpf",
        "name": null,
        "email": "api@test.com",
        "born_at": null,
        "gender": null,
        "date_created": "2015-03-04T18:40:03.000Z",
        "id": 14437
    },
    "card": null,
    "metadata": null
}

Suggest Edits

Objeto Assinatura

Esse objeto contém os dados das assinaturas geradas pelo seu sistema, que são atreladas a um plano.

Propriedade

Descrição

objeto
String

Nome do tipo do objeto criado/modificado.
Valor retornado: subscription

plan
Object

Objeto com os dados do plano que a assinatura está associada

id
Integer

Número identificador da assinatura

current_transaction
Object

Objeto com os dados da última transação criada
para essa assinatura

postback_url
String

Endpoint de sua aplicação irá receber as notificações de mudança de status da assinatura.

payment_method
String

Método de pagamento associado a essa assinatura

current_period_start
ISODate

Início do período atual de cobrança da assinatura em ISODate

card_brand
String

Bandeira do cartão usado para criar a assinatura.

card_last_digits
String

4 últimos dígitos do cartão usado para criar a assinatura.

current_period_end
ISODate

Fim do período atual de cobrança da assinatura em ISODate

charges
Integer

Número de cobranças que foram efetuadas na assinatura, sem contar a cobrança inicial da assinatura no caso de cartão de crédito.

status
String

Possíveis estados da assinatura
Sendo: trialing, paid, pending_payment, unpaid, canceled, ended

date_created
ISODate

Data da criação do plano ISODate

phone
Object

Objeto com dados do telefone do cliente

address
Object

Objeto com dados do endereço do cliente

customer
Object

Objeto com dados do cliente

card
Object

Objeto com dados do cartão do cliente

metadata
Object

Objeto com dados adicionais atrelados à assinatura

settled_charges
Integer

Quantidade de parcelas não pagas, e negociadas.

JSON

{
  "object": "subscription",
  "plan": {
    "object": "plan",
    "id": 164526,
    "amount": 15000,
    "days": 30,
    "name": "The Pro Plan - Platinum  - Rocks",
    "trial_days": 0,
    "date_created": "2017-06-09T22:43:08.048Z",
    "payment_methods": [
      "boleto",
      "credit_card"
    ],
    "color": null,
    "charges": null,
    "installments": 1,
    "invoice_reminder": null
  },
  "id": 205840,
  "current_transaction": {
    "object": "transaction",
    "status": "paid",
    "refuse_reason": null,
    "status_reason": "acquirer",
    "acquirer_response_code": "0000",
    "acquirer_name": "pagarme",
    "acquirer_id": "56f9d019decf72cc70055d58",
    "authorization_code": "211852",
    "soft_descriptor": null,
    "tid": 1627876,
    "nsu": 1627876,
    "date_created": "2017-06-18T06:45:51.193Z",
    "date_updated": "2017-06-18T06:45:51.742Z",
    "amount": 15000,
    "authorized_amount": 15000,
    "paid_amount": 15000,
    "refunded_amount": 0,
    "installments": 1,
    "id": 1627876,
    "cost": 50,
    "card_holder_name": "Susan Alexis",
    "card_last_digits": "4242",
    "card_first_digits": "424242",
    "card_brand": "visa",
    "card_pin_mode": null,
    "postback_url": null,
    "payment_method": "credit_card",
    "capture_method": "ecommerce",
    "antifraud_score": null,
    "boleto_url": null,
    "boleto_barcode": null,
    "boleto_expiration_date": null,
    "referer": "api_key",
    "ip": "189.8.94.42",
    "subscription_id": 205840,
    "split_rules": null,
    "metadata": {},
    "antifraud_metadata": {}
  },
  "postback_url": "https://api.aardvarl.com/1/handlepostback/subscription",
  "payment_method": "credit_card",
  "card_brand": "visa",
  "card_last_digits": "4242",
  "current_period_start": "2017-06-18T06:45:51.182Z",
  "current_period_end": "2017-07-18T06:45:51.182Z",
  "charges": 0,
  "status": "paid",
  "date_created": "2017-06-18T06:45:51.731Z",
  "phone": null,
  "address": null,
  "customer": {
    "object": "customer",
    "id": 198786,
    "external_id": null,
    "type": null,
    "country": null,
    "document_number": null,
    "document_type": "cpf",
    "name": null,
    "email": "aarvark.silva@emailg.com",
    "phones": null,
    "born_at": null,
    "birthday": null,
    "gender": null,
    "date_created": "2017-06-18T06:36:41.886Z",
    "documents": []
  },
  "card": {
    "object": "card",
    "id": "card_cj429yy5v01o8cd6eqgslolec",
    "date_created": "2017-06-18T05:32:06.646Z",
    "date_updated": "2017-06-18T05:33:03.995Z",
    "brand": "visa",
    "holder_name": "Chuck Silva",
    "first_digits": "424242",
    "last_digits": "4242",
    "country": "US",
    "fingerprint": "Ntjtk/Hk/QnY",
    "valid": true,
    "expiration_date": "1122"
  },
  "metadata": null,
  "settled_charges": null
}

Suggest Edits

Split com assinatura

Além de cobrar o seu cliente de forma recorrente, você também pode dividir as transações resultantes dessas assinaturas, entre dois ou mais recebedores de sua company. Os parâmetros a serem passados, além dos já existentes e explicados na seção anterior, são o conjunto split_rules:

posthttps://api.pagar.me/1/subscriptions

Body Params

split_rules

array of objects

required

Regras de split para transações criadas a partir de sua assinatura

liable

charge_processing_fee

percentage

amount

charge_remainder_fee

recipient_id

plan_id

string

required

ID do plano a ser associado a uma assinatura

card_hash

string

required

Dados encriptados do cartão do cliente. Você também pode usar o card_id ao invés do card_hash

card_number

string

required

Número do cartão, se for uma assinatura de cartão

card_cvv

string

required

CVV do cartão, se for uma assinatura paga com cartão

card_holder_name

string

required

Nome do detentor do cartão se for uma assinatura paga com cartão

card_expiration_date

string

required

Data de expiração do cartão, se for uma assinatura paga com cartão

card_id

string

required

ID do cartão a ser cobrado, se for uma assinatura paga com cartão

postback_url

string

URL para a qual a nossa API irá enviar requisições informando alterações de status da assinatura em questão.

customer

object

customer.email

string

required

E-mail do cliente

customer.name

string

Nome completo ou razão social do cliente que está realizando a transação

customer.document_number

string

CPF ou CNPJ do cliente, sem separadores

customer.address

object

customer.address.street

string

logradouro (rua, avenida, etc) do cliente

customer.address.street_number

string

Número da residência/estabelecimento do cliente

customer.address.complementary

string

complemento do endereço do cliente

customer.address.neighborhood

string

bairro de localização do cliente

customer.address.zipcode

string

CEP do imóvel do cliente, sem separadores

customer.phone

object

customer.phone.ddd

string

DDD do telefone do cliente

customer.phone.number

string

número de telefone do cliente

customer.sex

string

sexo do cliente

customer.born_at

date

Data de nascimento do cliente. Ex: 11-02-1985

metadata

json

Você pode passar dados adicionais na criação da transação para facilitar uma futura análise de dados tanto em nossa dashboard, quanto por seus sistemas. Ex: metadata[ idProduto ]=13933139

Dados necessários para uma assinatura

Dados obrigatórios

O e-mail do cliente é uma informação obrigatória, uma vez que utilizamos ele para enviar e-mails de assinatura.

Antifraude

A primeira transação criada em uma assinatura passa por antifraude, logo, é obrigatório enviar todos os dados de customer.

Valores de uma assintura

Dando descontos na assinatura

Só é possível dar descontos em uma assinatura através de troca para um plano mais barato, mas vale ressaltar que isso gera uma nova periodicidade. Mais em: Fluxo de cobrança.

Observações

ID do plano

Lembre-se de passar o ID de seu plano em todas as requests, para que não seja necessário recriar todas assinaturas que ficaram com plan_id = null.

curl -X POST -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":"aardvark.silva@pagar.me",
    "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
    }
  ]
}' "https://api.pagar.me/1/subscriptions"

require 'pagarme'

PagarMe.api_key = "ak_test_grXijQ4GicOa2BLGZrDRTR5qNQxJW0"

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 => {
        email: 'api@test.com'
    },
    :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("pagarme-php/Pagarme.php");

Pagarme::setApiKey("SUA API KEY");

$plan = PagarMe_Plan::findById("133163");

$subscription = new PagarMe_Subscription(array(
    "plan" => $plan,
    "payment_method" => "credit_card",
    "card_hash" => "card_hash_gerado",
    'customer' => array(
        'email' => 'whitney.silva@pagar.me'
    ),
    'split_rules' => array(
        array(
            "recipient_id" => "re_ciyol0qac00xnlg6dkaftvn9j",
            "liable" => "false",
            "charge_processing_fee" => "false",
            "percentage" => "20"
        ),
        array(
            "recipient_id" => "re_ciyoloogb0100l46dy6f1iuww",
            "liable" => "true",
            "charge_processing_fee" => "true",
            "percentage" => "80"
        )
    )));

$subscription->create();

Oops, ainda não temos essa feature no SDK.

Oops, ainda não temos essa feature no SDK.

Oops, ainda não temos essa feature no SDK.

const pagarme = require("pagarme");

pagarme.client.connect({ api_key: "SUA API KEY" })
.then( client => {

    client.subscriptions.create({
      plan_id: "ID DO PLANO",
      card_number: '4111111111111111',
      card_holder_name: 'Customer Teste',
      card_expiration_date: '1123',
      card_cvv: '123',
      customer: {
        document_number: '18152564000105',
        name: 'Customer Teste',
        email: 'customer@email.com',
        born_at: '17071996',
        gender: 'M',
        address: {
          street: 'Rua Fidêncio Ramos',
          complementary: 'apto',
          street_number: '308',
          neighborhood: 'pinheiros',
          city: 'São Paulo',
          state: 'SP',
          zipcode: '04551010',
          country: 'Brasil'
        },
        phone: {
          ddd: '11',
          number: '999887766'
        }
      },
      split_rules: [
        {
          recipient_id: "ID DO RECEBEDOR",
          charge_processing_fee: true,
          liable: true,
          percentage: 50
        },
        {
          recipient_id: "ID DO RECEBEDOR",
          charge_processing_fee: false,
          liable: false,
          percentage: 50
        }
      ]
    })
    .then( subscription => console.log(subscription), failure => console.log(failure) );

});

import pagarme

pagarme.authentication_key('SUA_API_KEY')

subscription = pagarme.subscription.create({
    "card_id": "card_cj6qvosem04w3nu6dm20nu8od",
    "customer":{
        "email":"aardvark.silva@gmail.com",
        "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)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

{
    "object": "subscription",
    "plan": {
        "object": "plan",
        "id": 12783,
        "amount": 31000,
        "days": 30,
        "name": "Plano Ouro",
        "trial_days": 0,
        "date_created": "2015-03-03T16:56:32.000Z",
        "payment_methods": ["boleto", "credit_card"],
        "color": null,
        "charges": null,
        "installments": 1
    },
    "id": 16892,
    "current_transaction": {
        "object": "transaction",
        "status": "waiting_payment",
        "refuse_reason": null,
        "status_reason": "acquirer",
        "acquirer_response_code": null,
        "acquirer_name": "development",
        "authorization_code": null,
        "soft_descriptor": null,
        "tid": null,
        "nsu": null,
        "date_created": "2015-04-14T20:17:18.000Z",
        "date_updated": "2015-04-14T20:17:19.000Z",
        "amount": 31000,
        "installments": 1,
        "id": 194402,
        "cost": 0,
        "card_holder_name": null,
        "card_last_digits": null,
        "card_first_digits": null,
        "card_brand": null,
        "postback_url": null,
        "payment_method": "boleto",
        "antifraud_score": null,
        "boleto_url": "https://pagar.me",
        "boleto_barcode": "1234 5678",
        "boleto_expiration_date": "2015-04-21T20:17:18.000Z",
        "referer": "api_key",
        "ip": "179.185.132.108",
        "subscription_id": 16892,
        "metadata": {}
    },
    "postback_url": "http://requestb.in/zyn5obzy",
    "payment_method": "boleto",
    "current_period_start": null,
    "current_period_end": null,
    "charges": 0,
    "status": "unpaid",
    "date_created": "2015-04-14T20:17:19.000Z",
    "phone": null,
    "address": null,
    "customer": {
        "object": "customer",
        "document_number": null,
        "document_type": "cpf",
        "name": null,
        "email": "api@test.com",
        "born_at": null,
        "gender": null,
        "date_created": "2015-03-04T18:40:03.000Z",
        "id": 14437
    },
    "card": null,
    "metadata": null
}

Suggest Edits

Retornando uma assinatura

Essa rota é utilizada para retornar os dados de uma determinada assinatura.

gethttps://api.pagar.me/1/subscriptions/subscription_id

Path Params

subscription_id

string

required

Id da assinatura

curl -X GET https://api.pagar.me/1/subscriptions/205881 -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY"
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

subscription = PagarMe::Subscription.find_by_id("205881")

<?php
    require("pagarme-php/Pagarme.php");

    Pagarme::setApiKey("SUA_API_KEY");

    $subscription = PagarMe_Subscription::findById(205881);

PagarMeService.DefaultApiKey = "SUA_API_KEY";

var subscription = PagarMeService.GetDefaultService().Subscriptions.Find("205881");

import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Subscription;

PagarMe.init("SUA_API_KEY");

Subscription subscription = new Subscription().find("205881");

<?php
    require __DIR__.'/vendor/autoload.php';

    $pagarMe = new \PagarMe\Sdk\PagarMe('SUA_API_KEY');
    $subscription = $pagarMe->subscription()->get(205881);

const pagarme = require('pagarme')
  
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.subscriptions.find({ id: '205881' }))
  .then(subscription => console.log(subscription))

import pagarme

pagarme.authentication_key('SUA_API_KEY')

subscription = pagarme.subscription.find_by({"id": "ID_DA_SUBSCRIPTION"})

print (subscription)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

{
  "object": "subscription",
  "plan": {
    "object": "plan",
    "id": 166235,
    "amount": 10000,
    "days": 30,
    "name": "The Turtle plan",
    "trial_days": 0,
    "date_created": "2017-06-19T12:24:11.015Z",
    "payment_methods": [
      "credit_card"
    ],
    "color": null,
    "charges": 0,
    "installments": 1,
    "invoice_reminder": null
  },
  "id": 205881,
  "current_transaction": {
    "object": "transaction",
    "status": "paid",
    "refuse_reason": null,
    "status_reason": "acquirer",
    "acquirer_response_code": "0000",
    "acquirer_name": "pagarme",
    "acquirer_id": "56f9d019decf72cc70055d58",
    "authorization_code": "46650",
    "soft_descriptor": null,
    "tid": 1629201,
    "nsu": 1629201,
    "date_created": "2017-06-19T12:26:05.425Z",
    "date_updated": "2017-06-19T12:26:05.952Z",
    "amount": 10000,
    "authorized_amount": 10000,
    "paid_amount": 10000,
    "refunded_amount": 0,
    "installments": 1,
    "id": 1629201,
    "cost": 50,
    "card_holder_name": "Aardvark da Silva",
    "card_last_digits": "4242",
    "card_first_digits": "424242",
    "card_brand": "visa",
    "card_pin_mode": null,
    "postback_url": null,
    "payment_method": "credit_card",
    "capture_method": "ecommerce",
    "antifraud_score": null,
    "boleto_url": null,
    "boleto_barcode": null,
    "boleto_expiration_date": null,
    "referer": "api_key",
    "ip": "189.8.94.42",
    "subscription_id": 205881,
    "split_rules": null,
    "metadata": {},
    "antifraud_metadata": {}
  },
  "postback_url": null,
  "payment_method": "credit_card",
  "card_brand": "visa",
  "card_last_digits": "2122",
  "current_period_start": "2017-06-19T12:27:01.672Z",
  "current_period_end": "2017-07-19T12:27:01.672Z",
  "charges": 0,
  "status": "paid",
  "date_created": "2017-06-19T12:26:05.933Z",
  "phone": null,
  "address": null,
  "customer": {
    "object": "customer",
    "id": 198874,
    "external_id": null,
    "type": null,
    "country": null,
    "document_number": "03427857530",
    "document_type": "cpf",
    "name": "Aardvark Silva",
    "email": "aardvark.silva@emailg.com",
    "phones": null,
    "born_at": null,
    "birthday": null,
    "gender": null,
    "date_created": "2017-06-19T12:12:32.020Z",
    "documents": []
  },
  "card": {
    "object": "card",
    "id": "card_cj41mpuhc01bb3f6d8exeo072",
    "date_created": "2017-06-17T18:41:10.801Z",
    "date_updated": "2017-06-17T18:41:11.257Z",
    "brand": "visa",
    "holder_name": "Aardvark da Silva",
    "first_digits": "424242",
    "last_digits": "4242",
    "country": "AR",
    "fingerprint": "SK+CuBxPYsE7",
    "valid": true,
    "expiration_date": "1220"
  },
  "metadata": null,
  "settled_charges": null
}

Suggest Edits

Retornando assinaturas

Essa rota é utilizada para retornar os dados de todas assinaturas.

gethttps://api.pagar.me/1/subscriptions

Query Params

plan_id

string

Filtro pelo ID do plano atrelado

string

Filtro por ID

postback_url

string

Filtro pela URL de postback

payment_method

string

Filtro pelo meio de pagamento

capture_method

string

Filtro pelo meio de captura

card_brand

string

Filtro pela bandeira do cartão

card_last_digits

string

Filtro pelos 4 ultimos dígitos do cartão

current_period_start

date

Filtro pelo começo do período atual da assinatura em ISODate

current_period_end

date

Filtro pelo fim do período atual em ISODate

status

string

Filtro pelo status da assinatura

date_created

date-time

Filtro pela data de criação

phone_id

string

Filtro pelo ID do telefone atrelado à assinatura

customer_id

string

Filtro pelo ID do cliente atrelado à assinatura

address_id

string

Filtro pelo ID do endereço atrelado ao cliente da assinatura.

metadata

json

Filtro pelo metadata

count

int32

Quantidade de resultados que devem ser retornados

page

int32

Útil para implementação de uma paginação de resultados

Filtros de objetos

Para filtrar por chaves nested de objetos usa-se a sintaxe de chaves. Por exemplo:

curl -X GET https://api.pagar.me/1/transactions \
-d 'api_key=SUA_API_KEY'
-d 'metadata[chave]=valor'

Filtros de range

Todos os filtros mencionados podem ser usados para buscas em ranges usando os prefixos:

Prefixo	Significado
<	menor que
>	maior que
<=	menor ou igual a
>=	maior ou igual a

Por exemplo, para buscar em um range de date_created:

curl -X GET https://api.pagar.me/1/transactions \
-d 'api_key=SUA_API_KEY'
-d 'date_created=>=1483236000000'
-d 'date_created=<=1484689847590'

Para campos que sejam strings, a comparação é lexicográfica, letras maiúsculas sendo 'maiores' que minúsculas.

Filtros de data

É importante notar o formato das datas para o filtro. Para gerar o unixTimeStamp de uma data, é possível utilizar o console do Google Chrome e utilizar o seguinte código em Javascript :

new Date("2017-12-25T02:00:00.000Z").getTime()

que retornará 1514167200000. Da mesma maneira, para criar uma data ISO date, basta fazer:

new Date().toISOString()

curl -X GET https://api.pagar.me/1/subscriptions -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY", 
    "count": "2", 
    "page": "1"
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

subscriptions = PagarMe::Subscription.all(1, 2)

<?php
    require("pagarme-php/Pagarme.php");

    Pagarme::setApiKey("SUA_API_KEY");

    $subscription = PagarMe_Subscription::all(1, 2);

PagarMeService.DefaultApiKey = "SUA_API_KEY";

var subscriptions = PagarMeService.GetDefaultService().Subscriptions.FindAll(new Subscription());

import java.util.Collection;

import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Subscription;

PagarMe.init("SUA_API_KEY");

Integer count = 10;
Integer page = 1;
Collection<Subscription> subs = new Subscription().findCollection(count, page);

<?php
require __DIR__.'/vendor/autoload.php';

date_default_timezone_set('America/Sao_Paulo');
$pagarMe = new \PagarMe\Sdk\PagarMe('SUA_API_KEY');

$count = 10;
$page = 1;
$subscriptions = $pagarMe->subscription()->getList($page, $count);

const pagarme = require('pagarme')
  
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.subscriptions.all())
  .then(subscriptions => console.log(subscriptions))

import pagarme

pagarme.authentication_key('SUA_API_KEY')

subscription = pagarme.subscription.find_all()
print (subscription)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

[
  {
    "object": "subscription",
    "plan": {
      "object": "plan",
      "id": 166235,
      "amount": 10000,
      "days": 30,
      "name": "The Turtles Plan",
      "trial_days": 0,
      "date_created": "2017-06-19T12:24:11.015Z",
      "payment_methods": [
        "credit_card"
      ],
      "color": null,
      "charges": 0,
      "installments": 1,
      "invoice_reminder": null
    },
    "id": 205881,
    "current_transaction": {
      "object": "transaction",
      "status": "paid",
      "refuse_reason": null,
      "status_reason": "acquirer",
      "acquirer_response_code": "0000",
      "acquirer_name": "pagarme",
      "acquirer_id": "56f9d019decf72cc70055d58",
      "authorization_code": "46650",
      "soft_descriptor": null,
      "tid": 1629201,
      "nsu": 1629201,
      "date_created": "2017-06-19T12:26:05.425Z",
      "date_updated": "2017-06-19T12:26:05.952Z",
      "amount": 10000,
      "authorized_amount": 10000,
      "paid_amount": 10000,
      "refunded_amount": 0,
      "installments": 1,
      "id": 1629201,
      "cost": 50,
      "card_holder_name": "Aardvark da Silva",
      "card_last_digits": "4242",
      "card_first_digits": "424242",
      "card_brand": "visa",
      "card_pin_mode": null,
      "postback_url": null,
      "payment_method": "credit_card",
      "capture_method": "ecommerce",
      "antifraud_score": null,
      "boleto_url": null,
      "boleto_barcode": null,
      "boleto_expiration_date": null,
      "referer": "api_key",
      "ip": "189.8.94.42",
      "subscription_id": 205881,
      "split_rules": null,
      "metadata": {},
      "antifraud_metadata": {}
    },
    "postback_url": null,
    "payment_method": "credit_card",
    "card_brand": "visa",
    "card_last_digits": "4242",
    "current_period_start": "2017-06-19T12:27:01.672Z",
    "current_period_end": "2017-07-19T12:27:01.672Z",
    "charges": 0,
    "status": "paid",
    "date_created": "2017-06-19T12:26:05.933Z",
    "phone": null,
    "address": null,
    "customer": {
      "object": "customer",
      "id": 198874,
      "external_id": null,
      "type": null,
      "country": null,
      "document_number": "03427857530",
      "document_type": "cpf",
      "name": "Aardvark Silva",
      "email": "aardvark.silva@emailg.com",
      "phones": null,
      "born_at": null,
      "birthday": null,
      "gender": null,
      "date_created": "2017-06-19T12:12:32.020Z",
      "documents": []
    },
    "card": {
      "object": "card",
      "id": "card_cj41mpuhc01bb3f6d8exeo072",
      "date_created": "2017-06-17T18:41:10.801Z",
      "date_updated": "2017-06-17T18:41:11.257Z",
      "brand": "visa",
      "holder_name": "Aardvark da Silva",
      "first_digits": "424242",
      "last_digits": "4242",
      "country": "AR",
      "fingerprint": "SK+CuBxPYsE7",
      "valid": true,
      "expiration_date": "1220"
    },
    "metadata": null,
    "settled_charges": null
  },
  {
    "object": "subscription",
    "plan": {
      "object": "plan",
      "id": 166231,
      "amount": 10000,
      "days": 30,
      "name": "The Turtle Plan",
      "trial_days": 0,
      "date_created": "2017-06-19T11:55:24.273Z",
      "payment_methods": [
        "boleto",
        "credit_card"
      ],
      "color": null,
      "charges": null,
      "installments": 1,
      "invoice_reminder": null
    },
    "id": 205880,
    "current_transaction": {
      "object": "transaction",
      "status": "paid",
      "refuse_reason": null,
      "status_reason": "acquirer",
      "acquirer_response_code": "0000",
      "acquirer_name": "pagarme",
      "acquirer_id": "56f9d019decf72cc70055d58",
      "authorization_code": "34097",
      "soft_descriptor": null,
      "tid": 1629199,
      "nsu": 1629199,
      "date_created": "2017-06-19T12:24:01.916Z",
      "date_updated": "2017-06-19T12:24:02.484Z",
      "amount": 10000,
      "authorized_amount": 10000,
      "paid_amount": 10000,
      "refunded_amount": 0,
      "installments": 1,
      "id": 1629199,
      "cost": 50,
      "card_holder_name": "Aardvark da Silva",
      "card_last_digits": "4242",
      "card_first_digits": "424242",
      "card_brand": "visa",
      "card_pin_mode": null,
      "postback_url": null,
      "payment_method": "credit_card",
      "capture_method": "ecommerce",
      "antifraud_score": null,
      "boleto_url": null,
      "boleto_barcode": null,
      "boleto_expiration_date": null,
      "referer": "api_key",
      "ip": "189.8.94.42",
      "subscription_id": 205880,
      "split_rules": null,
      "metadata": {},
      "antifraud_metadata": {}
    },
    "postback_url": null,
    "payment_method": "credit_card",
    "card_brand": "visa",
    "card_last_digits": "4242",
    "current_period_start": "2017-06-19T12:24:01.900Z",
    "current_period_end": "2017-07-19T12:24:01.900Z",
    "charges": 0,
    "status": "paid",
    "date_created": "2017-06-19T12:24:02.463Z",
    "phone": null,
    "address": null,
    "customer": {
      "object": "customer",
      "id": 198874,
      "external_id": null,
      "type": null,
      "country": null,
      "document_number": "03427857530",
      "document_type": "cpf",
      "name": "Aardvark Silva",
      "email": "aardvark.silva@emailg.com",
      "phones": null,
      "born_at": null,
      "birthday": null,
      "gender": null,
      "date_created": "2017-06-19T12:12:32.020Z",
      "documents": []
    },
    "card": {
      "object": "card",
      "id": "card_cj41mpuhc01bb3f6d8exeo072",
      "date_created": "2017-06-17T18:41:10.801Z",
      "date_updated": "2017-06-17T18:41:11.257Z",
      "brand": "visa",
      "holder_name": "Aardvark da Silva",
      "first_digits": "424242",
      "last_digits": "4242",
      "country": "AR",
      "fingerprint": "SK+CuBxPYsE7",
      "valid": true,
      "expiration_date": "1220"
    },
    "metadata": null,
    "settled_charges": null
  }
]

Suggest Edits

Atualizando uma assinatura

Após criar uma assinatura, você pode atualizar os dados do método do pagamento e o plano que essa assinatura está atrelada.

puthttps://api.pagar.me/1/subscriptions/id

Path Params

string

required

ID da assinatura

Body Params

plan_id

string

ID do novo plano atrelado a assinatura

payment_method

string

método de pagamento utilizado na assinatura. Valores possíveis: credit_card, boleto

card_id

string

Identificador dos dados de um cartão previamente salvo na nossa base de dados

card_hash

string

Dados encriptados de um cartão de crédito

card_number

string

Número de um cartão de crédito. Usado quando o cartão a ser configurado na assinatura ainda não está salvo no nosso banco de dados

card_holder_name

string

Nome do portador do cartão. Usado quando o cartão a ser configurado na assinatura ainda não está salvo no nosso banco de dados

card_expiration_date

string

Data de expiração do cartão. Ex: 0518 (Maio de 2018)

card_cvv

string

CVV do cartão, se for uma assinatura paga com cartão

Vale ressaltar

Para alterar o cartão de uma assinatura, é necessário passar o parâmetro payment_method=credit_card.

curl -X PUT https://api.pagar.me/1/subscriptions/205881 -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY", 
    "card_id": "card_cj41mpuhc01bb3f6d8exeo072", 
    "payment_method": "credit_card", 
    "plan_id": "166234"
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

subscription = PagarMe::Subscription.find_by_id(205881)

subscription.payment_method = 'credit_card'
subscription.card_id = 'card_cj41mpuhc01bb3f6d8exeo072'
subscription.plan_id = '166234'

subscription.save

<?php
    require("pagarme-php/Pagarme.php");

    Pagarme::setApiKey("SUA_API_KEY");

    $subscription = PagarMe_Subscription::findById(205881);
    $subscription->setPaymentMethod("credit_card");
    $subscription->setCardId("card_cj41mpuhc01bb3f6d8exeo072");
    $subscription->plan->id = "166234";

    $subscription->save();

PagarMeService.DefaultApiKey = "SUA_API_KEY";

var subscription = PagarMeService.GetDefaultService().Subscriptions.Find("205881");

subscription.PaymentMethod = PaymentMethod.CreditCard;
subscription.Card = PagarMeService.GetDefaultService().Cards.Find("card_cj41mpuhc01bb3f6d8exeo072");
subscription.Plan = PagarMeService.GetDefaultService().Plans.Find(166234);
subscription.Save();

<?php
    require __DIR__.'/vendor/autoload.php';

    date_default_timezone_set('America/Sao_Paulo');
    $pagarMe = new \PagarMe\Sdk\PagarMe('SUA_API_KEY');
    
 
    $subscription = $pagarMe->subscription()->get(184577);
    $newPlan = $pagarMe->plan()->get(166234);
    $subscription->setPlan($newPlan);
    $subscription->setPaymentMethod('credit_card');
    $card = $pagarMe->card()->get('card_cj41mpuhc01bb3f6d8exeo072');
    $subscription->setCard($card);

    $subscription = $pagarMe->subscription()->update($subscription);
    var_dump($subscription);

const pagarme = require('pagarme')
  
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.subscriptions.update({ id: '205881' }))
  .then(subscription => console.log(subscription))

import pagarme

pagarme.authentication_key('SUA_API_KEY')

subscription = pagarme.subscription.update(
    "subscription_id",
    {
        "card_id": "card_cj6p5853z0coko66e7h767986",
        "payment_method": "credit_card",
        "plan_id": "201836"
    }
)

print (subscription)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

{
  "object": "subscription",
  "plan": {
    "object": "plan",
    "id": 166234,
    "amount": 20000,
    "days": 30,
    "name": "The Dudes Plan",
    "trial_days": 0,
    "date_created": "2017-06-19T12:23:53.958Z",
    "payment_methods": [
      "credit_card"
    ],
    "color": null,
    "charges": 0,
    "installments": 1,
    "invoice_reminder": null
  },
  "id": 205881,
  "current_transaction": {
    "object": "transaction",
    "status": "paid",
    "refuse_reason": null,
    "status_reason": "acquirer",
    "acquirer_response_code": "0000",
    "acquirer_name": "pagarme",
    "acquirer_id": "56f9d019decf72cc70055d58",
    "authorization_code": "426266",
    "soft_descriptor": null,
    "tid": 1635873,
    "nsu": 1635873,
    "date_created": "2017-06-21T04:18:13.531Z",
    "date_updated": "2017-06-21T04:18:13.951Z",
    "amount": 10666,
    "authorized_amount": 10666,
    "paid_amount": 10666,
    "refunded_amount": 0,
    "installments": 1,
    "id": 1635873,
    "cost": 50,
    "card_holder_name": "Aardvark da Silva",
    "card_last_digits": "2122",
    "card_first_digits": "455636",
    "card_brand": "visa",
    "card_pin_mode": null,
    "postback_url": null,
    "payment_method": "credit_card",
    "capture_method": "ecommerce",
    "antifraud_score": null,
    "boleto_url": null,
    "boleto_barcode": null,
    "boleto_expiration_date": null,
    "referer": null,
    "ip": null,
    "subscription_id": 205881,
    "split_rules": null,
    "metadata": {},
    "antifraud_metadata": {}
  },
  "postback_url": null,
  "payment_method": "credit_card",
  "card_brand": "visa",
  "card_last_digits": "2122",
  "current_period_start": "2017-06-21T04:18:14.006Z",
  "current_period_end": "2017-07-21T04:18:14.006Z",
  "charges": 0,
  "status": "paid",
  "date_created": "2017-06-19T12:26:05.933Z",
  "phone": null,
  "address": null,
  "customer": {
    "object": "customer",
    "id": 198874,
    "external_id": null,
    "type": null,
    "country": null,
    "document_number": "03427857530",
    "document_type": "cpf",
    "name": "Aardvark Silva",
    "email": "aardvark.silva@emailg.com",
    "phones": null,
    "born_at": null,
    "birthday": null,
    "gender": null,
    "date_created": "2017-06-19T12:12:32.020Z",
    "documents": []
  },
  "card": {
    "object": "card",
    "id": "card_cj41mpuhc01bb3f6d8exeo072",
    "date_created": "2017-06-17T18:41:10.801Z",
    "date_updated": "2017-06-17T18:41:11.257Z",
    "brand": "visa",
    "holder_name": "Aardvark da Silva",
    "first_digits": "455636",
    "last_digits": "2122",
    "country": "AR",
    "fingerprint": "SK+CuBxPYsE7",
    "valid": true,
    "expiration_date": "1220"
  },
  "metadata": null,
  "settled_charges": null
}

Suggest Edits

Cancelando uma assinatura

Para cancelar uma assinatura você deve utilizar a rota /subscriptions/:id/cancel

posthttps://api.pagar.me/1/subscriptions/subscription_id/cancel

Path Params

subscription_id

string

required

ID da assinatura a ser cancelada

curl -X POST https://api.pagar.me/1/subscriptions/205880/cancel -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY"
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

subscription = PagarMe::Subscription.find_by_id("205880")

subscription.cancel

<?php
    require("pagarme-php/Pagarme.php");

    Pagarme::setApiKey("SUA_API_KEY");

    $subscription = PagarMe_Subscription::findById(205880);
    $subscription->cancel();

PagarMeService.DefaultApiKey = "SUA_API_KEY";
var subscription = PagarMeService.GetDefaultService().Subscriptions.Find("205880");
subscription.Cancel();

import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Subscription;

PagarMe.init("SUA_API_KEY");

Subscription subscription = new Subscription().find("205880");
subscription.cancel();

<?php
    require __DIR__.'/vendor/autoload.php';

    $pagarMe = new \PagarMe\Sdk\PagarMe('SUA_API_KEY');

    $subscriptionId = 205880;
    $subscription = $pagarMe->subscription()->get($subscriptionId);
    $subscription = $pagarMe->subscription()->cancel($subscription);

const pagarme = require('pagarme')
  
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.subscriptions.cancel({ id: '205880' }))
  .then(subscription => console.log(subscription))

import pagarme

pagarme.authentication_key('SUA_API_KEY')

subscription = pagarme.subscription.cancel("ID_DA_SUBSCRIPTION")

print (subscription)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

{
  "object": "subscription",
  "plan": {
    "object": "plan",
    "id": 166231,
    "amount": 10000,
    "days": 30,
    "name": "The Pro Plan",
    "trial_days": 0,
    "date_created": "2017-06-19T11:55:24.273Z",
    "payment_methods": [
      "boleto",
      "credit_card"
    ],
    "color": null,
    "charges": null,
    "installments": 1,
    "invoice_reminder": null
  },
  "id": 205880,
  "current_transaction": {
    "object": "transaction",
    "status": "paid",
    "refuse_reason": null,
    "status_reason": "acquirer",
    "acquirer_response_code": "0000",
    "acquirer_name": "pagarme",
    "acquirer_id": "56f9d019decf72cc70055d58",
    "authorization_code": "34097",
    "soft_descriptor": null,
    "tid": 1629199,
    "nsu": 1629199,
    "date_created": "2017-06-19T12:24:01.916Z",
    "date_updated": "2017-06-19T12:24:02.484Z",
    "amount": 10000,
    "authorized_amount": 10000,
    "paid_amount": 10000,
    "refunded_amount": 0,
    "installments": 1,
    "id": 1629199,
    "cost": 50,
    "card_holder_name": "Aardvark da Silva",
    "card_last_digits": "4242",
    "card_first_digits": "424242",
    "card_brand": "visa",
    "card_pin_mode": null,
    "postback_url": null,
    "payment_method": "credit_card",
    "capture_method": "ecommerce",
    "antifraud_score": null,
    "boleto_url": null,
    "boleto_barcode": null,
    "boleto_expiration_date": null,
    "referer": "api_key",
    "ip": "189.8.94.42",
    "subscription_id": 205880,
    "split_rules": null,
    "metadata": {},
    "antifraud_metadata": {}
  },
  "postback_url": null,
  "payment_method": "credit_card",
  "card_brand": "visa",
  "card_last_digits": "4242",
  "current_period_start": "2017-06-19T12:24:01.900Z",
  "current_period_end": "2017-07-19T12:24:01.900Z",
  "charges": 0,
  "status": "canceled",
  "date_created": "2017-06-19T12:24:02.463Z",
  "phone": null,
  "address": null,
  "customer": {
    "object": "customer",
    "id": 198874,
    "external_id": null,
    "type": null,
    "country": null,
    "document_number": "03427857530",
    "document_type": "cpf",
    "name": "Aardvark Silva",
    "email": "aardvark.silva@emailg.com",
    "phones": null,
    "born_at": null,
    "birthday": null,
    "gender": null,
    "date_created": "2017-06-19T12:12:32.020Z",
    "documents": []
  },
  "card": {
    "object": "card",
    "id": "card_cj41mpuhc01bb3f6d8exeo072",
    "date_created": "2017-06-17T18:41:10.801Z",
    "date_updated": "2017-06-17T18:41:11.257Z",
    "brand": "visa",
    "holder_name": "Aardvark da Silva",
    "first_digits": "424242",
    "last_digits": "4242",
    "country": "AR",
    "fingerprint": "SK+CuBxPYsE7",
    "valid": true,
    "expiration_date": "1220"
  },
  "metadata": null,
  "settled_charges": null
}

Suggest Edits

Transações de assinatura

Retorna um array de objetos transaction contendo as transações feitas a partir de uma assinatura.

gethttps://api.pagar.me/1/subscriptions/id_subscription/transactions

Path Params

id_subscription

string

required

ID da assinatura que possui as transações desejadas

Query Params

count

string

Parâmetro de paginação. Quantidade a ser retornada por página

page

string

Parâmetro de paginação. Página da listagem

status

string

Filtro de status das transações

date_created

date-time

Filtro da data de criação

date_updated

date-time

Filtro da data de update

amount

string

Filtro de valor da transação

installments

string

Filtro de parcelas da transação

string

Filtro de ID da transação

tid

string

Filtro de TID das transações

nsu

string

Filtro de NSU das transações

card_holder_name

string

Filtro de nome do portador do cartão das transações

card_last_digits

string

Filtro dos ultimos dígitos do cartão da transação

card_brand

string

Filtro da bandeira do cartão da transação

postback_url

string

Filtro da URL do postback da transação

payment_method

string

Filtro do meio de pagamento da transação

boleto_url

string

Filtro de URL do boleto da transação

boleto_barcode

string

Filtro do barcode do boleto

customer

object

Filtro pelos dados do customer atrelado

address

object

Filtro pelos dados do endereço atrelado

phone

object

Filtro pelos dados do telefone atrelado

metadata

object

Filtro pelos dados do metadata atrelado

Filtros de objetos

Para filtrar por chaves nested de objetos usa-se a sintaxe de chaves. Por exemplo:

curl -X GET https://api.pagar.me/1/transactions \
-d 'api_key=SUA_API_KEY'
-d 'metadata[chave]=valor'

Filtros de range

Todos os filtros mencionados podem ser usados para buscas em ranges usando os prefixos:

Prefixo	Significado
<	menor que
>	maior que
<=	menor ou igual a
>=	maior ou igual a

Por exemplo, para buscar em um range de date_created:

curl -X GET https://api.pagar.me/1/transactions \
-d 'api_key=ak_test_grXijQ4GicOa2BLGZrDRTR5qNQxJW0'
-d 'date_created=>=1483236000000'
-d 'date_created=<=1484689847590'

Para campos que sejam strings, a comparação é lexicográfica, letras maiúsculas sendo 'maiores' que minúsculas.

Filtros de data

curl -X GET https://api.pagar.me/1/subscriptions/205840/transactions -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY"
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

subscription = PagarMe::Subscription.find_by_id("205881");

subscription.transactions

<?php
require("pagarme-php/Pagarme.php");

Pagarme::setApiKey("SUA_API_KEY");

$subscription = PagarMe_Subscription::findById(205881);

$transactions = $subscription->getTransactions();

Oops, ainda não temos essa feature no SDK.

import java.util.Collection;

import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Subscription;
import me.pagar.model.Transaction;

PagarMe.init("SUA_API_KEY");

Collection<Transaction> txs = new Subscription().find("205840").transactions();

<?php
    require __DIR__.'/vendor/autoload.php';

    $pagarMe = new \PagarMe\Sdk\PagarMe('SUA_API_KEY');

    $subscriptionId = 205840;
    $subscription = $pagarMe->subscription()->get($subscriptionId);
    $transactions = $pagarMe->subscription()->transactions($subscription);

const pagarme = require('pagarme')
  
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.subscriptions.findTransactions({ id: '205840' }))
  .then(subscription => console.log(subscription))

import pagarme

pagarme.authentication_key('SUA_API_KEY')

subscription = pagarme.subscription.transactions("ID_DA_SUBSCRIPTION")

print (subscription)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

[
  {
    "object": "transaction",
    "status": "paid",
    "refuse_reason": null,
    "status_reason": "acquirer",
    "acquirer_response_code": "0000",
    "acquirer_name": "pagarme",
    "acquirer_id": "56f9d019decf72cc70055d58",
    "authorization_code": "211852",
    "soft_descriptor": null,
    "tid": 1627876,
    "nsu": 1627876,
    "date_created": "2017-06-18T06:45:51.193Z",
    "date_updated": "2017-06-18T06:45:51.742Z",
    "amount": 15000,
    "authorized_amount": 15000,
    "paid_amount": 15000,
    "refunded_amount": 0,
    "installments": 1,
    "id": 1627876,
    "cost": 50,
    "card_holder_name": "Chuck Silva",
    "card_last_digits": "4242",
    "card_first_digits": "424242",
    "card_brand": "visa",
    "card_pin_mode": null,
    "postback_url": null,
    "payment_method": "credit_card",
    "capture_method": "ecommerce",
    "antifraud_score": null,
    "boleto_url": null,
    "boleto_barcode": null,
    "boleto_expiration_date": null,
    "referer": "api_key",
    "ip": "189.8.94.42",
    "subscription_id": 205840,
    "phone": null,
    "address": null,
    "customer": {
      "object": "customer",
      "id": 198786,
      "external_id": null,
      "type": null,
      "country": null,
      "document_number": null,
      "document_type": "cpf",
      "name": null,
      "email": "aarvark.silva@emailg.com",
      "phones": null,
      "born_at": null,
      "birthday": null,
      "gender": null,
      "date_created": "2017-06-18T06:36:41.886Z",
      "documents": []
    },
    "billing": null,
    "shipping": null,
    "items": [],
    "card": {
      "object": "card",
      "id": "card_cj429yy5v01o8cd6eqgslolec",
      "date_created": "2017-06-18T05:32:06.646Z",
      "date_updated": "2017-06-18T05:33:03.995Z",
      "brand": "visa",
      "holder_name": "Chuck Silva",
      "first_digits": "424242",
      "last_digits": "4242",
      "country": "US",
      "fingerprint": "Ntjtk/Hk/QnY",
      "valid": true,
      "expiration_date": "1122"
    },
    "split_rules": null,
    "antifraud_metadata": {},
    "metadata": {}
  }
]

Suggest Edits

Pulando cobranças

Pula as x próximas cobranças de uma assinatura . Funciona apenas para assinaturas com status unpaid ou pending_payment

posthttps://api.pagar.me/1/subscriptions/subscription_id/settle_charge

Path Params

subscription_id

string

required

ID da assinatura referenciada

Body Params

charges

int32

Quantas cobranças devem ser puladas

Não temos essa feature implementada ainda :(

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

subscription_id = "205881"
subscription = PagarMe::Subscription.find_by_id(subscription_id)

subscription.settle_charge

Não temos essa feature implementada ainda :(

Não temos essa feature implementada :(

N]ao temos essa feature implementada ainda :(

curl -X POST https://api.pagar.me/1/subscriptions/206087/settle_charge \
  -H 'content-type: application/json' \
  -d '{
	"api_key": "SUA_API_KEY",
	"charges": 2
}'

import pagarme

pagarme.authentication_key('SUA_API_KEY')

subscription = pagarme.subscription.settle_charges("ID_DA_SUBSCRIPTION")

print (subscription)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

{
    "object": "subscription",
    "plan": {
        "object": "plan",
        "id": 138554,
        "amount": 4990,
        "days": 30,
        "name": "Plano Especial",
        "trial_days": 0,
        "date_created": "2017-03-06T13:44:00.401Z",
        "payment_methods": [
            "credit_card",
            "boleto"
        ],
        "color": null,
        "charges": null,
        "installments": 1,
        "invoice_reminder": null
    },
    "id": 206087,
    "current_transaction": null,
    "postback_url": null,
    "payment_method": "boleto",
    "card_brand": null,
    "card_last_digits": null,
    "current_period_start": "2017-07-04T14:27:17.242Z",
    "current_period_end": "2017-08-03T14:27:17.242Z",
    "charges": 2,
    "status": "paid",
    "date_created": "2017-06-20T14:26:28.734Z",
    "phone": {
        "object": "phone",
        "ddi": "55",
        "ddd": "11",
        "number": "87654321",
        "id": 118169
    },
    "address": {
        "object": "address",
        "street": "rua",
        "complementary": null,
        "street_number": "122",
        "neighborhood": "bairro",
        "city": null,
        "state": null,
        "zipcode": "06350270",
        "country": null,
        "id": 121172
    },
    "customer": {
        "object": "customer",
        "id": 156977,
        "external_id": null,
        "type": null,
        "country": null,
        "document_number": "35965816804",
        "document_type": "cpf",
        "name": "teste",
        "email": "qwe@qwe.com",
        "phones": null,
        "born_at": "1970-01-01T03:38:41.988Z",
        "birthday": null,
        "gender": "M",
        "date_created": "2017-02-24T17:58:49.028Z",
        "documents": []
    },
    "card": null,
    "metadata": null,
    "settled_charges": [
        1,
        2
    ]
}

Suggest Edits

Objeto-resposta Postback

Ao criar uma transação ou uma assinatura você tem a opção de passar o parâmetro postback_url na requisição. Essa é uma URL do seu sistema que irá então receber notificações a cada alteração de status dessas transações/assinaturas.

1. Propriedades de um postback

Propriedades específicas do postback:

Propriedade

Descrição

object
String

Nome do tipo do objeto criado/modificado.
Valor retornado: postback

status
String

Status atual do postback. Pode ser: processing, waiting_retry, pending_retry, failed, success

model
String

A que tipo de objeto o postback se relaciona. Pode ser 'transaction', 'subscription' ou 'recipient'

model_id
String

ID do objeto relacionado.

headers
String

String com formato json dos headers enviados no postback

payload
String

Corpo do postback, envolve o conteúdo do objeto a que corresponde a notificação. Dentre eles transaction, subscription e recipient. Mais na seção a seguir.

request_url
String

URL para a qual o postback foi enviado

retries
Integer

Quantidade de reenvios. A primeira tentativa não conta como uma retentativa

next_retry
Datetime

Data e hora do próximo reenvio.

deliveries
Array com objetos do tipo postback_delivery

Lista das tentativas até então. Retornam informações sobre a comunicação entre nossos servidores e sua aplicação, descrevendo status response header, etc.

date_created
Datetime

Data de criação

date_updated
Datetime

Data da ultima mudança

signature
String

Hmac SHA1 do payload

id
String

ID do postback

2. Payload de um postback

Você irá receber em sua postback_url, isto é, em seu servidor, uma propriedade chamada payload, em formato de query string. É ela que contém as informações do evento que ocorreu junto à transação ou assinatura de sua company. A seguir mais detalhes sobre cada propriedade:

Propriedade

Descrição

id
String

ID do objeto sendo enviado no payload. Objetos possíveis: transação, assinatura ou recebedor.

fingerprint
String

Hash gerada para validação do postback em seu servidor.

event
String

Define qual evento aconteceu para que o postback tenha sido enviado. Valores possíveis: transaction_status_changed, subscription_status_changed, recipient_status_changed, transaction_created.

old_status
String

Indica qual era o status antigo do objeto sendo enviado.

desired_status
String

Indica qual seria o status ideal para objetos deste tipo, em um fluxo normal.

current_status
String

Indica qual é o real status do objeto.

object

Objeto enviado e que teve mudanças significativas, para iniciar um postback. Valores possíveis: transaction, subscription ou recipient.

Eventuais novos status de transação

Novos status de transação podem ser criados e enviados dentro do payload do postback. Desta forma, a sua aplicação deve estar preparada para receber por postback status de transação que anteriormente não existiam.

3. Observações sobre postback

Atenção

Não é possível alterar a URL de postback de uma transaction, subscription ou recipient.

Problemas com postback?

Alguns pontos a considerar:

-Houve alguma mudança de url do seu sistema? Por exemplo : https://lojateste.com.br para https://novalojateste.com.br ; Se sim, você deve redirecionar os postbacks para sua nova url.

-Houve troca de protocolo? Por exemplo : http://lojateste.com.br para https://lojateste.com.br ; Este caso também requer que você mantenha ambas URLs funcionando, e redirecionando postback de acordo com necessidade. Caso tenha mais dúvidas, entre em contato com suporte@pagar.me para que possamos ajudar ;)

4. Postback deliveries

Cada tentativa de envio de postback cria uma nova entidade de delivery. Ou seja, um novo registro de tentativa, bem-sucedida ou não, de entrega de postback à sua aplicação. Segue a descrição de cada propriedade de um delivery:

Propriedade

Descrição

object
String

Nome do tipo do objeto criado/modificado.
Valor retornado: postback_delivery

status
String

Status do delivery. Pode ser: processing, failed, success

status_reason
String

Razão do status. Pode ser http_status_code ou null

status_code
String

Http status recebido como response de seus servidores.

response_time
Integer

Milissegundos entre envio do postback e a response

response_headers
String

Headers da response do postback

response_body
String

Corpo da resposta do postback. Esta é a response que seus servidores enviaram à API Pagar.me

date_created
Datetime

Data de criação do delivery

date_updated
Datetime

Data da última atualização do delivery

id
String

ID do delivery

Suggest Edits

Reenvio de postback

Com essa rota você pode reenviar qualquer postback que pertença a uma transação ou assinatura.

posthttps://api.pagar.me/1/model/model_id/postbacks/id/redeliver

Path Params

model_id

string

required

ID da transação, assinatura ou recebedor

string

required

ID do postback

model

string

required

Qual o tipo da entidade referenciada. Pode ser transactions, subscriptions, recipients

Processo de retentativa

Nossa API faz até 31 tentativas de envio do postback, caso sua plataforma não envie uma http status code igual a 200. Após todas se esgotarem, é necessário que a sua plataforma
solicite o reenvio através dessa rota.

curl -X POST https://api.pagar.me/1/transactions/1662527/postbacks/po_cj4haa8l4131bpi73glgzbnpp/redeliver -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY"
}'
#ou para assinaturas
curl -X POST https://api.pagar.me/1/subscriptions/208309/postbacks/po_cj4hbrmg713jopi738gn1hzh0/redeliver -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY"
}'

PagarMeService.DefaultApiKey = "SUA_API_KEY";
var postback = PagarMeService.GetDefaultService().Transactions.Find("1662527").Postbacks.Find("po_cj4haa8l4131bpi73glgzbnpp");
postback.Redeliver();

<?php
    require __DIR__.'/vendor/autoload.php';

    $pagarMe = new \PagarMe\Sdk\PagarMe('SUA_API_KEY');		

		$transactionId = 1662527;
		$transaction = $pagarMe->transaction()->get($transactionId);

		$postbackId = 'po_cj4haa8l4131bpi73glgzbnpp';
    $postbacks = $pagarMe->postback()->redeliver(
        $transaction,
        $postbackId
    );

const pagarme = require('pagarme')
  
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.postbacks.redeliver({ subscriptionId: 208309, id: 'po_cj4hbrmg713jopi738gn1hzh0' }))

Oops. Não temos essa funcionalidade em nosso SDK.

import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Transaction;
import me.pagar.model.Postback;

PagarMe.init("SUA_API_KEY");

Transaction tx = new Transaction().find(1662527);
tx.postbackRedeliver("po_cj4haa8l4131bpi73glgzbnpp");

#Oops. Ainda não temos essa funcionalidade em nosso SDK.

import pagarme

pagarme.authentication_key('SUA_API_KEY')

redeliver = pagarme.transaction.postback_redeliver("transaction_id", "postback_id")

print (redeliver)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

{
  "object": "postback",
  "status": "pending_retry",
  "model": "transaction",
  "model_id": "1662527",
  "headers": "{\"Content-Type\":\"application/x-www-form-urlencoded\",\"X-PagarMe-Event\":\"transaction_status_changed\",\"X-Hub-Signature\":\"sha1=0c62a0b489e1138ef39ae71dece45be1c0e97c1e\",\"User-Agent\":\"PagarMe-Hookshot/1.0\"}",
  "payload": "id=1662527&fingerprint=a67597c98a493cc8b2c62ab018a553c19747e8a5&event=transaction_status_changed&old_status=waiting_payment&desired_status=paid&current_status=paid&object=transaction&transaction%5Bobject%5D=transaction&transaction%5Bstatus%5D=paid&transaction%5Brefuse_reason%5D=&transaction%5Bstatus_reason%5D=acquirer&transaction%5Bacquirer_response_code%5D=&transaction%5Bacquirer_name%5D=pagarme&transaction%5Bacquirer_id%5D=56f9d019decf72cc70055d58&transaction%5Bauthorization_code%5D=&transaction%5Bsoft_descriptor%5D=&transaction%5Btid%5D=1662527&transaction%5Bnsu%5D=1662527&transaction%5Bdate_created%5D=2017-06-28T17%3A36%3A52.808Z&transaction%5Bdate_updated%5D=2017-06-28T17%3A37%3A25.949Z&transaction%5Bamount%5D=15000&transaction%5Bauthorized_amount%5D=15000&transaction%5Bpaid_amount%5D=0&transaction%5Brefunded_amount%5D=0&transaction%5Binstallments%5D=1&transaction%5Bid%5D=1662527&transaction%5Bcost%5D=380&transaction%5Bcard_holder_name%5D=&transaction%5Bcard_last_digits%5D=&transaction%5Bcard_first_digits%5D=&transaction%5Bcard_brand%5D=&transaction%5Bcard_pin_mode%5D=&transaction%5Bpostback_url%5D=https%3A%2F%2Frequestb.in%2F10m5xva1&transaction%5Bpayment_method%5D=boleto&transaction%5Bcapture_method%5D=ecommerce&transaction%5Bantifraud_score%5D=&transaction%5Bboleto_url%5D=https%3A%2F%2Fpagar.me&transaction%5Bboleto_barcode%5D=1234%205678&transaction%5Bboleto_expiration_date%5D=2017-07-03T03%3A00%3A00.000Z&transaction%5Breferer%5D=api_key&transaction%5Bip%5D=177.63.194.231&transaction%5Bsubscription_id%5D=&transaction%5Bphone%5D=&transaction%5Baddress%5D=&transaction%5Bcustomer%5D=&transaction%5Bbilling%5D=&transaction%5Bshipping%5D=&transaction%5Bcard%5D=&transaction%5Bsplit_rules%5D=",
  "request_url": "https://requestb.in/10m5xva1",
  "retries": 0,
  "next_retry": null,
  "deliveries": [
    {
      "object": "postback_delivery",
      "status": "success",
      "status_reason": "http_status_code",
      "status_code": "200",
      "response_time": 228,
      "response_headers": "{\"date\":\"Wed, 28 Jun 2017 17:37:26 GMT\",\"content-type\":\"text/html; charset=utf-8\",\"transfer-encoding\":\"chunked\",\"connection\":\"close\",\"set-cookie\":[\"__cfduid=dd5481bfa0252320257fb1d3de05f19961498671446; expires=Thu, 28-Jun-18 17:37:26 GMT; path=/; domain=.requestb.in; HttpOnly\"],\"sponsored-by\":\"https://www.runscope.com\",\"via\":\"1.1 vegur\",\"strict-transport-security\":\"max-age=15552000\",\"x-content-type-options\":\"nosniff\",\"server\":\"cloudflare-nginx\",\"cf-ray\":\"376269f9ef4c0ed9-EWR\"}",
      "response_body": "ok",
      "date_created": "2017-06-28T17:37:26.033Z",
      "date_updated": "2017-06-28T17:37:26.266Z",
      "id": "pd_cj4haa8lt14slps730qybvjij"
    }
  ],
  "date_created": "2017-06-28T17:37:26.008Z",
  "date_updated": "2017-06-28T18:11:42.999Z",
  "signature": "sha1=0c62a0b489e1138ef39ae71dece45be1c0e97c1e",
  "id": "po_cj4haa8l4131bpi73glgzbnpp"
}

Suggest Edits

Lista de postbacks

Retorna todos os postbacks enviados, que estejam relacionados a transações ou assinaturas.

gethttps://api.pagar.me/1/model/model_id/postbacks

Path Params

model

string

required

Model a que o grupo de postbacks pertence. Valores possíveis: transactions, subscriptions ou recipients.

model_id

string

required

ID do model a que este postback pertence.

curl -X GET https://api.pagar.me/1/transactions/888502/postbacks -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY"
}'

PagarMeService.DefaultApiKey = "ak_test_grXijQ4GicOa2BLGZrDRTR5qNQxJW0";
var postbacks = PagarMeService.GetDefaultService().Transactions.Find("314578").Postbacks.FindAll(new Postback());

Oops não temos essa feature em nosso SDK.

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

subscription = PagarMe::Subscription.find_by_id("205881")
subscription.postbacks

<?php
    require __DIR__.'/vendor/autoload.php';

    date_default_timezone_set('America/Sao_Paulo');
    $pagarMe = new \PagarMe\Sdk\PagarMe('SUA_API_KEY');

		$transactionId = 1159049;
    $transaction = $pagarMe->transaction()->get(transactionId);
    $postbacks = $pagarMe->postback()->getList($transaction);
    var_dump($postbacks);

const pagarme = require('pagarme')

// From transaction:
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.postbacks.find({ transactionId: 1234 }))

// From subscription:
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.postbacks.find({ subscriptionId: 1234 }))

import pagarme

pagarme.authentication_key('SUA_API_KEY')

#transaction postbacks
postback = pagarme.transaction.postbacks("ID_DA_TRANSAÇÃO")
print (postback)

#subscription postbacks
postback = pagarme.subscription.postbacks("ID_DA_SUBSCRIPTION")

print (postback)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

{
    "date_created": "2016-11-25T03:42:10.719Z",
    "date_updated": "2016-11-25T03:42:10.802Z",
    "deliveries": [
        {
            "date_created": "2016-11-25T03:42:10.745Z",
            "date_updated": "2016-11-25T03:42:10.791Z",
            "id": "pd_civx8ry2h05ok46737pv27fv4",
            "object": "postback_delivery",
            "response_body": "ok",
            "response_headers": "{\"date\":\"Fri, 25 Nov 2016 03:42:10 GMT\",\"content-type\":\"text/html; charset=utf-8\",\"transfer-encoding\":\"chunked\",\"connection\":\"close\",\"set-cookie\":[\"__cfduid=d55f4f5d9b0afe3e197096eda73c9905c1480045330; expires=Sat, 25-Nov-17 03:42:10 GMT; path=/; domain=.requestb.in; HttpOnly\"],\"sponsored-by\":\"https://www.runscope.com\",\"via\":\"1.1 vegur\",\"server\":\"cloudflare-nginx\",\"cf-ray\":\"307216d544a12408-IAD\"}",
            "response_time": 36,
            "status": "success",
            "status_code": "200",
            "status_reason": "http_status_code"
        }
    ],
    "headers": "{\"Content-Type\":\"application/x-www-form-urlencoded\",\"X-PagarMe-Event\":\"transaction_status_changed\",\"X-Hub-Signature\":\"sha1=d3b3576d3c223e404f46144e121c6242ecfc97bd\",\"User-Agent\":\"PagarMe-Hookshot/1.0\"}",
    "id": "po_civx8ry1r04zz3v73bxkt2gma",
    "model": "transaction",
    "model_id": "888502",
    "next_retry": null,
    "object": "postback",
    "payload": "id=888502&fingerprint=8ba735a3ea0ec86003d2d711eed9a9f0f8eb1072&event=transaction_status_changed&old_status=waiting_payment&desired_status=paid&current_status=paid&object=transaction&transaction%5Bobject%5D=transaction&transaction%5Bstatus%5D=paid&transaction%5Brefuse_reason%5D=&transaction%5Bstatus_reason%5D=acquirer&transaction%5Bacquirer_response_code%5D=&transaction%5Bacquirer_name%5D=pagarme&transaction%5Bauthorization_code%5D=&transaction%5Bsoft_descriptor%5D=&transaction%5Btid%5D=888502&transaction%5Bnsu%5D=888502&transaction%5Bdate_created%5D=2016-11-25T03%3A41%3A35.830Z&transaction%5Bdate_updated%5D=2016-11-25T03%3A42%3A10.642Z&transaction%5Bamount%5D=10000&transaction%5Bauthorized_amount%5D=10000&transaction%5Bpaid_amount%5D=0&transaction%5Brefunded_amount%5D=0&transaction%5Binstallments%5D=1&transaction%5Bid%5D=888502&transaction%5Bcost%5D=380&transaction%5Bcard_holder_name%5D=&transaction%5Bcard_last_digits%5D=&transaction%5Bcard_first_digits%5D=&transaction%5Bcard_brand%5D=&transaction%5Bpostback_url%5D=http%3A%2F%2Frequestb.in%2F18bbyxi1&transaction%5Bpayment_method%5D=boleto&transaction%5Bcapture_method%5D=ecommerce&transaction%5Bantifraud_score%5D=&transaction%5Bboleto_url%5D=https%3A%2F%2Fpagar.me&transaction%5Bboleto_barcode%5D=1234%205678&transaction%5Bboleto_expiration_date%5D=2016-11-28T02%3A00%3A00.824Z&transaction%5Breferer%5D=api_key&transaction%5Bip%5D=188.31.126.157&transaction%5Bsubscription_id%5D=&transaction%5Bphone%5D=&transaction%5Baddress%5D=&transaction%5Bcustomer%5D=&transaction%5Bcard%5D=&transaction%5Bsplit_rules%5D=",
    "request_url": "http://requestb.in/18bbyxi1",
    "retries": 0,
    "signature": "sha1=d3b3576d3c223e404f46144e121c6242ecfc97bd",
    "status": "success"
}

Suggest Edits

Retornando um postback

Retorna um postback específico relacionado a transação.

gethttps://api.pagar.me/1/model/model_id/postbacks/postback_id

Path Params

model

string

required

Model a que o grupo de postbacks pertence. Valores possíveis: transactions, subscriptions ou recipients.

model_id

string

required

ID do model a que este postback pertence.

postback_id

string

required

ID do postback.

curl -X GET https://api.pagar.me/1/transactions/314578/postbacks/po_ciat6ssga0022k06ng8vxg -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY"
}'

PagarMeService.DefaultApiKey = "ak_test_grXijQ4GicOa2BLGZrDRTR5qNQxJW0";
var postback = PagarMeService.GetDefaultService().Transactions.Find("314578").Postbacks.Find("po_ciat6ssga0022k06ng8vxg");

<?php
    require __DIR__.'/vendor/autoload.php';

    date_default_timezone_set('America/Sao_Paulo');
    $pagarMe = new \PagarMe\Sdk\PagarMe('SUA_API_KEY');		

		$transactionId = 1159049;
		$transaction = $pagarMe->transaction()->get($transactionId);

		$postbackId = 'po_ciat6ssga0022k06ng8vxg';
    $postbacks = $pagarMe->postback()->get(
        $transaction,
        $postbackId
    );

const pagarme = require('pagarme')

// From transaction:
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.postbacks.find({ transactionId: 1234, id: 'postback_id' }))

// From subscription:
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.postbacks.find({ subscriptionId: 1234, id: 'postback_id'  }))

import pagarme

pagarme.authentication_key('SUA_API_KEY')

postback = pagarme.transaction.specific_postback("transaction_id", "postback_id")

print (postback)

{{ results.statusCode[0] }} {{ results.statusCode[1] }}

Metadata

to examples

A binary file was returned

You couldn't be authenticated

Method

URL

Request Headers

{{ results.requestHeaders }}

Request Data

{{ results.data }}

Status

Response Headers

{{ results.responseHeaders }}

200 OK

{
        "date_created": "2015-06-12T05:41:57.000Z", 
        "date_updated": "2015-06-12T05:42:07.000Z", 
        "deliveries": [
            {
                "date_created": "2015-06-12T05:42:06.000Z", 
                "date_updated": "2015-06-12T05:42:07.000Z", 
                "id": "pd_ciat6szv2002yk06nyhacqmr4", 
                "object": "postback_delivery", 
                "response_body": "", 
                "response_headers": "{\"cache-control\":\"no-cache\",\"pragma\":\"no-cache\",\"content-length\":\"0\",\"expires\":\"-1\",\"server\":\"Microsoft-IIS/8.0\",\"x-aspnet-version\":\"4.0.30319\",\"x-powered-by\":\"ASP.NET\",\"set-cookie\":[\"ARRAffinity=663d85223525d21e72aebd941082ca482841f5719c27124196939b3de6204504;Path=/;Domain=requestb.in\"],\"date\":\"Fri, 12 Jun 2015 05:42:06 GMT\",\"connection\":\"close\"}", 
                "response_time": 516, 
                "status": "success", 
                "status_code": "200", 
                "status_reason": "http_status_code"
            }
        ], 
        "headers": "{\"Content-Type\":\"application/x-www-form-urlencoded\",\"X-PagarMe-Event\":\"transaction_status_changed\",\"X-Hub-Signature\":\"sha1=d825b60eee7f3034484be584ccca20d3f7bb8c5b\",\"User-Agent\":\"PagarMe-Hookshot/1.0\"}", 
        "id": "po_ciat6ssga0022k06ng8vxg", 
        "model": "transaction", 
        "model_id": "674579", 
        "next_retry": null, 
        "object": "postback", 
        "payload": "id=674579&fingerprint=05112b2b5d756a1501d994027c95d3202c7b&event=transaction_status_changed&old_status=authorized&desired_status=paid&current_status=refused&object=transaction", 
        "request_url": "http://requestb.in/1azqnq81?inspect", 
        "retries": 0, 
        "signature": "d825b60eee7f3034484be584d3f7bb8c5b", 
        "status": "success"
}

Suggest Edits

Validando um postback

Você deve validar a origem do postback, isto é, se ele foi realmente enviado pelo Pagar.me.

Para fazer isso, você deve calcular o HMAC-SHA1 do body da requisição HTTP e compará-lo com o header X-Hub-Signature.

EXPECTED_SIGNATURE=`cat postback_body | openssl dgst -sha1 -hmac "ak_test_grXijQ4GicOa2BLGZrDRTR5qNQxJW0"`
SIGNATURE=1213e67a3b34c2848f8317d29bcb8cbc9e0979b8
if [ "$SIGNATURE" = "$EXPECTED_SIGNATURE" ]; then
    echo "Valid Signature"
fi

require 'pagarme'

PagarMe.api_key = 'ak_test_grXijQ4GicOa2BLGZrDRTR5qNQxJW0';

if PagarMe::Postback.valid_request_signature?(postback_body, '1213e67a3b34c2848f8317d29bcb8cbc9e0979b8')
    puts "Valid Signature"
end

<?php
    require("pagarme-php/Pagarme.php");

    Pagarme::setApiKey("ak_test_grXijQ4GicOa2BLGZrDRTR5qNQxJW0");

    if(PagarMe::validateRequestSignature(postback_body, "1213e67a3b34c2848f8317d29bcb8cbc9e0979b8")) {
        echo "Valid Signature";
    }
?>

const pagarme = require('pagarme')

// Calculate signature:
pagarme.postback.calculateSignature('X-Hub-Signature', 'postbackBody')
// returns a hash

// Verify signature:
pagarme.postback.verifySignature('X-Hub-Signature', 'postbackBody', 'expectedHash')
// returns true or false

Não se esqueça de:

postback_body pelo conteúdo do body da requisição HTTP do postback,
1213e67a3b34c2848f8317d29bcb8cbc9e0979b8 pela signature recebido em X-Hub-Signature,
ak_test_grXijQ4GicOa2BLGZrDRTR5qNQxJW0 pela sua chave de API disponível
no seu Dashboard.

A X-Hub-Si

Você tem certeza de que está na versão correta da documentação?

Paginação

Autenticação

Cuidado com as suas chaves de API

Query Auth

Body Params

Transações recusadas

Não guardamos CVV

Campo 'session'

Transação síncrona com postback

card_hash

Boletos

Antifraude

Parâmetro local_time

Análise manual pelo antifraude

Metadata

Metadata 2

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

Query Auth

Path Params

Query Params

O que é uma captura?

Captura de uma transação

Restrições ao tempo para captura de uma transação

Tempo para captura de uma transação

Captura em transações de boleto

Captura de boleto

Captura parcial

Valores para captura

Query Auth

Path Params

Body Params

Query Auth

Path Params

Body Params

Query Auth

Path Params

Body Params

Query Auth

Query Params

Filtros

Filtro de data

Query Auth

Path Params

Retornando uma transação com Reference Key

Query Auth

Path Params

Status de um recebível

Transação por boleto

Query Auth

Path Params

Query Auth

Path Params

Exemplo de retorno

Significado de cada propriedade

Query Auth

Path Params

Body Params

Somente produção

Query Auth

Path Params

Query Auth

Query Params

Juros?

Query Auth

Path Params

Body Params

Cadê o link do boleto?

Query Auth

Utilizando a Pagar.me JS

Passo a passo

1. Gerando uma nova chave para encriptação

2. Encriptando os dados do cartão de crédito

Por que preciso do card_hash?

Query Auth

Query Params

Estornos

Query Auth

Body Params

One Click Buy