Configurador de Split nas Maquininhas PagBank

A funcionalidade Configurador de Split nas Maquininhas PagBank oferece aos Parceiros PagBank autonomia e flexibilidade para configurar a divisão de pagamentos em qualquer modelo de maquininha PagBank.

Benefícios

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

Premissas e Requisitos

Antes de utilizar a funcionalidade, 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. Veja como 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.
• Todos os recebedores envolvidos no split devem ter contas PagBank Avançadas do tipo empresarial ou vendedor.

📘

Testes em Sandbox

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 de Produção.

Como utilizar

Para realizar a configuração de Split nas maquininhas, você deve seguir as etapas abaixo:

1. Cadastrar Recebedores
2. Cadastrar Regras de Split

1. Cadastrar Recebedores

Antes de realizar o cadastro de Split para uma maquininha, é necessário cadastrar os recebedores. Utilize a API de recebedores para vincular as contas que participarão das regras de Split ao parceiro.

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

2. Cadastrar Regras de Split

Para cadastrar uma regra de split em uma maquininha, o Parceiro deve utilizar a API informando os seguintes dados:

• name: Nome para a regra.
• level: O nível dessa regra. Tipo permitido: "receivers".
• device: Informações sobre a maquininha.
  • pos: Lista de terminais.
    • serial: Número de série (pode ser obtido na etiqueta no verso da maquininha ou nas configurações do menu da maquininha).
    • owner: O Account Id do dono do terminal. Pode ser obtido no iBanking da conta associada à maquininha. Para encontrar, confira o tópico Onde encontrar o ACCOUNT ID?.

📘

Toda regra precisa obrigatoriamente ter o dono do terminal incluído como um dos recebedores.

• payment_method: Informações sobre as formas de pagamento aceitas.

  • Tipos permitidos: "CREDIT_CARD", "PIX", "DEBIT_CARD".
  • Você pode selecionar no mínimo 1 e no máximo 3 métodos.

• method: Informa que os valores da divisão serão em porcentagem. Tipo permitido: "PERCENTAGE".

• receivers: A lista de recebedores envolvidos e respectivas porcentagens.

  • account: Deve ser informado o id (Account Id) do recebedor.
  • amount:
    • value: O valor em percentual que esse recebedor receberá na transação.
    • currency: Obrigatório ser "BRL".

• reason: Campo opcional para controle do parceiro.

📘

Regras e Métodos de Pagamento

Você pode definir uma única regra especificando de uma a três formas de pagamento, ou criar até três regras distintas, cada uma com seu próprio método de pagamento.

Isso significa que o mesmo número de série pode possuir até três regras ativas simultaneamente (ex: uma para Crédito e outra para Débito), com percentuais de divisão diferentes para cada uma.

Servidores

• Produção: https://api.pagseguro.com/split-configuration/device
• Sandbox: https://sandbox.api.pagseguro.com/split-configuration/device

Criar Configuração de Split (POST)

Utilize este endpoint para criar uma nova configuração de divisão de pagamentos (Split) para um terminal específico. Ao cadastrar uma regra com sucesso, a API retornará um identificador único da regra (iniciado por SPCO_), que será necessário para realizar futuras edições ou consultas específicas.

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": {
        "pos": [
            {
                "serial": "XXXXXXXXXXXX",
                "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 (PUT)

Este endpoint permite atualizar os dados de uma regra de Split já existente em um terminal específico.

❗️

Atenção

Durante a edição, não é permitido alterar os dados do objeto device (maquininha). As informações de identificação do terminal devem permanecer idênticas às enviadas na criação da regra; apenas os parâmetros de divisão (como recebedores, métodos de pagamento e percentuais) podem ser modificados.

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

Listar as configurações cadastradas (GET)

Utilize este método para consultar as configurações de Split vinculadas ao parceiro. A listagem retorna as regras cadastradas e suporta paginação para facilitar a visualização de grandes volumes de dados. Você também pode utilizar filtros opcionais (como status, serial, offset e limit) para refinar sua busca e encontrar configurações específicas.

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'

Listar todas as configurações de um parceiro de forma paginada e com filtros:

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

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

Também é possível consultar 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'

Inativar Regra (DELETE)

Este endpoint é utilizado para inativar uma regra de Split específica.

❗️

Importante

Esta ação é irreversível. Uma vez que uma regra é inativada, ela não poderá ser reativada ou utilizada novamente em transações futuras. Caso seja necessário retomar o Split, uma nova regra deverá ser criada.

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

Split com Maquininhas Compartilhadas

Os parceiros PagBank podem compartilhar suas maquininhas. Ao utilizar esse modo de operação, você pode configurar a maquininha para cada usuário compartilhado, tornando o usuário que está realizando a venda o owner temporário do terminal.

📘

Owner temporário

Todos os usuários que serão owner temporários devem ter uma conta PagBank do tipo vendedor ou empresarial e aceitar o compartilhamento da maquininha.

Cada maquininha pode ter até 6 usuários:

• 1 usuário principal que ativou a maquininha inicialmente.
• 5 usuários compartilhados.

Exemplo de Compartilhamento

Suponha que os usuários Joy Flores, Pag Boutique e Barraca do Marcelo precisem utilizar o Split de pagamentos. Nesse caso, é necessário criar três regras de Split, alterando o owner do terminal conforme abaixo:

Observe que o número de série permanece inalterado, pois está sendo configurado em um único terminal.

Ao utilizar regras de Split em máquinas compartilhadas, é importante considerar os seguintes cenários:

• Se houver uma regra para um usuário que transferiu o dispositivo para outro, a regra do antigo proprietário permanecerá ativa. Caso não faça sentido mantê-la, o parceiro deverá inativá-la via API.
• Se houver uma regra para um usuário que foi removido do compartilhamento do dispositivo, a regra permanecerá ativa. Caso não faça sentido mantê-la, o parceiro deverá inativá-la via API.
• Se houver uma regra ativa para um usuário compartilhado e, posteriormente, ocorrer a transferência do dispositivo para esse mesmo usuário, a regra continuará ativa e será aplicada nas transações. Caso o usuário não deseje que a regra seja aplicada, deverá solicitar ao parceiro que a inative via API.
• Se houver uma ou mais regras ativas para usuários compartilhados e o dispositivo for transferido para outro usuário, e depois de volta para o usuário inicial, as regras continuarão válidas e serão aplicadas nas transações, caso o(s) usuário(s) realizem transações. Se não for mais necessário manter as regras, o parceiro deve desativá-las via API.

Como obter o token para se integrar as APIs?

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

Onde encontrar o ACCOUNT ID?

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 e 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 e clique em Identificador para Marketplace.

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