Configurador de Split

A funcionalidade Configurador de Split (divisão de pagamento) no TEF PagBank oferece aos Parceiros PagBank a opção de configurar a divisão de pagamentos entre múltiplos recebedores em qualquer modelo de maquininha PagBank.

📘

Esta é uma funcionalidade disponível exclusivamente para números lógicos PagBank. Não é compatível com números lógicos de outras adquirentes.

Benefícios

• Permite a divisão de pagamentos entre dois ou mais recebedores (até um máximo de 15 por configuração) no TEF PagBank.
• Facilita a gestão das regras de Split, incluindo percentuais, recebedores e métodos de pagamento.

Requisitos

Antes de utilizar a funcionalidade de Configurador de Split, o Parceiro deve garantir que as seguintes condições sejam atendidas:

• O Parceiro deve possuir uma conta PagBank do tipo vendedor ou empresarial, avançada, tokenizada e validada no processo de KYP do PagBank.
• O token necessário para utilizar as APIs pode ser obtido no iBanking do Parceiro. O processo para obter o token é descrito em Como obter o token para se integrar as APIs? .
• As APIs devem ser testadas no ambiente Sandbox antes de solicitar homologação ao time de Integração do PagBank.
• Utilizar uma solução de TEF integrada ao PagBank. Para mais informações, consulte a documentação.

📘

Testar transações

Não é possível realizar testes transacionais no ambiente Sandbox. Apenas os testes da API de configuração de Split são permitidos.

• O time de Integração analisará a solicitação e liberará o uso no ambiente Produção. Todos os recebedores envolvidos no split devem ter contas PagBank Avançadas do tipo empresarial ou vendedor.

Como utilizar

Para realizar a divisão do pagamento (Split) entre recebedores para um TEF, você deve:

1. Cadastrar recebedores
2. Cadastrar regras de Split

Cadastrar recebedores

Antes de definir as regras de divisão do pagamento, você precisa cadastrar todos os recebedores envolvidos. Para realizar esse cadastro você utilizará a API, que permite vincular os recebedores que participarão das regras de Split ao parceiro.

Para mais informações, consulte a página da API de recebedores.

Cadastrar regra de Split

O cadastro de uma regra de Split para divisão dos pagamentos entre os recebedores deve ser feito utilizando a API do PagBank. Os seguintes endpoints estão disponíveis para você gerenciar as suas regras:

• Criar regra de Split
• Editar regra de Split
• Listar regras de Split
• Inativar regra de Split

📘

Gerenciando regras

Cada número lógico pode conter no máximo três regras por forma de pagamento ativa.

Regras inativas não podem ser reativadas ou utilizadas novamente.

📘

Regras inativas

Quando uma regra é inativada, ela não pode ser reativada. Como resultado, a máquininha associada a essa regra inativada deixará de processar transações com Split até que o integrador configure uma nova regra de Split para ela.

Para consultar a regra ativa em um terminal específico, o integrador pode utilizar a funcionalidade de Listar regras de Split .

📘

Token para uso da API

Para utilizar a API e gerenciar as regras de Split, você precisa informar o token de identificação. Acesse a seção Obter Token para aprender como acessar esse token.

Após o cadastro dos recebedores, você pode criar as suas regras de Split utilizando o endpoint Criar regra de Split . Para cadastrar uma regra em um TEF, você (Parceiro PagBank) deve informar:

• name: Nome da regra.
• level: Nível dessa regra. Apenas o tipo receivers é aceito no momento.
• device: Informações sobre o TEF.
  • tef: Contém os detalhes de identificação do TEF.
    • logical_number: Número lógico. Obtido após solicitação de cadastro de número lógico.

      📘

      Para adquirir o número lógico, entre em contato com seu gerente comercial do PagBank.

    • owner: O Account Id do dono do número lógico. Pode ser obtido no iBanking da conta associada ao número lógico. Acesse a seção Obter Account Id para mais detalhes. Toda regra precisa obrigatoriamente ter o dono do terminal como recebedor.
• payment_method: Informações sobre as formas de pagamento aceitas. Os tipos permitidos são CREDIT_CARD, PIX e DEBIT_CARD.

📘

Atualmente, o método de pagamento PIX não está disponível para operações realizadas com a Fiserv. Caso seja configurado, a transação será aprovada, porém sem aplicação do Split.

📘

Você pode configurar uma única regra com uma a três formas de pagamento, ou definir até três regras distintas, cada uma com seu próprio método de pagamento. Dessa forma, um mesmo número de série pode ter até três regras de Split ativas simultaneamente, desde que utilizem métodos de pagamento diferentes. Os percentuais de divisão também podem variar entre essas regras.

• method: Define como a divisão será realizada entre os recebedores cadastrados. Atualmente, apenas a divisão percentual (PERCENTAGE) é aceita.
• receivers: Lista dos recebedores envolvidos e respectivas porcentagens de recebimento:
  • account: Deve ser informado o id do recebedor. Ele pode ser obtido no iBanking pelo próprio recebedor. Acesse a seção Obter Account Id para mais detalhes.
  • amount: Define o valor (value) em percentual que esse recebedor receberá em toda transação e a moeda (currency) da operação. Atualmente, somente o real (BRL) é aceito.
  • reason: Campo opcional que pode ser utilizado para controle do parceiro.

📘

Validação do campo amount

A soma dos valores informados no campo values para todos os recebedores deve ser igual a 100 (equivalente a 100%). Caso a soma seja diferente de 100, um erro será retornado ao tentar criar a regra de Split.

