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

Dividindo uma transação

Usando as split rules

Para que os valores de uma transação sejam divididos entre 2 ou mais recebedores, você precisa especificar algumas regras, que aqui chamamos de split rules. Elas ditam quem são os envolvidos em uma transação, quanto cada um recebe e quais são as responsabilidades deles.

Veja agora um exemplo de como criar uma transação com split e, em seguida, entenda melhor o que cada parâmetro significa.

Criando uma transação com split

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
      }
    ],
    "split_rules": [
        {
          "recipient_id": "re_cj6cglnhc0bbcbt6dbsl8fdcs",
          "percentage": 50,
          "liable": true,
          "charge_processing_fee": true
        },{
          "recipient_id": "re_cj6cgqzy31irpmx6dj9h3xdln",
          "percentage": 50,
          "liable": true,
          "charge_processing_fee": 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
      }
    ],
    "split_rules": [
        {
          "recipient_id": "re_cj6cglnhc0bbcbt6dbsl8fdcs",
          "percentage": 50,
          "liable": true,
          "charge_processing_fee": true
        },{
          "recipient_id": "re_cj6cgqzy31irpmx6dj9h3xdln",
          "percentage": 50,
          "liable": true,
          "charge_processing_fee": true
        }
      ]
}

trx = pagarme.transaction.create(params)

print(trx)
using System;
using PagarMe;

PagarMeService.DefaultApiKey = "ak_test_9c0AUwmQm9EAcMTGM3zRd5y6GzfuWo";
PagarMeService.DefaultEncryptionKey = "ek_test_UGvmO3DbRwGeHYc3gEMnUtRCrF3M9z";

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
  }
};

 t.SplitRules = new[]
 {
   new SplitRule {
     Recipient = r1,
     Percentage = 10,
     ChargeProcessingFee = true,
     Liable = true
   },
   new SplitRule {
     Recipient = r2,
     Percentage = 40,
     ChargeProcessingFee = false,
     Liable = false
   },
   new SplitRule {
     Recipient = r3,
     Percentage = 50,
     ChargeProcessingFee = false,
     Liable = false
   }
 };

transaction.Save();
<?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
    ]
  ],
  'split_rules' => [
    [
      'id' => 'sr_cj41w9m4d01ta316d02edaqav',
      'amount' => '3000',
      'recipient_id' => 're_cj2wd5ul500d4946do7qtjrvk'
    ],
    [
      'id' => 'sr_cj41w9m4e01tb316dl2f2veyz',
      'amount' => '3153',
      'recipient_id' => 're_cj2wd5u2600fecw6eytgcbkd0',
      'charge_processing_fee' => 'true'
    ]
  ]
]);

Passando split no momento de captura

Você pode também passar as regras de split no momento de captura de uma transação:

curl -X POST https://api.pagar.me/1/transactions/:id/capture -H "Content-Type: application/json"
-d '{
    "api_key"="SUA_API_KEY",
  "split_rules": [
    {
      "recipient_id": "re_civb4p9l7004xbm6dhsetkpj8",
      "percentage": 50,
      "liable": true,
      "charge_processing_fee": true
    },{
      "recipient_id": "re_civb4o6zr003u3m6e8dezzja6",
      "percentage": 50,
      "liable": true,
      "charge_processing_fee": true
    }
  ]
}'
require 'pagarme'

PagarMe.api_key = 'SUA_API_KEY'

