Guides
GuidesSuporteAPI Reference

Cartão de crédito

Suggest Edits

❗️

Você 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.

Realizando uma transação

Após obter os dados do cartão, gerar o card_hash e enviá-lo para o seu servidor, você deve realizar a transação junto à API Pagar.me, que então efetua o fluxo de cobrança no cartão do cliente.

Abaixo você encontrará o exemplo de uma transação de cartão de crédito de uma companhia com o antifraude habilitado.

📘

Quando submeter informações sobre o comprador?

Os campos customer, billing e items são obrigatórios no caso de transações de cartão de crédito de companhias com o antifraude habilitado. O campo shipping é opcional e deve ser preenchido no caso da venda de um bem físico. Para mais informações, clique aqui

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": "[email protected]",
      "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
      }
    ]
}'

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": "[email protected]",
      "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 = "SUA_CHAVE_DE_API";
PagarMeService.DefaultEncryptionKey = "SUA_CHAVE_DE_CRIPTOGRAFIA";

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 = "[email protected]",
  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()

<?php
$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
    ]
  ]
]);

É dessa forma que você consegue criar uma transação de cartão de crédito. Viu como é simples? ;-)

Parâmetros de uma transação

Descrição dos parâmetros passados no exemplo:

ParâmetroPadrãoDescrição
amountValor total a ser cobrado (em centavos). Ex: R$14,99 = 1499
card_hashRepresentação segura dos dados de cartão de crédito
installments1Número de parcelas a serem cobradas no cartão de crédito
payment_methodcredit_cardMeio de pagamento que será utilizado
postback_urlURL para receber notificações sobre alterações no status da transação
soft_descriptorTexto (de até 13 caracteres, somente letras e números) que aparecerá na fatura do cartão do cliente ao lado do nome da sua loja
customerObjeto que deve possuir as informações do cliente. Obrigatório com o antifraude habilitado. Para mais informações, clique aqui
billingObjeto que deve possuir as informações de cobrança da transação. Obrigatório com o antifraude habilitado. Para mais informações, clique aqui
shippingObjeto que deve possuir as informações de envio do que foi comprado. Deve ser preenchido no caso da venda de um bem físico. Para mais informações, clique aqui
itemsObjeto que deve possuir as informações sobre os produtos comprados. Obrigatório com o antifraude habilitado. Para mais informações, clique aqui
metadataObjeto JSON para você receber dados de sua plataforma, como: id do pedido, descrição do produto/serviço, etc
sessionValor único que identifica a sessão do usuário acessando o site

Aprenda mais sobre a lista completa de parâmetros em: Criar transação

Observações

card_hash

🚧

Vale ressaltar:

Após gerado, o card_hash tem validade de 5 minutos. Além disso, ele pode ser utilizado uma única vez.

Análises antifraude com transações assíncronas

❗️

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.

Dados de customer

🚧

Por que passar os dados do cliente (customer, billing, shipping e items) na transação?

São dados essenciais para que o antifraude consiga avaliar a transação e evitar compras ilegítimas.

Ao usar os exemplos

🚧

Mudança de API KEY:

Não se esqueça de substituir ak_test_grXijQ4GicOa2BLGZrDRTR5qNQxJW0 pela sua Chave de API, que está disponível em sua Dashboard.

Status de uma transação após ser criada

Após realizar uma transação de Cartão de crédito, ela fica com o status paid, indicando que o cartão do usuário foi debitado com sucesso. No entanto, caso ela seja recusada pelo banco emissor, fica com o status refused. Você pode aprender mais sobre os possíveis status de uma transação em: Status das transações

Simulações em teste

Como simular uma transação recusada pelo banco emissor?

📘

Testando transações recusadas

No ambiente de testes, você pode simular uma transação recusada pelo banco emissor. Basta passar um card_cvv que começa com o número 6.

Como simular uma transação recusada pelo antifraude ?

📘

Testando transação recusada por antifraude

Você pode fazer este teste passando um document_number igual à 11111111111.

Capturando uma transação posteriormente

Com a API Pagar.me, você pode separar o processo de autorização (reserva de saldo no cartão) e captura (confirmação para cobrança em fatura). Isso é feito através de um parâmetro chamado capture.

O primeiro passo é passar este parâmetro como false no momento da criação de uma transação, como é mostrado nesse exemplo: 

curl -X POST 'https://api.pagar.me/1/transactions' -H 'content-type: application/json' -d '{
    "api_key": "SUA_API_KEY",
    "capture": "false", 
    "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": "[email protected]",
      "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
      }
    ]
}'

