Guides
GuidesSuporteAPI Reference

Recebedores

Suggest Edits

Um recipient é um recebedor — isto é, um vendedor ou empresa que expõe os seus produtos dentro do seu Marketplace. Dentro do ambiente Pagar.me é atribuido um saldo a esse recebedor, de acordo com as transações que tenham sido criadas através da loja. Para isso, você precisa criar o objeto recipient pela API.

É através de um recipient que você especifica as suas regras de split, para que os valores a receber sejam automaticamente atribuídos a cada um dos sellers envolvidos na transação.

Criando um recebedor

Vamos aprender a criar um novo recipient, e em seguida entender cada parâmetro passado. Veja este exemplo:

curl -X POST https://api.pagar.me/1/recipients -H 'content-type: application/json' -d '{
    "anticipatable_volume_percentage": "85", 
    "api_key": "SUA_API_KEY", 
    "automatic_anticipation_enabled": "true", 
    "bank_account": {
    		"bank_code": "341",
        "agencia": "0932",
        "agencia_dv": "5",
        "conta": "58054",
        "type": "conta_corrente",
        "conta_dv": "1",
        "document_number": "26268738888",
        "legal_name": "API BANK ACCOUNT"
    }, 
    "transfer_day": "5", 
    "transfer_enabled": "true", 
    "transfer_interval": "weekly",
    "postback_url": "https://requestb.in/tl0092tl",
    ,
    "register_information": {
        "type": "corporation",
        "document_number": "43633675456",
        "company_name": "Full Name Company",
        "email": "[email protected]",
        "site_url": "http://www.site.com",
        "annual_revenue": "100000",
        "address": {
            "street": "Rua de Exemplo",
            "number": "100",
            "neighborhood": "Centro",
            "zip_code": "12345678",
            "city": "São Paulo",
            "state": "SP",
            "country": "BR",
            "complement": "Loja 100",
            "reference_point": string
        },
        "phone_numbers": [
            {
                "ddd": "11",
                "number": "11987654321",
                "type": "mobile"
            }
        ],
        "managing_partners": [{
            "name": "Teste Onboarding",
            "document_number": "50107915014",
            "mother_name": "Eliana das Neves",
            "birthdate": "01/01/0001",
            "email": "[email protected]",
            "monthly_income": "1000",
        	"professional_occupation": "Empresário",
            "self_declared_legal_representative": true,
			"address": {
              "street": null,
              "complementary": "SN",
              "street_number": null,
              "neighborhood": null,
              "city": null,
              "state": null,
              "zipcode": null,
              "reference_point": null
          },
			"phone_numbers": [
            {
              "ddd": "27",
              "number": "999992628",
              "type": "primary"
            }
          ]
          }
      ]
    }
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

PagarMe::Recipient.create(
  transfer_enabled: false,
  transfer_interval: "weekly",
  transfer_day: 5,
  automatic_anticipation_enabled: true,
  anticipatable_volume_percentage: 85,
  bank_account_id: {
  	bank_code: "341",
    agencia: "0932",
    agencia_dv: "5",
    conta: "58054",
    type: "conta_corrente",
    conta_dv: "1",
    document_number: "26268738888",
    legal_name: "API BANK ACCOUNT"
  }
)

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

$recipient = $pagarme->recipients()->create([
  'anticipatable_volume_percentage' => '85', 
  'automatic_anticipation_enabled' => 'true', 
  'bank_account' => [
    'bank_code' => '341',
    'agencia' => '0932',
    'agencia_dv' => '5',
    'conta' => '58054',
    'type' => 'conta_corrente',
    'conta_dv' => '1',
    'document_number' => '26268738888',
    'legal_name' => 'API BANK ACCOUNT'
  ],
  'transfer_day' => '5', 
  'transfer_enabled' => 'true', 
  'transfer_interval' => 'weekly'
]);

Não temos essa funcionalidade nessa sdk ainda :(

import pagarme from 'pagarme'

pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.recipients.create({
      transfer_enabled: false,
      transfer_interval: "weekly",
      transfer_day: 5,
      automatic_anticipation_enabled: true,
      anticipatable_volume_percentage: 85,
      bank_account: {
        bank_code: "341",
        agencia: "0932",
        agencia_dv: "5",
        conta: "58054",
        type: "conta_corrente",
        conta_dv: "1",
        document_number: "26268738888",
        legal_name: "API BANK ACCOUNT"
      }
  })
)

import me.pagar.model.BankAccount;
import me.pagar.model.PagarMe;
import me.pagar.model.PagarMeException;
import me.pagar.model.Recipient;

PagarMe.init("SUA_API_KEY");
BankAccount bankAccount = new BankAccount();
bankAccount.setBankCode("342");
bankAccount.setAgencia("0932");
bankAccount.setAgenciaDv("5");
bankAccount.setConta("58054");
bankAccount.setContaDv("1");
bankAccount.setDocumentNumber("26268738888");
bankAccount.setLegalName("API BANK ACCOUNT");