tx_to_capture = PagarMe::Transaction.find_by_id("test_token_xxx")
tx_to_capture.capture(
    split_rules: [
    {
      recipient_id: "re_civb4p9l7004xbm6dhsetkpj8",
      percentage: 50,
      liable: true,
      charge_processing_fee: true
    },{
      recipient_id: "re_civb4o6zr003u3m6e8dezzja6",
      percentage: 50,
      liable: true,
      charge_processing_fee: true
    }
  ]
)
<?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' => 1000,
  'split_rules' => [
    [
      'amount' => '3000',
      'recipient_id' => 're_cj2wd5ul500d4946do7qtjrvk'
      'charge_processing_fee' => true,
      'liable' => true
    ],
    [
      'amount' => '70',
      'recipient_id' => 're_cj2wd5u2600fecw6eytgcbkd0',
      'charge_processing_fee' => 'true',
      'charge_processing_fee' => true,
      'liable' => true
    ]
  ]
]);
No momento não temos essa funcionalidade :(
const pagarme = require('pagarme')
pagarme.client.connect({ api_key: 'SUA_API_KEY' })
.then(client => client.transactions.capture({
    id: 6010225,
    amount: 100,
    split_rules: [
        {
          recipient_id: 'ID_DO_RECEBEDOR',
          percentage: 50,
          liable: true,
          charge_processing_fee: true
        },
        {
          recipient_id: 'ID_DO_RECEBDOR',
          percentage: 50,
          liable: false,
          charge_processing_fee: true
        }
      ]
}))
.then(transaction => console.log(transaction))
.catch(exception => console.log(exception.response))
No momento não temos essa funcionalidade :(
import pagarme

pagarme.authentication_key('SUA_API_KEY')

default_recipient = pagarme.recipient.default_recipient()

params_capture = {
    'amount': '10000',
    'split_rules': [
        {
            'recipient_id': default_recipient['test'],
            'percentage': 50,
            'liable': 'true',
            'charge_processing_fee': 'true'
        },
        {
            'recipient_id': 'RECIPIENT_ID',
            'percentage': 50,
            'liable': 'true',
            'charge_processing_fee': 'true'
        }
    ]
}

captured_trx = pagarme.transaction.capture(trx['id'], params_capture)

print (captured_trx)

Parâmetros de uma split rule

Vamos agora ao significado de cada parâmetro:

Parâmetro

Significado

Formatos válidos e restrições

recipient_id

id de um recebedor

charge_processing_fee
Default: true

indica se o recebedor vinculado à regra será cobrado pelas taxas da transação

Ao menos um dos recebedores deve ter esse parâmetro true

liable
Default: true

indica se o recebedor atrelado assumirá os riscos de chargeback da transação

Ao menos um dos recebedores deve ter esse parâmetro true

amount

valor em centavos de quanto da transação irá para o recebedor.

percentage

valor em porcentagem de quanto da transação irá para o recebedor.

Sempre inteiro, ou seja, não é possível especificar porcentagem quebrada, e.g: 81.34

charge_remainder
Default: true para o primeiro recipient do conjunto de split rules

no caso de restos de divisão de taxas entre os dois recebedores exista, aquele com esse parâmetro 'true' será cobrado desses centavos

Por padrão, vai para o primeiro recebedor.

Observações

📘

Onde e quando posso usar as split rules?

As split rules atualmente podem ser usadas durante o processo de criação de transações, especificamente em duas fases: Na criação ou na captura da transação.

Além disso, você pode usar split rules também na criação de assinaturas. Saiba mais em: Criando assinaturas

🚧

O que usar? Percentage ou Amount?

Dentro das split rules, você deve passar apenas amount ou percentage — não usar os dois ao mesmo tempo.

🚧

Caso escolha usar o amount em sua regra de split:

A soma de amount de cada split rule deve ser igual ao amount da transação em si.

🚧

Recebedor principal e outros:

É preciso explicitamente definir todos os recebedores que irão participar da transação, pois a API Pagar.me não vai inferir que recebedor X está presente na divisão.

📘

Existe split de boleto?

Sim, a mesma regra se aplica a transações de boleto, basta especificar as split rules desejadas.

🚧

Custos de gateway e antifraude

Os custos de gateway e antifraude são de responsabilidade do marketplace (recebedor principal), não podendo ser dividido via regras de divisão.

🚧

Custo de saque

O custo de saque é de responsabilidade do recebedor, não podendo ser dividido via regras de divisão.

Relação de recebíveis de uma transação com split

Caso a compra tenha mais de um installment (parcela), serão criados (installments * número de recebedores) recebíveis. Mais sobre em: Objeto-resposta Recebível

Você pode também visualizar em sua Dashboard o resultado final da regra de split, assim como quais os custos com que cada recebedor arca, o seu valor a receber e a responsabilidade por um eventual chargeback:

Marketplace com plataformas

Atualmente, as integrações disponibilizadas pelo Pagar.me para as plataformas Woocommerce e Magento não possuem suporte para utilizar nossa funcionalidade de Marketplace.

Para as demais integrações consulte o responsável por sua plataforma.

Updated 2 months ago


Próximo

Está pronto para começar a aprender mais sobre a Recorrência do Pagar.me? Então vamos!

Overview

Dividindo uma transação


Suggested Edits are limited on API Reference Pages

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