VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Pagar.me

Recebedores do split

Cria, consulta e altera os recebedores do Pagar.me e liga cada seller ao seu recebedor para o split de pagamentos.

Para dividir uma cobrança entre sellers, o gateway precisa saber para onde mandar o dinheiro de cada um. O recebedor (recipient, id re_...) é essa conta: nome, documento (CPF ou CNPJ), e-mail e conta bancária, mais as regras de repasse e antecipação. Estas rotas conversam direto com o gateway: o que você cria aqui existe no Pagar.me. Exigem o módulo pagarme e o privilégio manage_payments ou view_payments.

A conta bancária deve ser do próprio recebedor: a plataforma envia o nome e o documento informados como titular da conta.

Listar recebedores

Busca os recebedores no gateway (não numa cópia local). Não há filtros nem paginação: vem o que o gateway devolve na primeira página.

GET/api/v1/admin/pagarme/recipientsAdmin

Lista os recebedores do Pagar.me

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/pagarme/recipients" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Recebedores devolvidos
json
{
  "recipients": [
    {
      "id": "re_cm0sellerexampleexample0001",
      "name": "Perola Produtos Ltda",
      "email": "financeiro@perola.example.com",
      "document": "98765432000198",
      "status": "active",
      "transfer_enabled": false,
      "created_at": "2026-09-08T14:55:26Z"
    }
  ],
  "total": 1
}

Campos da resposta

recipientsarray
Recebedores devolvidos pelo gateway.
totalinteger
Quantidade de itens desta resposta (não o total de recebedores da conta).
idstring
Id no gateway (re_...).
namestring
Nome ou razão social.
emailstring
E-mail de contato.
documentstring
CPF ou CNPJ, só dígitos.
statusstring
Situação no gateway, por exemplo active.
transfer_enabledboolean
Se o repasse automático para o banco está ligado.
created_atstring
Criação, RFC 3339.

Erros

StatusQuandoCorpo
500Chave de API ausente ou recusada, gateway fora do ar{"error":"failed to list recipients","detail":"pagarme: list recipients api returned 401: ..."}

Criar um recebedor

Cria o recebedor no gateway. Ele passa por análise do Pagar.me; o campo status da resposta mostra a situação inicial. Esta rota não liga o recebedor a um seller: para isso use a última seção desta página, "Ligar um seller a um recebedor".

POST/api/v1/admin/pagarme/recipientsAdmin

Cria um recebedor no Pagar.me

Corpo da requisição

namestringobrigatório
Nome ou razão social. É também o titular da conta bancária.
emailstringobrigatório
E-mail do recebedor.
documentstringobrigatório
CPF ou CNPJ, só dígitos.
document_typestringobrigatório
cpfcnpj
Tipo do documento. cnpj cria um recebedor empresa; cpf, pessoa física.
bank_codestringobrigatório
Código do banco com 3 dígitos (por exemplo 001, 341).
branch_numberstringobrigatório
Agência.
account_numberstringobrigatório
Número da conta com dígito verificador.
account_typestringobrigatório
checkingsavings
Conta corrente (checking) ou poupança (savings).
auto_anticipationbooleanpadrão: false
Antecipa os recebíveis automaticamente.
transfer_intervalstring
dailyweeklymonthly
Frequência do repasse automático. Sem ela, nenhuma regra de repasse é enviada e transfer_enabled e transfer_day são ignorados.
transfer_enabledbooleanpadrão: false
Liga o repasse automático (só vale com transfer_interval).
transfer_dayinteger
Dia do repasse: de 1 (segunda) a 5 (sexta) em weekly, de 1 a 31 em monthly, ignorado em daily.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/pagarme/recipients" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Perola Produtos Ltda",
    "email": "financeiro@perola.example.com",
    "document": "98765432000198",
    "document_type": "cnpj",
    "bank_code": "341",
    "branch_number": "0001",
    "account_number": "123456-7",
    "account_type": "checking",
    "transfer_interval": "weekly",
    "transfer_enabled": true,
    "transfer_day": 1
  }'

Resposta

201Recebedor criado
json
{
  "id": "re_cm0sellerexampleexample0001",
  "name": "Perola Produtos Ltda",
  "email": "financeiro@perola.example.com",
  "document": "98765432000198",
  "status": "active",
  "transfer_enabled": true,
  "created_at": "2026-10-11T23:20:00Z"
}

Erros

StatusQuandoCorpo
400JSON inválido{"error":"invalid request body","detail":"..."}
500Campo obrigatório ausente ou valor fora da lista{"error":"failed to create recipient","detail":"pagarme: recipient document_type must be 'cpf' or 'cnpj', got \"\""}
500O gateway recusou (documento já cadastrado, banco inválido){"error":"failed to create recipient","detail":"pagarme: create recipient api returned 412: ..."}
Validação volta como 500

Mensagens como recipient name is required, recipient email is required, recipient bank_code is required e recipient account_type must be 'checking' or 'savings' chegam com status 500, não 400. Valide os campos no cliente antes de enviar.

Consultar um recebedor

GET/api/v1/admin/pagarme/recipients/{id}Admin

Consulta um recebedor do Pagar.me

Parâmetros de caminho

idstringobrigatório
Id do recebedor no gateway (re_...).

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/pagarme/recipients/re_cm0sellerexampleexample0001" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Recebedor devolvido
json
{
  "id": "re_cm0sellerexampleexample0001",
  "name": "Perola Produtos Ltda",
  "email": "financeiro@perola.example.com",
  "document": "98765432000198",
  "status": "active",
  "transfer_enabled": true,
  "created_at": "2026-10-11T23:20:00Z"
}

Erros