Recipient recipient = new Recipient();
recipient.setBankAccount(bankAccount);
recipient.setAnticipatableVolumePercentage(85);
recipient.setAutomaticAnticipationEnabled(true);
recipient.setTransferDay(5);
recipient.setTransferEnabled(true);
recipient.setTransferInterval(Recipient.TransferInterval.WEEKLY);
recipient.save();

import pagarme

pagarme.authentication_key('SUA_API_KEY')

params = {
    'anticipatable_volume_percentage': '80',
    'automatic_anticipation_enabled': 'true',
    'transfer_day': '5',
    'transfer_enabled': 'true',
    'transfer_interval': 'weekly',
    'bank_account':{
        'agencia': '0932',
        'agencia_dv': '5',
        'bank_code': '341',
        'conta': '58054',
        'conta_dv': '1',
        'document_number': '26268738888',
        'legal_name': 'HOUSE TARGARYEN'
    }
}

recipient = pagarme.recipient.create(params)

print(recipient)

É possível, porém, quebrar a criação do recebedor em múltiplas etapas:

curl -X POST https://api.pagar.me/1/recipients -H 'content-type: application/json' -d '{
    "anticipatable_volume_percentage": "85", 
    "api_key": "SUA_API_KEY", 
    "automatic_anticipation_enabled": "true", 
    "bank_account_id": "4841", 
    "transfer_day": "5", 
    "transfer_enabled": "true", 
    "transfer_interval": "weekly"
}'

require 'pagarme'

PagarMe.api_key = "SUA_API_KEY"

PagarMe::Recipient.create(
  transfer_enabled: false,
  transfer_interval: "weekly",
  transfer_day: 5,
  automatic_anticipation_enabled: true,
  anticipatable_volume_percentage: 85,
  bank_account_id: 4841
)

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

$recipient = $pagarme->recipients()->create([
  'anticipatable_volume_percentage' => '85', 
  'automatic_anticipation_enabled' => 'true', 
  'bank_account_id' => '17899179', 
  'transfer_day' => '5', 
  'transfer_enabled' => 'true', 
  'transfer_interval' => 'weekly'
]);

PagarMeService.DefaultApiKey = "SUA_API_KEY";

Recipient recipient = new Recipient();
recipient.TransferInterval = TransferInterval.Weekly;
recipient.TransferDay = 5;
recipient.TransferEnabled = true;
recipient.BankAccount = PagarMeService.GetDefaultService().BankAccounts.Find("4840");
recipient.Save();

import pagarme from 'pagarme'

pagarme.client.connect({ api_key: 'SUA_API_KEY' })
  .then(client => client.recipients.create({
    bank_account_id: 'bank_account_id',
    transfer_interval: 'weekly',
    transfer_day: 5,
    transfer_enabled: true
  }))

import me.pagar.model.PagarMe;
import me.pagar.model.Recipient;
import me.pagar.model.Recipient.TransferInterval;

PagarMe.init("SUA_API_KEY");
Recipient recipient = new Recipient();
recipient.setAnticipatableVolumePercentage(85);
recipient.setAutomaticAnticipationEnabled(true);
recipient.setBankAccountId(17490076);
recipient.setTransferDay(5);
recipient.setTransferEnabled(true);
recipient.setTransferInterval(TransferInterval.WEEKLY);
recipient.save();

import pagarme

pagarme.authentication_key('SUA_API_KEY')

params = {
    'anticipatable_volume_percentage': '80',
    'automatic_anticipation_enabled': 'true',
    'transfer_day': '5',
    'transfer_enabled': 'true',
    'transfer_interval': 'weekly',
    'bank_account_id': '4841'
}

recipient = pagarme.recipient.create(params)

print(recipient)

Dessa maneira é possível criar um recebedor com uma conta bancária já existente.

Parâmetros de um recebedor

Veja a tabela a seguir para entender cada parâmetro:

PropriedadeDescrição
bank_account
Object		Objeto contendo os dados bancários do recebedor.
transfer_enabled
Boolean		Se o recebedor está habilitado para receber transferências ou não.
transfer_interval
String		Frequência na qual o recebedor irá ser pago.
Valores possíveis: daily, weekly, monthly.
transfer_day
Integer		Dia no qual o recebedor vai ser pago. Para cada transfer_day, existe uma faixa de pagamento possível.
weekly: 1 a 5, onde 1 é segunda-feira e 5 é sexta-feira
monthly: 1 a 31
daily: 1

OBS: Para monthly=31 e meses com menos de 31 dias, a transferência acontece no primeiro dia útil do mês seguinte.
automatic_anticipation_enabled
Boolean		Se o recebedor está habilitado para receber automaticamente ou não o valor disponível para antecipação.
anticipatable_volume_percentage
Integer		Porcentagem do valor passível de antecipação para este recebedor.