<?php
$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',
  'capture' => false,
  '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
    ]
  ]
]);

Desta forma, a API Pagar.me retorna uma transação com status authorized, assim como no exemplo a seguir:

{
    "object": "transaction",
    "status": "authorized",
    "refuse_reason": null,
    "status_reason": "acquirer",
    "acquirer_response_code": "0000",
    "acquirer_name": "pagarme",
    "acquirer_id": "58a49047916d40fa539ba926",
    "authorization_code": "421974",
    "soft_descriptor": null,
    "tid": 1828542,
    "nsu": 1828542,
    "date_created": "2017-08-14T17:35:40.242Z",
    "date_updated": "2017-08-14T17:35:40.501Z",
    "amount": 21000,
    "authorized_amount": 21000,
    "paid_amount": 0,
    "refunded_amount": 0,
    "installments": 1,
    "id": 1828542,
    "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": 232990,
        "external_id": "#3311",
        "type": "individual",
        "country": "br",
        "document_number": null,
        "document_type": "cpf",
        "name": "Morpheus Fishburne",
        "email": "[email protected]",
        "phone_numbers": [
            "+5511999998888",
            "+5511888889999"
        ],
        "born_at": null,
        "birthday": "1965-01-01",
        "gender": null,
        "date_created": "2017-08-14T17:35:40.125Z",
        "documents": [
            {
                "object": "document",
                "id": "doc_cj6cfx08k0ah6cm6eq0lxx9th",
                "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": 145689
        },
        "object": "billing",
        "id": 27,
        "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": 145690
        },
        "object": "shipping",
        "id": 23,
        "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,
            "venue": null,
            "date": null
        },
        {
            "object": "item",
            "id": "b123",
            "title": "Blue pill",
            "unit_price": 10000,
            "quantity": 1,
            "category": null,
            "venue": null,
            "date": null
        }
    ],
    "card": {
        "object": "card",
        "id": "card_cj6cfx0au0ah7cm6e2uhdgkcj",
        "date_created": "2017-08-14T17:35:40.230Z",
        "date_updated": "2017-08-14T17:35:40.561Z",
        "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
}

Chamada para fazer a captura

Posteriormente, você pode confirmar e pedir a captura. É importante lembrar que isso precisa ser feito até 5 dias após a autorização. Confirme a captura com a seguinte chamada:

curl -X POST https://api.pagar.me/1/transactions/:id/capture -H 'content-type: application/json' -d '{
    "api_key": "SUA API KEY"
}'

require 'pagarme'

PagarMe.api_key = 'SUA API KEY'

transaction = PagarMe::Transaction.find 123
transaction.capture()

<?php
require("vendor/autoload.php");
$pagarme = new PagarMe\Client('SUA_CHAVE_DE_API');

$capturedTransaction = $pagarme->transactions()->capture([
  'id' => 'ID_OU_TOKEN_DA_TRANSAÇÃO',
  'amount' => VALOR_TOTAL_EM_CENTAVOS
]);

PagarMeService.DefaultApiKey = "SUA API KEY";

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

transaction.Capture();

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

import me.pagar.model.Address;
import me.pagar.model.Customer;
import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Phone;
import me.pagar.model.Transaction;
import me.pagar.model.Transaction.PaymentMethod;

PagarMe.init("SUA_API_KEY");

Transaction transaction = new Transaction().find(194351);
transaction.capture(1000);

import pagarme from 'pagarme'

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

import pagarme

pagarme.authentication_key("SUA_API_KEY")

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

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

Perceba que, no caminho da request, é necessário especificar o ID da transação que foi criada anteriormente.

Captura parcial

Também pela API Pagar.me é possível especificar o quanto você gostaria de efetivamente capturar desta transação. Para isso você precisa apenas especificar o parâmetro amount, como no exemplo a seguir:

curl -X POST https://api.pagar.me/1/transactions/:id/capture -H 'content-type: application/json' -d '{
    "amount": "10000", 
    "api_key": "SUA API KEY"
}'

require 'pagarme'

PagarMe.api_key = 'SUA API KEY'

transaction = PagarMe::Transaction.find 123
transaction.capture(amount: 6234)

<?php
require("vendor/autoload.php");
$pagarme = new PagarMe\Client('SUA_CHAVE_DE_API');

$capturedTransaction = $pagarme->transactions()->capture([
  'id' => 'ID_OU_TOKEN_DA_TRANSAÇÃO',
  'amount' => VALOR_PARCIAL_EM_CENTAVOS
]);

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

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

  $amount = "6234";
  $transaction = $pagarMe->transaction()->get(194351);
  $transaction = $pagarMe->transaction()->capture(
    $transaction,
    $amount
  );