StatusQuandoCorpo
500Recebedor que não existe no gateway, ou falha de comunicação{"error":"failed to get recipient","detail":"pagarme: get recipient api returned 404: ..."}

Alterar um recebedor

Substitui os dados do recebedor no gateway. Como na criação, todos os campos obrigatórios precisam ser enviados de novo, mesmo os que não mudam: o corpo é validado por inteiro.

PUT/api/v1/admin/pagarme/recipients/{id}Admin

Altera um recebedor do Pagar.me

Parâmetros de caminho

idstringobrigatório
Id do recebedor no gateway (re_...).

Corpo da requisição

namestringobrigatório
Nome ou razão social.
emailstringobrigatório
E-mail.
documentstringobrigatório
CPF ou CNPJ, só dígitos.
document_typestringobrigatório
cpfcnpj
Tipo do documento.
bank_codestringobrigatório
Código do banco com 3 dígitos.
branch_numberstringobrigatório
Agência.
account_numberstringobrigatório
Conta com dígito.
account_typestringobrigatório
checkingsavings
Tipo da conta.
auto_anticipationbooleanpadrão: false
Antecipação automática. Omitir envia false.
transfer_intervalstring
dailyweeklymonthly
Frequência do repasse automático.
transfer_enabledbooleanpadrão: false
Repasse automático ligado.
transfer_dayinteger
Dia do repasse.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/pagarme/recipients/re_cm0sellerexampleexample0001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Perola Produtos Ltda",
    "email": "financeiro@perola.example.com",
    "document": "98765432000198",
    "document_type": "cnpj",
    "bank_code": "341",
    "branch_number": "0001",
    "account_number": "123456-7",
    "account_type": "checking",
    "transfer_interval": "monthly",
    "transfer_enabled": true,
    "transfer_day": 5
  }'

Resposta

200Recebedor atualizado
json
{
  "id": "re_cm0sellerexampleexample0001",
  "name": "Perola Produtos Ltda",
  "email": "financeiro@perola.example.com",
  "document": "98765432000198",
  "status": "active",
  "transfer_enabled": true,
  "created_at": "2026-10-11T23:20:00Z"
}

Erros

StatusQuandoCorpo
400JSON inválido{"error":"invalid request body","detail":"..."}
500Campo obrigatório ausente, recebedor inexistente ou gateway recusou{"error":"failed to update recipient","detail":"..."}

Ligar um seller a um recebedor

Cria o recebedor no gateway e grava a ligação com o seller, em um passo. A partir daí o seller pode participar do split. Se o seller já tinha uma ligação, ela é substituída pela do novo recebedor, mas o recebedor antigo continua existindo no gateway.

POST/api/v1/admin/pagarme/recipients/vendorAdmin

Cria um recebedor e liga a um seller

Corpo da requisição

vendor_iduuidobrigatório
Id do seller.
recipientobjectobrigatório

Dados do recebedor, com os mesmos campos e regras de Criar um recebedor.

namestringobrigatório
Nome ou razão social.
emailstringobrigatório
E-mail.
documentstringobrigatório
CPF ou CNPJ, só dígitos.
document_typestringobrigatório
cpfcnpj
Tipo do documento.
bank_codestringobrigatório
Código do banco.
branch_numberstringobrigatório
Agência.
account_numberstringobrigatório
Conta com dígito.
account_typestringobrigatório
checkingsavings
Tipo da conta.
auto_anticipationboolean
Antecipação automática.
transfer_intervalstring
dailyweeklymonthly
Frequência do repasse.
transfer_enabledboolean
Repasse automático.
transfer_dayinteger
Dia do repasse.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/pagarme/recipients/vendor" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_id": "ec5e10b3-8cb1-43e9-9aa8-964b64eda8de",
    "recipient": {
      "name": "Perola Produtos Ltda",
      "email": "financeiro@perola.example.com",
      "document": "98765432000198",
      "document_type": "cnpj",
      "bank_code": "341",
      "branch_number": "0001",
      "account_number": "123456-7",
      "account_type": "checking"
    }
  }'

Resposta

201Recebedor criado e ligado
json
{
  "recipient": {
    "id": "re_cm0sellerexampleexample0001",
    "name": "Perola Produtos Ltda",
    "email": "financeiro@perola.example.com",
    "document": "98765432000198",
    "status": "active",
    "transfer_enabled": false,
    "created_at": "2026-10-11T23:20:00Z"
  },
  "vendor_id": "ec5e10b3-8cb1-43e9-9aa8-964b64eda8de"
}

Campos da resposta

recipientobject
O recebedor criado, no formato descrito acima.
vendor_iduuid
Seller ligado.

Erros

StatusQuandoCorpo
400JSON inválido{"error":"invalid request body","detail":"..."}
400Sem vendor_id{"error":"vendor_id is required"}
500Dados do recebedor inválidos ou recusados pelo gateway{"error":"failed to create recipient","detail":"..."}
500Recebedor criado, mas a ligação não foi gravada{"error":"failed to save vendor recipient mapping","detail":"..."}
Falha na ligação deixa um recebedor órfão

A ordem é: criar no gateway e depois gravar a ligação. Se a segunda parte falhar, o recebedor já existe no Pagar.me, sem seller. Antes de tentar de novo, liste os recebedores e procure pelo documento, para não criar um duplicado (o gateway pode recusar documento repetido).

Veja também

  • Cobranças
  • Conciliação
  • Configuração
Anterior
Cobranças do Pagar.me
Próxima
Conciliação de um seller
Nesta página
  • Listar recebedores
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar um recebedor
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar um recebedor
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar um recebedor
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ligar um seller a um recebedor
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também