Pular para o conteúdo principal

Split de pagamento Pix

Nesta seção você encontrará todos os endpoints disponíveis para a realização do Split de pagamento na API Pix Efí.


Configuração de um Split de pagamento​

Importante!

O Split de pagamento Pix só pode ser realizado entre contas Efí, com limite máximo de 20 contas para o repasse.


O conjunto de endpoints a seguir é responsável pela configuração dos Splits de pagamento na API Pix. As cobranças, no contexto da API Pix representam uma transação financeira entre um pagador e um recebedor, cuja forma de pagamento é o Pix.

Informação

Uma mesma configuração de Split pode ser utilizada em várias cobranças. Isso significa que você pode definir uma divisão de valores para um parceiro e aplicá-la em todas as cobranças relacionadas.


Configure Split de Pagamento em QR Code e copia e cola estático!

Você tem a flexibilidade de dividir o pagamento dos QR Codes e copia e cola estático entre diferentes contas Efí. Isso significa que, ao gerar um QR Code ou um código copia e cola estáticos para pagamento, você pode especificar como o valor recebido será distribuído, facilitando a gestão financeira e assegurando que os fundos sejam alocados corretamente desde o início.


Instruções para testes em Homologação

No processo de split de pagamento, é essencial fornecer uma conta digital EFÍ válida.

É importante destacar que não é possível realizar o split para a própria conta. Portanto, se estiver realizando testes em ambiente de homologação e não possuir uma conta válida para os repasses, será necessário criar uma subconta. Veja como fazer isso aqui.


Configuração de um Split de pagamento (sem passar id)​

Endpoint para criar Split de pagamento sem informar um id. Em geral, o id é criado pela pessoa recebedora e está sob sua responsabilidade. Porém, neste caso, o id será definido pela Efí, fazendo uma exceção à regra padrão.

POST /v2/gn/split/config
Requer autorização para o escopo: gn.split.write


Requisição

{
  "descricao": "Batatinha frita 1, 2, 3",
  "lancamento": {
    "imediato": true
  },
  "split": {
    "divisaoTarifa": "assumir_total",
    "minhaParte": {
      "tipo": "porcentagem",
      "valor": "60.00"
    },
    "repasses": [
      {
        "tipo": "porcentagem",
        "valor": "15.00",
        "favorecido": {
          "cpf": "12345678909",
          "conta": "1234567"
        }
      },
      {
        "tipo": "porcentagem",
        "valor": "25.00",
        "favorecido": {
          "cpf": "94271564656",
          "conta": "7654321"
        }
      }
    ]
  }
}

Respostas

As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.

{
  "id": "00000000000000000abcd",
  "status": "ATIVA",
  "txid": "SplitEstatico001",
  "descricao": "Batatinha frita 1, 2, 3",
  "lancamento": {
    "imediato": true
  },
  "split": {
    "divisaoTarifa": "assumir_total",
    "minhaParte": {
      "tipo": "porcentagem",
      "valor": "60.00"
    },
    "repasses": [
      {
        "tipo": "porcentagem",
        "valor": "15.00",
        "favorecido": {
          "conta": "1234567",
          "cpf": "12345678909"
        }
      },
      {
        "tipo": "porcentagem",
        "valor": "25.00",
        "favorecido": {
          "conta": "7654321",
          "cpf": "94271564656"
        }
      }
    ]
  }
}

Configuração de um Split de pagamento (com id)​

Este é o endpoint para cadastrar uma cobrança com um identificador de transação (id). O id é criado pela pessoa usuária recebedora e está sob sua responsabilidade. Caso o usuário informe um id que já exista, esse endpoint irá atualizar a configuração da cobrança.

PUT /v2/gn/split/config/:id
Requer autorização para o escopo: gn.split.write


Requisição

{
  "descricao": "Batatinha frita 1, 2, 3",
  "lancamento": {
    "imediato": true
  },
  "split": {
    "divisaoTarifa": "assumir_total",
    "minhaParte": {
      "tipo": "porcentagem",
      "valor": "60.00"
    },
    "repasses": [
      {
        "tipo": "porcentagem",
        "valor": "15.00",
        "favorecido": {
          "cpf": "12345678909",
          "conta": "1234567"
        }
      },
      {
        "tipo": "porcentagem",
        "valor": "25.00",
        "favorecido": {
          "cpf": "94271564656",
          "conta": "7654321"
        }
      }
    ]
  }
}

