Bem-vindo à documentação pagar.me

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

Começar

Você também pode buscar ou navegar pelas categorias

Usando Metadata

Ao criar transações usando a API Pagar.me, você pode usar um recurso chamado metadata. Esse parâmetro permite enviar informações adicionais sobre a transação, como o ID do pedido na sua plataforma, tipo de produto/serviço adquirido etc. Existem milhares de combinações possíveis, que dependem única e exclusivamente do que faz mais sentido para o seu negócio.

Em resumo, o parâmetro metadata é mais uma forma de individualizar as suas transações para facilitar o controle posterior no seu sistema.

É possível atrelar o metadata à transação em duas situações: na criação e na captura.

1. Metadata na criação

Para usar o metadata já na criação da transação, basta passar os parâmetros desse recurso na requisição, como mostra esse exemplo:

curl -X POST 'https://api.pagar.me/1/transactions' -H 'content-type: application/json' -d '{
    "amount": "1000", 
    "api_key": "ak_test_grXijQ4GicOa2BLGZrDRTR5qNQxJW0", 
    "metadata": {
        "pedido": {
            "product": {
                "cost": "2500", 
                "name": "Swimming Cap"
            }
        }
    }, 
    "payment_method": "boleto"
}'
require 'pagarme'

PagarMe.api_key = "SUA_API_KEY";

transaction = PagarMe::Transaction.new({
    :amount => 1000,
    :payment_method => "boleto",
    :metadata => {
        :pedido => {
            :name => "Swimming Cap",
            :cost => 100
        }
    }
})

transaction.charge
import pagarme from 'pagarme'

pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.transactions.create({
    amount: 100,
    payment_method: 'credit_card',
    card_number: '4111111111111111',
    card_holder_name: 'abc',
    card_expiration_date: '1225',
    card_cvv: '123',
    metadata: {
      produto: {
        id: '13933139',
        nome: 'carrinho'
      }
    }
  }))
<?php
require("vendor/autoload.php");
$pagarme = new PagarMe\Client('SUA_CHAVE_DE_API');

$transaction = $pagarme->transactions()->create([
  'amount' => 1000,
  'payment_method' => 'credit_card',
  'card_holder_name' => 'Anakin Skywalker',
  'card_cvv' => '123',
  'card_number' => '4242424242424242',
  'card_expiration_date' => '1220',
  'customer' => [
    'external_id' => '1',
    'name' => 'Nome do cliente',
    'type' => 'individual',
    'country' => 'br',
    'documents' => [
      [
        'type' => 'cpf',
        'number' => '00000000000'
      ]
    ],
    'phone_numbers' => [ '+551199999999' ],
    'email' => '[email protected]'
  ],
  'billing' => [
    'name' => 'Nome do pagador',
    'address' => [
      'country' => 'br',
      'street' => 'Avenida Brigadeiro Faria Lima',
      'street_number' => '1811',
      'state' => 'sp',
      'city' => 'Sao Paulo',
      'neighborhood' => 'Jardim Paulistano',
      'zipcode' => '01451001'
    ]
  ],
  'shipping' => [
    'name' => 'Nome de quem receberá o produto',
    'fee' => 1020,
    'delivery_date' => '2018-09-22',
    'expedited' => false,
    'address' => [
      'country' => 'br',
      'street' => 'Avenida Brigadeiro Faria Lima',
      'street_number' => '1811',
      'state' => 'sp',
      'city' => 'Sao Paulo',
      'neighborhood' => 'Jardim Paulistano',
      'zipcode' => '01451001'
    ]
  ],
  'items' => [
    [
      'id' => '1',
      'title' => 'R2D2',
      'unit_price' => 300,
      'quantity' => 1,
      'tangible' => true
    ],
    [
      'id' => '2',
      'title' => 'C-3PO',
      'unit_price' => 700,
      'quantity' => 1,
      'tangible' => true
    ]
  ],
  'metadata' => [
    'pedido'=> [
      'product' => [
        'cost' => "$15003",
        'name' => "Swimming Cap"
      ]
    ]
  ]
]);
using System;
using PagarMe;
using System.Collections.Generic;

PagarMe.PagarMeService.DefaultApiKey = "SUA_API_KEY";
PagarMe.PagarMeService.DefaultApiEndpoint = "https://api.pagar.me/1";

Transaction transaction = new Transaction();