PagarMeService.DefaultApiKey = "SUA API KEY";

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

transaction.Capture(6234);

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

import me.pagar.model.Address;
import me.pagar.model.Customer;
import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Phone;
import me.pagar.model.Transaction;
import me.pagar.model.Transaction.PaymentMethod;

PagarMe.init("SUA_API_KEY");

Transaction transaction = new Transaction().find(194351);
transaction.capture(6234);

import pagarme from 'pagarme'

pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.transactions.capture({
    id: 1399451,
    amount: 6234
  }))

import pagarme

pagarme.authentication_key("SUA_API_KEY")

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

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

Quando uma captura parcial é feita, você consegue ver o resultado refletido no campo paid_amount da transaction, como o exemplo a seguir:

{
    "object": "transaction",
    "status": "paid",
    "refuse_reason": null,
    "status_reason": "acquirer",
    "acquirer_response_code": "0000",
    "acquirer_name": "pagarme",
    "acquirer_id": "58a49047916d40fa539ba926",
    "authorization_code": "421974",
    "soft_descriptor": null,
    "tid": 1828542,
    "nsu": 1828542,
    "date_created": "2017-08-14T17:35:40.242Z",
    "date_updated": "2017-08-14T17:47:07.370Z",
    "amount": 21000,
    "authorized_amount": 21000,
    "paid_amount": 10000,
    "refunded_amount": 0,
    "installments": 1,
    "id": 1828542,
    "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": 232990,
        "external_id": "#3311",
        "type": "individual",
        "country": "br",
        "document_number": null,
        "document_type": "cpf",
        "name": "Morpheus Fishburne",
        "email": "[email protected]",
        "phone_numbers": [
            "+5511999998888",
            "+5511888889999"
        ],
        "born_at": null,
        "birthday": "1965-01-01",
        "gender": null,
        "date_created": "2017-08-14T17:35:40.125Z",
        "documents": [
            {
                "object": "document",
                "id": "doc_cj6cfx08k0ah6cm6eq0lxx9th",
                "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": 145689
        },
        "object": "billing",
        "id": 27,
        "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": 145690
        },
        "object": "shipping",
        "id": 23,
        "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,
            "venue": null,
            "date": null
        },
        {
            "object": "item",
            "id": "b123",
            "title": "Blue pill",
            "unit_price": 10000,
            "quantity": 1,
            "category": null,
            "venue": null,
            "date": null
        }
    ],
    "card": {
        "object": "card",
        "id": "card_cj6cfx0au0ah7cm6e2uhdgkcj",
        "date_created": "2017-08-14T17:35:40.230Z",
        "date_updated": "2017-08-14T17:35:40.561Z",
        "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
}

🚧

Vale ressaltar

A captura parcial só é permitida para transações criadas usando uma API Key, tanto para cartão de crédito ou boleto.

Logo, para transações feitas com o Checkout Pagar.Me, o valor de captura deve ser sempre igual ao total do carrinho de compras em sua plataforma.

Captura com split rules e metadata

Em um Marketplace, é no momento da captura que você precisa passar os dados de Split Rules — isto é, as regras de divisão de uma transação.

Além disso, é também na captura que você precisa enviar os parâmetros de metadata com informações de sua plataforma. Veja os exemplos:

curl -X POST -H "Content-Type: application/json"  -d '{
  "api_key":"SUA API KEY",
  "split_rules": [
    {
      "recipient_id": "re_ciyol0qac00xnlg6dkaftvn9j",
      "percentage": 55,
      "liable": true,
      "charge_processing_fee": true
    },{
      "recipient_id": "re_ciyoloogb0100l46dy6f1iuww",
      "percentage": 45,
      "liable": false,
      "charge_processing_fee": false
    }
  ],
  "metadata": {
       "id_pedido": "13933139"
   }
}' "https://api.pagar.me/1/transactions/:id/capture" -H 'content-type: application/json' -d '{}'

require 'pagarme'

PagarMe.api_key = 'SUA API KEY'

transaction = PagarMe::Transaction.find 123
transaction.capture({
  split_rules: [
    {
      recipient_id: 're_ciyoloogb0100l46dy6f1iuww',
      liable: true,
      charge_processing_fee: true,
      percentage: 55
    },
    {
      recipient_id: 're_ciyol0qac00xnlg6dkaftvn9j',
      liable: false,
      charge_processing_fee: false,
      percentage: 45
    }
  ],
  metadata: {
    id_pedido: '13933139'  
  }
})

