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

Quando for necessário criar um novo recebedor, podemos criá-lo sem dependências de outros recursos.

É 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",
    "postback_url": "https://requestb.in/tl0092tl"
}'

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

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:

CamposDefinição
transfer_enabled
Default: false		Essa propriedade define se o recebedor pode receber seus pagamentos automaticamente, no dia e no intervalo que forem definidos.
transfer_interval
Default: daily		Essa propriedade define com qual frequência os valores disponíveis no Pagar.me são transferidos automaticamente para a conta bancária do recebedor. Os valores são: daily, weekly, monthly, que respectivamente significam diário, semanal e mensal.
transfer_day
Default: 0		Essa propriedade define em qual dia as transferências automáticas são feitas para o recebedor, dado o transfer_interval escolhido.
Os valores possíveis são:
1 a 5 se transfer_interval for igual a weekly
1 a 31 se transfer_interval for igual a monthly
0 se transfer_interval for igual daily
anticipatable_volume_percentage
Default: 0		Essa propriedade define a porcentagem referente ao valor a receber que o recebedor pode antecipar junto ao Pagar.me. Por padrão, novos recebedores possuem essa propriedade com valor 0.
automatic_anticipation_enabled
Default: false		Define se o recebedor pode receber antecipações automáticas
bank_account_id
obrigatório		Essa propriedade deverá conter o id de uma conta bancária previamente criada. Mais em: Criando uma conta bancária
postback_urlURL (endpoint) de seu sistema que recebe notificações a cada mudança no status da transação.

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.