Respostas

As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.

{
  "id": "00000000000000000abcd",
  "status": "ATIVA",
  "descricao": "Batatinha frita 1, 2, 3",
  "txid": "SplitEstatico001",
  "lancamento": {
    "imediato": true
  },
  "split": {
    "divisaoTarifa": "assumir_total",
    "minhaParte": {
      "tipo": "porcentagem",
      "valor": "60.00"
    },
    "repasses": [
      {
        "tipo": "porcentagem",
        "valor": "15.00",
        "favorecido": {
          "conta": "1234567",
          "cpf": "12345678909"
        }
      },
      {
        "tipo": "porcentagem",
        "valor": "25.00",
        "favorecido": {
          "conta": "7654321",
          "cpf": "94271564656"
        }
      }
    ]
  }
}

Consultar configuração do Split por id​

Endpoint para consultar um Split de pagamento partir do id.

Atenção!

Atualmente, o endpoint está desativado para manutenção, portanto está temporariamente indisponível. Em breve, essa funcionalidade será restabelecida.


GET /v2/gn/split/config/:id
Requer autorização para o escopo: gn.split.read


Requisição

Também é possível consultar informações de uma revisão específica da configuração. Para isso é necessário informar o query param revisao. Exemplo: /v2/gn/split/config/:id?revisao=2. Quando o parâmetro não é informado, a revisão mais recente é retornada como padrão.

Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

{
  "id": "00000000000000000abcd",
  "status": "ATIVA",
  "revisao": 0,
  "descricao": "Batatinha frita 1, 2, 3",
  "lancamento": {
    "imediato": true
  },
  "split": {
    "divisaoTarifa": "assumir_total",
    "minhaParte": {
      "tipo": "porcentagem",
      "valor": "60.00"
    },
    "repasses": [
      {
        "tipo": "porcentagem",
        "valor": "15.00",
        "favorecido": {
          "conta": "1234567",
          "cpf": "12345678909"
        }
      },
      {
        "tipo": "porcentagem",
        "valor": "25.00",
        "favorecido": {
          "conta": "7654321",
          "cpf": "94271564656"
        }
      }
    ]
  }
}

Cobranças com Split​

O conjunto de endpoints a seguir é responsável pela gestão de cobranças com split de pagamento na API Pix. As cobranças, no contexto do Split, representam uma transação financeira entre um pagador e mais de um recebedor, cuja forma de pagamento é o Pix.

Criar uma cobrança​

Endpoint para cadastrar uma cobrança com um identificador de transação (txid).

Informação

Para consumir esse endpoint e gerar a cobrança, você pode seguir o mesmo exemplo do endpoint de geração de uma cobrança com :txid na API Pix seguindo esse link.


PUT /v2/cob/:txid
Requer autorização para o escopo: cob.write


Vincular uma cobrança a um Split de pagamento​

Este é o endpoint para vincular uma cobrança Pix a um Split de pagamento. Ele utiliza dois campos (txid da cobrança e splitConfigId do Split de pagamento) para fazer essa vinculação quando a cobrança Pix está ativa.

PUT /v2/gn/split/cob/:txid/vinculo/:splitConfigId
Requer autorização para o escopo: gn.split.write


Respostas

As respostas abaixo representam Sucesso(204) e Falhas/erros do consumo.

No content 
* O split foi vinculado à cobrança

Consultar cobrança com Split de pagamento por txid​

Endpoint para consultar uma cobrança com Split de pagamento a partir do txid.

GET /v2/gn/split/cob/:txid
Requer autorização para o escopo: gn.split.read


Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