<?php
require("vendor/autoload.php");

$pagarme = new PagarMe\Client('SUA_CHAVE_DE_API');

$capturedTransaction = $pagarme->transactions()->capture([
  "id" => 'ID_OU_TOKEN_DA_TRANSAÇÃO',
  "split_rules" => [
    [
      "recipient_id" => "re_ciyoloogb0100l46dy6f1iuww",
      "liable" => "true",
      "charge_processing_fee" => "true",
      "percentage" => "55",
    ],
    [
      "recipient_id" => "re_ciyol0qac00xnlg6dkaftvn9j",
      "liable" => "false",
      "charge_processing_fee" => "false",
      "percentage" => "45",    
    ] 
  ],
  "metadata" => [
    "id_pedido" => "13933139"
  ]
]);

Feature ainda não disponível para esse SDK

Feature ainda não disponível para esse SDK

import pagarme from 'pagarme'

pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.transactions.capture({
    id: 1399451,
    split_rules: [
      {
        'recipient_id': 're_ciyoloogb0100l46dy6f1iuww',
        'liable': 'true',
        'charge_processing_fee': 'true',
        'percentage': '55',
      },
      {
        'recipient_id': 're_ciyol0qac00xnlg6dkaftvn9j',
        'liable': 'false',
        'charge_processing_fee': 'false',
        'percentage': '45',
      }
    ],
    metadata: {
      'id_pedido': '13933139'
    }
  }))

import pagarme

pagarme.authentication_key("SUA_API_KEY")

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

params = {
	"split_rules": [
    {
      "recipient_id": "re_ciyol0qac00xnlg6dkaftvn9j",
      "percentage": 55,
      "liable": true,
      "charge_processing_fee": true
    },{
      "recipient_id": "re_ciyoloogb0100l46dy6f1iuww",
      "percentage": 45,
      "liable": false,
      "charge_processing_fee": false
    }
  ],
  "metadata": {
       "id_pedido": "13933139"
   }
} 

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

Criando um cartão para one-click buy

Com a API Pagar.me você consegue criar um cartão para possíveis cobranças posteriores em transações e assinaturas. Para fazer isso, você precisa primeiramente de um card_hash, como mostra o exemplo a seguir:

curl -X POST 'https://api.pagar.me/1/cards' -H 'content-type: application/json' -d '{
    "api_key": "ak_test_grXijQ4GicOa2BLGZrDRTR5qNQxJW0", 
    "card_hash": "CARD_HASH"
}'

require 'pagarme'

PagarMe.api_key = 'SUA API KEY'

card = PagarMe::Card.create(card_hash: 'CARD_HASH_GERADO')

<?php
require("vendor/autoload.php");

$pagarme = new PagarMe\Client('SUA_CHAVE_DE_API');

$card = $pagarme->cards()->create([
  'holder_name' => 'Yoda',
  'number' => '4242424242424242',
  'expiration_date' => '1225',
  'cvv' => '123'
]);

PagarMeService.DefaultApiKey = "ak_test_grXijQ4GicOa2BLGZrDRTR5qNQxJW0";
PagarMeService.DefaultEncryptionKey = "ek_test_Ec8KhxISQ1tug1b8bCcxC2nXfxqRnk";

Card card = new Card();
card.Number = "4242424242424242";
card.HolderName = "API CUSTOMER";
card.ExpirationDate = "0117";
card.Cvv = "314";

//O próprio SDK vai gerar o card_hash, antes de enviar a API
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("4242424242424242");
card.setHolderName("API CUSTOMER");
card.setExpiresAt("1219");
card.setCvv(314);
card.save();

const pagarme = require('pagarme')

pagarme.client.connect({ api_key: 'SUA API KEY' })
    .then(client => client.cards.create({
        card_number: '4242424242424242',
        card_holder_name: 'Aardvark Silva',
        card_expiration_date: '1225',
        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))

O que todos estes exemplos retornam em comum é um card_id, dado que funciona como um ID para o cartão criado. Com ele, você consegue criar transações e assinaturas da mesma maneira que faz com card_hash. Exemplo de Card ID: card_cj2ebvhnm011lkd6dj683vn0j

As vantagens de um Card ID

  • Ele pode ser usado indefinidamente, ou enquanto o cartão em si tenha validade com o banco emissor.
  • Pode ser armazenado em sua base de dados, pois não expira após 5 minutos como acontece com o Card Hash.

Updated over 5 years ago

Próximo

Legal, você aprendeu sobre todos os aspectos que envolvem transações com cartão de crédito, que tal ver agora como criar uma transação por boleto?