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"
}'
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:
Campos | Definiçã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_url | URL (endpoint) de seu sistema que recebe notificações a cada mudança no status do recebedor. |
register_information | Campo 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. |
metadata | Objeto com dados adicionais do 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 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_url | Site do seller. |
email obrigatório | Email do seller |
phone_numbers | Nú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. |
Email do seller | |
site_url | Site do seller. |
phone_numbers | Nú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
Agora que você já sabe como criar seus recebedores, vamos aprender sobre transações com split.