{
  "calendario": {
    "criacao": "2020-09-09T20:15:00.358Z",
    "expiracao": "864000"
  },
  "txid": "7978c0c97ea847e78e8849634473c1f1",
  "revisao": 0,
  "status": "CONCLUIDA"
  "valor": {
    "original": "3.50"
  }, 
  "chave": "e8471824-640e-40d0-b300-39356a3b28c7",
  "loc": {
    "id": 48,
    "location": "qrcodespix.testesejaefi.com.br/v2/709c783e00ee4cc59f753435e1c492b1",
    "tipoCob": "cob",
    "criacao": "2020-09-09T20:15:00.358Z",
  },
  "location": "qrcodespix.testesejaefi.com.br/v2/",
  "pixCopiaECola": "00020101021226830014BR.GOV.BCB.PIX2561qrcodespix.sejaefi.com.br/v2/41e0badf811a4ce6ad8a80b306821fce5204000053000065802BR5905EFISA6008SAOPAULO60070503***61040000",
  "pix": {
    "endToEndId": "E090893562026042412492e0c4b9b253",
    "txid": "14a51086bad14ae2899e3b484f12bbe6",
    "valor": "3.50",
    "chave": "e8471824-640e-40d0-b300-39356a3b28c7",
    "horario": "2026-04-24T12:49:49.000Z",
    "devolucoes": {
      "id": "1",
      "rtrId": "D090893562026042412531bdf44c845e",
      "valor": "0.30",
      "horario": {
        "solicitacao": "2026-04-24T12:53:33.000Z"
      },
      "status": "NAO_REALIZADO",
      "id": "2",
      "rtrId": "D09089356202604241301d6fe779649d",
      "valor": "0.20",
      "horario": {
        "solicitacao": "2026-04-24T12:53:33.000Z",
        "liquidacao": "2026-04-24T13:01:36.000Z"
      },
      "status": "DEVOLVIDO",
    }
  }
  "config": {
    "id": "4d6aac6a548d4f7c9661a007064f03df",
    "status": "ATIVA",
    "revisao": 0,
    "descricao": "Config teste para devolução parcial",
    "tipo": "COBRANCA_DINAMICA"
  },
  "split": {
    "minhaParte": {
      "conta": "292929",
      "protocolo": 3444717411,
      "valor": 263,
      "protocoloTarifa": 3444717412,
      "valorTarifa": 10,
      "dataEfetivacao": "2026-04-24T12:49:51.000Z"
    },
    "repasses": {
      "conta": "292930",
      "protocolo": 3444717410,
      "valor": 87,
      "protocoloTarifa": 3444717409,
      "valorTarifa": 0,
      "dataEfetivacao": "2026-04-24T12:49:51.000Z"
    }
  }
}

Deletar o vínculo entre um Split de pagamento e uma cobrança​

Endpoint para deletar o vinculo entre um split de pagamento e uma cobrança a partir do txid.

DELETE /v2/gn/split/cob/:txid/vinculo
Requer autorização para o escopo: gn.split.write


Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

status: 200

Cobranças com vencimento e com Split​

O conjunto de endpoints a seguir é responsável pela gestão de cobranças com vencimento e com split de pagamento. As cobranças, no contexto do Split na API Pix, representam uma transação financeira entre um pagador e mais de um recebedores, cuja forma de pagamento é o Pix.


Criar uma cobrança com vencimento​

Endpoint para cadastrar uma cobrança com um identificador de transação (txid).

Informação

Para consumir esse endpoint e gerar a cobrança, você pode seguir o mesmo exemplo do endpoint de geração de uma cobrança com vencimento na API Pix seguindo esse link.


PUT /v2/cobv/:txid
Requer autorização para o escopo: cob.write


Vincular uma cobrança com vencimento a um Split de pagamento por txid​

Endpoint para vincular uma cobrança com vencimento (COBV) a um Split de pagamento.

PUT /v2/gn/split/cobv/:txid/vinculo/:splitConfigId
Requer autorização para o escopo: gn.split.write


Respostas

As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.

status 200

Consultar cobrança com vencimento e com Split de pagamento por txid​

Endpoint para consultar uma cobrança com vencimento e com a partir do txid.

GET /v2/gn/split/cobv/:txid
Requer autorização para o escopo: gn.split.read


Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

