GuidesSuporteAPI Reference

Usando Metadata

Suggest Edits

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 __DIR__ . '/vendor/autoload.php';
$pagarme = new PagarMe\Client('SUA_CHAVE_DE_API');

$transaction = $pagarme->transactions()->create([
  "amount" => 100,
  "payment_method" => "boleto",
  "customer" => [
    "name" => "Aardvark Silva", 
    "document_number" => "18152564000105",
    "email" => "[email protected]",
    "address" => [
      "street" => "Avenida Brigadeiro Faria Lima", 
      "street_number" => "1811",
      "neighborhood" => "Jardim Paulistano",
      "zipcode" => "01451001"
    ],
    "phone" =>  [
      "ddi" => "55",
      "ddd" => "11",
      "number" => "99999999" 
    ]
  ],
  "metadata" => [
    "produto" => [
      "name" => "Swimming Cap",
      "cost" => 100
    ]
  ]
]);

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();

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 :(

🚧

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
}

Caso queira mudar, você precisará passar um novo campo dentro do metadata.

📘

Plataformas de e-commerce

Caso você tenha integração com nossos módulos de plataformas com Magento ou WooCommerce por exemplo, não é possível usar o metadata. Isso é apenas possível caso sua aplicação possua desenvolvimento próprio, ou seja, sem as plataformas de e-commerce.

Updated over 2 years ago

Próximo

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