Recebedores
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:
Propriedade | Descriçã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-feiramonthly : 1 a 31daily : 1OBS: 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 valordaily
, não é necessário informar o parâmetrotransfer_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âmetro | Especificação do parâmetro |
---|---|
type obrigatório | Utilizar "individual". |
document_number obrigatório | Número do CPF. |
name obrigatório | Nome do seller. |
site_url | Site do seller. |
email obrigatório | Email do seller |
mother_name | Nome 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âmetro | Especificaçã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_type | Tipo da empresa |
founding_date | Data de fundação |
cnae | Classificaçã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 10 months ago
Agora que você já sabe como criar seus recebedores, vamos aprender sobre transações com split.