{
  "calendario": {
    "criacao": "2026-04-24T16:42:30.000Z"
    "dataDeVencimento": "2026-12-01"
    "validadeAposVencimento": 30
  },
  "txid": "aaazazdasddwdefdmf1777048949890",
  "revisao": 0,
  "status": "CONCLUIDA",
  "devedor": {
        "logradouro": "Alameda Souza, Numero 80, Bairro Braz",
        "cidade": "Recife",
        "uf": "PE",
        "cep": "70011750",
        "nome": "Francisco da Silva",
        "cpf": "12345678909"
  },
  "recebedor": {
    "logradouro": "Rua 15 Numero 1200, Bairro São Luiz",
    "cidade": "São Paulo",
    "uf": "SP",
    "cep": "70800100",
    "nome": "INTELLECTI SOLUTIONS LTDA",
    "cnpj": "32916731000178",
    "nomeFantasia": "Intellecti"
  },
  "valor": {
    "original": "4.45"
  },
  "chave": "5f84a4c5-c5cb-4599-9f13-7eb4d419dacc",
  "loc": {
    "id": 49,
    "location": "qrcodespix.testesejaefi.com.br/v2/cobv/85fa1eb7e430489087afbafb718e8727",
    "tipoCob": "cobv"
    "criacao": "2026-04-24T16:42:30.000Z"
  },
  "pixCopiaECola": "00020101021226880014BR.GOV.BCB.PIX2116qrcodespix.sejaefi.com.br/v2/cobv/c24c8d65fd024836bc7bac75d5c4002f5204000053039865802BR5905EFISA6008SAOPAULO62070503***6304C225"
  "pix": {
    "endToEndId": "E09089356202604241708ab512913aa8",
    "txid": "aaazazdasddwdefdmf1777048949890",
    "valor": "4.45",
    "chave": "e8471824-640e-40d0-b300-39356a3b28c7",
    "horario": "2026-04-24T17:09:16.000Z",
    "devolucoes": {
        "id": "1",
        "rtrId": "D09089356202604241711e418d7bc50c",
        "valor": "0.20",
        "horario": {
          "solicitacao": "2026-04-24T17:11:55.000Z",
          "liquidacao": "2026-04-24T17:11:55.000Z"
          },
        "status": "DEVOLVIDO"
    }
  }
  "config": {
    "id": "e26b53a986664c398462ec2871c124de",
    "status": "ATIVA",
    "revisao": 0,
    "descricao": "Config teste para devolução parcial cobv 1777048968785",
    "tipo": "COBRANCA_DINAMICA"
  },
  "split": {
    "minhaParte": {
      "conta": "29259",
      "protocolo": 3444717451,
      "valor": 334,
      "valorTarifa": 0,
      "dataEfetivacao": "2026-04-24T17:09:17.000Z"
    }
    "repasses": {
        "conta": "29260",
        "protocolo": 3444717450,
        "valor": 111,
        "valorTarifa": 0,
        "dataEfetivacao": "2026-04-24T17:09:17.000Z"
    }
  }
}

Solicitar devolução de uma cobrança Pix com Split de pagamento​

Este é o endpoint usado para solicitar uma devolução de Split usando o e2eid do Pix.

Atenção!

A devolução de Split Pix debita apenas da conta integradora, que é a conta principal que fez a configuração e definiu os repasses de Split Pix. As contas filhas, que receberam uma fatia do Split Pix, não sofrem nenhum débito e também não recebem nenhuma informação sobre a devolução do Pix.


PUT /v2/gn/split/pix/:e2eid/devolucao/:id
Requer autorização para o escopo: gn.pix.write


Requisição

{
"valor": "0.01"
}

Respostas

As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.

{
  "id": "identificadorUnico001",
  "rtrId": "D09089356202604092025abcdefg1234",
  "valor": "0.01",
  "horario": {
      "solicitacao": "2026-04-09T20:25:25.955Z"
  },
  "status": "EM_PROCESSAMENTO"
}

Deletar o vínculo entre um Split de pagamento e uma cobrança com vencimento​

Endpoint para deletar o vinculo entre um split de pagamento e uma cobrança com vencimento a partir do txid.

DELETE /v2/gn/split/cobv/:txid/vinculo
Requer autorização para o escopo: gn.split.write


Respostas

As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.

status: 200
Última atualização em