Observações

🚧

Atenção

Quando o parâmetro transfer_interval possui o valor daily, não é necessário informar o parâmetro transfer_day

❗️

Recebedores inativos

Todos os recebedores que foram criados a mais de 60 dias, não possuem valores a receber e nos últimos 60 dias não transacionaram ou realizaram transferências terão a transferência automática desabilitada. Mesmo que esse recebedor volte a transacionar eventualmente, a transferência automática precisa ser reabilitada manualmente nesses casos.

❗️

Alterando um recebedor

Ao atrelar uma conta bancária a um recebedor, somente será possível trocar a conta se a nova tiver o mesmo número de documento (seja ele CPF ou CNPJ). Caso contrário, essa ação não é possível.

Para aprender como atualizar um recebedor, leia mais em: Atualizando um recebedor

Campo register_information

O campo register_information recebe informações cadastrais do seller. Abaixo você pode conferir as especificações do campo para pessoa física e jurídica

Campo register_information para pessoa física

Quando o recebedor é uma pessoa física, deve-se usar o valor individual no campo type. 

{
"register_information": {
  "type": "individual",
  "document_number": "12345678910",
  "name": "Someone",
  "site_url": "",
  "email": "[email protected]",
  "mother_name": "Eliana das Neves",
  "birthdate": "01/01/0001",
  "monthly_income": "1000",
  "professional_occupation": "Empresário",
  "address": {
      "street": null,
      "complementary": "SN",
      "street_number": null,
      "neighborhood": null,
      "city": null,
      "state": null,
      "zipcode": null,
      "reference_point": null
  },
  "phone_numbers": [
    {
      "ddd": "27",
      "number": "999992628",
      "type": "primary"
    }
  ]
}
Nome do parâmetroEspecificação do parâmetro
type
obrigatório		Utilizar "individual".
document_number
obrigatório		Número do CPF.
name
obrigatório 		Nome do seller.
site_urlSite do seller.
email
obrigatório		Email do seller
mother_nameNome da mãe
birthday
obrigatório		Data de nascimento
monthly_income
obrigatório		Renda mensal (disponível em Janeiro de 2024)
professional_occupation
obrigatório		Ocupação profissional (disponível em Janeiro de 2024)
address
obrigatório		Endereço completo
phone_numbers
obrigatório		Número de telefone do seller. Deve-se informar o DDD, número e o tipo.

Campo register_information para pessoa jurídica

Quando o recebedor é uma pessoa jurídica, deve-se usar o valor corporation no campo type. 

{
"register_information": {
  "type": "corporation",
  "document_number": "43633675456",
  "company_name": "Full Name Company",
  "trading_name": "Full Name Company SA",
  "annual_revenue": "1000",
  "corporation_type": "",
  "founding_date": "",
  "cnae": "",
  "email": "[email protected]",
  "site_url":"http://www.site.com",
  "phone_numbers":  [{
    "ddd": "11",
    "number": "11987654321",
    "type": "mobile"
  }],
  "main_address": {
    "street": null,
    "complementary": "SN",
    "street_number": null,
    "neighborhood": null,
    "city": null,
    "state": null,
    "zipcode": null,
    "reference_point": null
  },
  "managing_partners": [{
    "type": "individual",
    "name": "Teste Onboarding",
    "document_number": "50107915014",
    "mother_name": "Eliana das Neves",
    "birthdate": "01/01/0001",
    "email": "[email protected]",
    "monthly_income": "1000",
 		"professional_occupation": "Empresário",
    "self_declared_legal_representative": true,
	  "address": {
      "street": null,
      "complementary": "SN",
      "street_number": null,
      "neighborhood": null,
      "city": null,
      "state": null,
      "zipcode": null,
      "reference_point": null
  },
	  "phone_numbers": [
    {
      "ddd": "27",
      "number": "999992628",
      "type": "primary"
    }
  ]
  }
Nome do parâmetroEspecificação do parâmetro
type
obrigatório		Utilizar "corporation"
document_number
obrigatório		Número do CNPJ.
company_name
obrigatório		Nome fantasia do seller.
trading_name
obrigatório		Razão social
annual_revenue
obrigatório		Faturamento anual (disponível em Janeiro de 2024)
corporation_typeTipo da empresa
founding_dateData de fundação
cnaeClassificação Nacional das Atividades Econômicas
email
obrigatório		Email do seller
site_url
obrigatório		Site do seller.
phone_numbers
obrigatório		Número de telefone do seller. Deve-se informar o DDD, número e o tipo.
main_address
obrigatório		Endereço completo
managing_partners
obrigatório		Dados dos sócios listados neste CNPJ/Representante legal, seguir o mesmo padrão do recebedor com type individual.

Updated 9 months ago

Próximo

Agora que você já sabe como criar seus recebedores, vamos aprender sobre transações com split.