transaction.Amount = 100;
transaction.PaymentMethod = PaymentMethod.Boleto;
transaction.Customer = new Customer () {
  Name = "Aardvark Silva",
  Email = "[email protected]",
  DocumentNumber = "18152564000105",
  Address = new Address () {
    Street = "Avenida Brigadeiro Faria Lima",
    StreetNumber = "123",
    Neighborhood = "Jardim Paulistano",
    Zipcode = "01451001"
  },

  Phone = new Phone () {
    Ddi = "55",
    Ddd = "11",
    Number = "23456789"
  }
};
transaction.Metadata ["pedido"] = new Dictionary<string, object> 
{
  ["product"] = new Dictionary<string, object>
  {
    ["name"] = "Swimming Cap",
    ["cost"] = "100"
  }
};

transaction.Save();
import pagarme

pagarme.authentication_key('SUA_API_KEY')

params = {
  'amount': '10000',
  'payment_method': 'boleto',
  'customer': {
    'email': '[email protected]',
    'name': 'Daenerys Targaryen',
    'document_number': '18152564000105',
    'address': {
        'zipcode': '04571020',
        'neighborhood': 'Dragon Village',
        'street': 'Rua Drogon',
        'street_number': '240'
    },
    'phone': {
      	'number': '987654321',
        'ddd': '11'
    }
  },
  'metadata': {
    'command':'Dracarys'
  }
}
trx = pagarme.transaction.create(params)

print(trx)

Dessa forma, automaticamente a nossa API vai montar o objeto para você e retornar algo como:

{
    "acquirer_id": "56f9d019decf72cc70055d58",
    "acquirer_name": "pagarme",
    "acquirer_response_code": null,
    "address": null,
    "amount": 15003,
    "antifraud_metadata": {},
    "antifraud_score": null,
    "authorization_code": null,
    "authorized_amount": 15003,
    "boleto_barcode": "1234 5678",
    "boleto_expiration_date": "2017-04-02T03:00:00.000Z",
    "boleto_url": "https://pagar.me",
    "capture_method": "ecommerce",
    "card": null,
    "card_brand": null,
    "card_first_digits": null,
    "card_holder_name": null,
    "card_last_digits": null,
    "card_pin_mode": null,
    "cost": 0,
    "customer": null,
    "date_created": "2017-03-29T01:39:40.475Z",
    "date_updated": "2017-03-29T01:39:40.880Z",
    "id": 1399405,
    "installments": 1,
    "ip": "188.72.120.20",
    "metadata": {
        "pedido": {
            "product": {
                "cost": "$15003",
                "name": "Swimming Cap"
            }
        }
    },
    "nsu": 1399405,
    "object": "transaction",
    "paid_amount": 0,
    "payment_method": "boleto",
    "phone": null,
    "postback_url": null,
    "referer": "api_key",
    "refunded_amount": 0,
    "refuse_reason": null,
    "soft_descriptor": null,
    "split_rules": null,
    "status": "waiting_payment",
    "status_reason": "acquirer",
    "subscription_id": null,
    "tid": 1399405
}

2. Metadata na captura

Quando uma transação é autorizada, no momento da captura da mesma é possível passar um metadata:

curl -X POST -H "Content-Type: application/json" -d '{
	"api_key": "SUA_API_KEY",
  "amount": 1000,
	"metadata": {
		"produto": {
			"name": "Swimming Cap",
			"cost": 100
		}
	}
}' "https://api.pagar.me/1/transactions/1542957/capture" -H 'content-type: application/json' -d '{}'
require 'pagarme'

PagarMe.api_key = 'SUA_API_KEY'

transaction.capture({
	:amount => 1000,
	:metadata => {
		:produto => {
			:name => "Swimming Cap",
			:cost => 1000
		}
	}
})
<?php
require __DIR__ . '/vendor/autoload.php';
$pagarme = new PagarMe\Client('SUA_CHAVE_DE_API');  
$transaction = $pagarme->transactions()->capture([
  "amount" => 100,
  "metadata" => [
    "produto" => [
      "name" => "Swimming Cap",
      "cost" => 100
    ]
  ]
]);
Ainda não temos essa feature :(
import pagarme

pagarme.authentication_key("SUA_API_KEY")

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

metadata = {
  "metadata": {
    "id_pedido": "13933139"
  } 
}

capture = pagarme.transaction.capture(
  	transaction[0]['id'],
  	metadata
}
print(capture)

Formato

Você deve manter o tipo de dado em um metadata sempre o mesmo, ou seja, uma chave que era um array, não pode virar um integer na próxima request. Exemplo:

Era:

metadata: {
    "pedido" : {
         "name" : "Swimming cap"
    }
}

Não pode virar:

metadata: {
   "pedido": 1234
}

Se você quiser mudar isso, é preciso passar um novo campo dentro do metadata.

Updated 7 months ago


Próximo

Excelente, agora você já sabe quase tudo de transações. Falta apenas aprender como estornar uma transação, vamos lá!

Estorno

Usando Metadata


Suggested Edits are limited on API Reference Pages

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