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",
  "card_number": "4242424242424242",
  "card_cvv": "122",
  "card_holder_name": "Aardvark Silva",
  "card_expiration_date": "1220",
  "customer":{
    "email":"[email protected]",
    "name":"nome",
    "document_number":"35965816804",
    "address":{
      "zipcode":"01451001",
      "neighborhood":"Jardim Paulista",
      "street":"Avenida Brigadeiro Faria Lima",
      "street_number":"1811"
    },
    "phone": {
      "number":"87654321",
      "ddd":"11"
    }
  } ,
  "payment_method":"credit_card",
  "amount": 122,
  "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
    }
  ]
}'
PagarMe.api_key = 'SUA_API_KEY'

new_tx = PagarMe::Transaction.new(
    amount:    1000,      # in cents
    card_hash: "UM_CARD_HASH",
    capture: false,
    customer: {
        name: "Nome",
        email: "[email protected]",
        document_number: "113.255.976-60",
        address: {
            zipcode: "79108-110",
            street: "Rua A",
            street_number: "123",
            neighborhood: "Bairro"
        },
        phone: {
            ddd: "11",
            number: "87654321"
        }
    },
    split_rules: [
        {
            recipient_id: "re_civb4p9l7004xbm6dhsetkpj8",
            percentage: 50
        },{
            recipient_id: "re_civb4o6zr003u3m6e8dezzja6",
            percentage: 50
        }
    ]
).charge
<?php
require("vendor/autoload.php");
$pagarme = new PagarMe\Client('SUA_CHAVE_DE_API');

$transaction = $pagarme->transactions()->create([
  'amount' => 1000,
  'card_hash' => "CARD_HASH",
  'split_rules' => [
    [
      'recipient_id' => 're_ci7nheu0m0006n016o5sglg9t',
      'charge_processing_fee' => true,
      'liable' => true,
      'percentage' => '60',
    ]
    [
      'recipient_id' => 're_ci7nhf1ay0007n016wd5t22nl',
      'charge_processing_fee' => true,
      'liable' => false,
      'percentage' => '40',
    ]
  ]
]);
?>
using System;
using System.Collections.Generic;
using System.Linq;
using PagarMe;
using Newtonsoft.Json;
using PagarMe.Model;

PagarMeService.DefaultApiKey = "SUA_API_KEY";
PagarMeService.DefaultEncryptionKey = "SUA_ENCRYPTION_KEY";
var service = PagarMeService.GetDefaultService();

var tx = new Transaction
{
  Amount = 1000,
  CardHash = "UM_CARD_HASH",
  Customer = new Customer
  {
    Name = "Nome",
    Email = "[email protected]",
    DocumentNumber = "113.255.976-60",
    Address = new Address
    {
      Zipcode = "79108-110",
      Street = "Rua A",
      StreetNumber = "123",
      Neighborhood = "Bairro"
    },
    Phone = new Phone
    {
      Ddd = "11",
      Number = "87654321"
    }
  },
  SplitRules = new SplitRule[]{
    new SplitRule
    {
      Recipient = service.Recipients.Find("re_civb4p9l7004xbm6dhsetkpj8"),
      Percentage = 60
    },
    new SplitRule
    {
      Recipient = service.Recipients.Find("re_civb4o6zr003u3m6e8dezzja6"),
      Percentage = 40
    }
  }
};

tx.Save();
Console.WriteLine(tx);
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',
    split_rules: [
      {
        recipient_id: 're_civb4p9l7004xbm6dhsetkpj8',
        percentage: 50,
        liable: true,
        charge_processing_fee: true
      },
      {
        recipient_id: 're_civb4o6zr003u3m6e8dezzja6',
        percentage: 50,
        liable: false,
        charge_processing_fee: true
      }
    ]
  }))
import java.util.ArrayList;
import java.util.Collection;

import org.joda.time.LocalDate;

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.SplitRule;
import me.pagar.model.Transaction;

PagarMe.init("SUA_API_KEY");

Phone phone = new Phone();
phone.setDdd("11");
phone.setNumber("87654321");

Address address = new Address();
address.setCity("Cidade");
address.setComplementary("Complemento");
address.setCountry("Brasil");
address.setNeighborhood("Bairro");
address.setState("Estado");
address.setStreet("Rua");
address.setStreetNumber("123");
address.setZipcode("06350270");

Customer customer = new Customer();
customer.setBornAt(new LocalDate());
customer.setGender("M");
customer.setEmail("[email protected]");
customer.setName("qwe");
customer.setDocumentNumber("648.655.349-97");
customer.setDocumentType("cpf");
customer.setPhone(phone);
customer.setAddress(address);

Transaction transaction = new Transaction();
transaction.setAmount(100);
transaction.setPaymentMethod(Transaction.PaymentMethod.CREDIT_CARD);
transaction.setCardHolderName("Lucas Dos Santos Alves");
transaction.setCardExpirationDate("0519");
transaction.setCardCvv("401");
transaction.setCardNumber("4111111111111111");
transaction.setInstallments(1);
transaction.setCustomer(customer);

Collection<SplitRule> splitRules = new ArrayList<SplitRule>();

SplitRule splitRule = new SplitRule();
splitRule.setRecipientId("re_cix7pxz6f02ppcv6dn4ckcrcc");
splitRule.setPercentage(50);
splitRule.setLiable(true);
splitRule.setChargeProcessingFee(true);
splitRules.add(splitRule);

SplitRule splitRule2 = new SplitRule();
splitRule2.setRecipientId("re_cix7pnghi02wm196emgbthh8u");
splitRule2.setPercentage(50);
splitRule2.setLiable(true);
splitRule2.setChargeProcessingFee(true);
splitRules.add(splitRule2);

transaction.setSplitRules(splitRules);
transaction.save();
System.out.println(transaction);
import pagarme

pagarme.authentication_key('SUA_API_KEY')

default_recipient = pagarme.recipient.default_recipient()

params = {
  'amount': '10000',
  'payment_method': 'credit_card',
    'card_number': '4242424242424242',
    'card_cvv': '111',
    'card_holder_name': 'DAENERYS TARGARYEN',
    'card_expiration_date': '1220',
  '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'
    }
  },
    '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'
        }
    ]
}

trx = pagarme.transaction.create(params)

print(trx)

📘

Somente para biblioteca Python:

A função default_recipient retorna o recebedor principal da sua company sendo ele de teste ou produção.

Caso queira utilizar o recebedor de teste, faça como no exemplo acima. No entanto, se quiser utilizar o de produção, use o seguinte código: default_recipient ['live']

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 = {
  'amount': '10000',
  'payment_method': 'boleto',
  'capture': 'false',
  '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'
    }
  }
}

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'
        }
    ]
}

trx = pagarme.transaction.create(params)

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âmetroSignificadoFormatos válidos e restrições
recipient_idid de um recebedor
charge_processing_fee
Default: true
indica se o recebedor vinculado à regra será cobrado pelas taxas da transaçãoAo 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çãoAo menos um dos recebedores deve ter esse parâmetro true
amountvalor em centavos de quanto da transação irá para o recebedor.
percentagevalor 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 centavosPor 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:

741741

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.


Próximo

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