O bloco de código a seguir mostra um exemplo de requisição:

curl --location 'https: //sandbox.api.pagseguro.com/split-configuration/device' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
"name": "Regra 1 teste",
"level": "receivers",
"device": {
    "tef": [
        {
            "logical_number": "TXXXXXXXXXXXX",
            "owner": " ACCO_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
        }
    ]
},
"payment_method": [
    "CREDIT_CARD",
    "PIX",
    "DEBIT_CARD"
],
"method": "PERCENTAGE",
"receivers": [
    {
        "account": {
            "id": " ACCO_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
        },
        "amount": {
            "value": 40,
            "currency": "BRL"
        },
        "reason": "Descrição 1"
    },
    {
        "account": {
            "id": " ACCO_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXL"
        },
        "amount": {
            "value": 60,
            "currency": "BRL"
        },
        "reason": "Descrição 2"
    }
]
}'

Após a criação da regra de Split, todas as transações realizadas na maquininha configurada serão divididas conforme as regras estabelecidas.

Editar regra de Split criada

O bloco de código a seguir é um exemplo de requisição para editar uma regra de um terminal específico. Não é permitido alterar o campo device: o mesmo valor utilizado na criação da regra deve ser informado na edição.

{
"name": "Regra 1 teste",
"level": "receivers",
"device": {
    "tef": [
        {
            "logical_number": "TXXXXXXXXXXXX",
            "owner": " ACCO_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
        }
    ]
},
"payment_method": [
    "CREDIT_CARD",
    "PIX",
    "DEBIT_CARD"
],
"method": "PERCENTAGE",
"receivers": [
    {
        "account": {
            "id": " ACCO_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
        },
        "amount": {
            "value": 40,
            "currency": "BRL"
        },
        "reason": "Descrição 1"
    },
    {
        "account": {
            "id": " ACCO_XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXL"
        },
        "amount": {
            "value": 60,
            "currency": "BRL"
        },
        "reason": "Descrição 2"
    }
]
}

Listar as configurações cadastradas

Exemplo de requisição para listar todas as configurações de um parceiro:

curl --location 'https://sandbox.api.pagseguro.com/split-configuration/device/partner' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json'

Exemplo de requisição para listar todas as configurações de um parceiro de forma paginada:

curl --location 'https://sandbox.api.pagseguro.com/split-configuration/device/partner?
logical_number=T123&type=TEF&status=ACTIVE&offset=1&limit=20' \
 --header 'Authorization: Bearer <token>' \
 --header 'Content-Type: application/json'

Na requisição exemplificada acima, é possível adicionar os seguintes filtros opcionais:

Exemplo de requisição com consulta pelo configuration_id:

curl --location 'https://sandbox.api.pagseguro.com/split-configuration/device/SPCO_ XXXXXXXXXXXX-
XXXX-XXXX-XXXXXXXXXXXX' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data ''

Inativar regra

O bloco de código abaixo é um exemplo de requisição para tornar uma regra inativa.

❗️

Importante

Uma regra inativa não poderá ser reativada ou utilizada novamente.

curl --location --request DELETE 'https://sandbox.api.pagseguro.com/split-configuration/device/SPCO_ XXXXXXXXXXXX-
XXXX-XXXX-XXXXXXXXXXXX' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data ''

Obter Token

Para utilizar a API e gerenciar as regras de Split, você precisa informar o token de identificação. Para obter esse token, siga os passos indicados a seguir:

1. Acesse a sua conta através do iBanking.
2. Clique no menu de Vendas.

3. Na seção Plataformas e Checkout clique em Integrações.

4. Clique em Gerar token. Você poderá copiá-lo ou enviá-lo por e-mail.

📘

Cuidados ao gerar um novo token

Ao gerar um novo token, o token antigo é automaticamente inativado.

Proceda com cuidado ao executar essa opção, pois ela pode paralisar a sua integração.

Obter Account Id

Para utilizar a API e gerenciar as regras de Split, recebedores e o parceiro precisam informar o seus respectivos Account Id. Para obter o Account Id, siga os passos indicados a seguir:

1. Acesse a sua conta através do iBanking.
2. Clique no menu de Vendas

3. Na seção Plataformas e Checkout, clique em Identificador para Marketplace.

4. O identificador do seu Account Id será apresentado na tela.

Existem diversas maneiras de adquirir o Account Id (ACCO), dependendo do fluxo desejado:

1. Via interface (exemplo acima):
   Cada conta precisa acessar individualmente a tela de identificação do marketplace. Este processo é manual e exige que o usuário realize a ação diretamente pela interface.
2. Via API de contas:
   Através dessa API, é possível criar contas preliminares para seus clientes. Isso significa que, após a criação, o usuário ainda precisará concluir o processo avançando com a validação de documentos e selfie. A principal vantagem é que, assim que a conta preliminar é criada, o usuário recebe automaticamente um e-mail com instruções para finalizar o cadastro. Além disso, essa API permite que o Account Id seja retornado imediatamente após a criação da conta através da API, eliminando a necessidade de solicitá-lo posteriormente ao usuário. Para mais detalhes, consulte a documentação da API.
3. Via API do Connect:
   Essa API permite criar uma aplicação no PagBank e executar ações em nome de outros usuários. É possível enviar um SMS ou uma URL para que o usuário seja redirecionado e dê o “aceite”. Após o consentimento, você poderá realizar ações em nome do usuário e receberá o Account Id.