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.

1. Metadata na criação

2. Metadata na captura

🚧Formato

🚧
Formato