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

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

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 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