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

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)

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

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:

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 do recebedor.
register_informationCampo usado para receber informações cadastrais de um recebedor. Este recebedor pode ser pessoal física ou pessoa jurídica, onde cada um tem formato especifico.
metadataObjeto com dados adicionais do 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 para pessoa física

O campo register_information recebe informações cadastrais do seller. Este recebedor pode ser pessoa física (utilizar "individual" em "type").

"register_information": {
	"type": "individual",
	"document_number": "92545278157",
	"name": "Someone",
	"site_url":"http://www.site.com",
	"email": "[email protected]",
	"phone_numbers": [{
		"ddd": "11",
		"number": "11987654321",
		"type": "mobile"
	}]
}
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
phone_numbersNúmero de telefone do seller. Deve-se informar o DDD, número e o tipo.

Campo register_information para pessoa jurídica

O campo register_information recebe informações cadastrais do seller. Este recebedor pode ser pessoa jurídica (utilizar "corporation" em "type").

"register_information": {
	"type": "corporation",
	"document_number": "43633675456",
	"company_name": "Full Name Company",
	"email": "[email protected]",
	"site_url":"http://www.site.com",
	"phone_numbers":  [{
		"ddd": "11",
		"number": "11987654321",
		"type": "mobile"
	}],
	"managing_partners": [{
		"type": "individual",
		"document_number": "925452787",
		"email": "so[email protected]",
		"name": "Someone"
	}]
type
obrigatório		Utilizar "corporation".
document_number
obrigatório		Número do CNPJ.
company_name
obrigatório		Nome fantasia do seller.
emailEmail do seller
site_urlSite do seller.
phone_numbersNúmero de telefone do seller. Deve-se informar o DDD, número e o tipo.
managing_partners
obrigatório		Dados dos sócios listados neste CNPJ.

Updated almost 3 years ago

Próximo

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