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.

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",
"dataDeVencimento": "2020-12-31",
"validadeAposVencimento": 30
},
"txid": "7978c0c97ea847e78e8849634473c1f1",
"revisao": 0,
"loc": {
"id": 789,
"location": "pix.example.com/qr/c2/cobv/9d36b84fc70b478fb95c12729b90ca25",
"tipoCob": "cobv"
},
"status": "ATIVA",
"devedor": {
"logradouro": "Alameda Souza, Numero 80, Bairro Braz",
"cidade": "Recife",
"uf": "PE",
"cep": "70011750",
"cpf": "12345678909",
"nome": "Francisco da Silva"
},
"valor": {
"original": "123.45"
},
"chave": "5f84a4c5-c5cb-4599-9f13-7eb4d419dacc",
"solicitacaoPagador": "Cobrança dos serviços prestados.",
"config": {
"id": "6aeddee74dd1a890c0ace00000000a",
"status": "ATIVA",
"descricao": "Batatinha frita"
},
"pixCopiaECola": "00020101021226830014BR.GOV.BCB.PIX2561qrcodespix.sejaefi.com.br/v2/41e0badf811a4ce6ad8a80b306821fce5204000053000065802BR5905EFISA6008SAOPAULO60070503***61040000"
}

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": "2020-09-09T20:15:00.358Z",
"dataDeVencimento": "2020-12-31",
"validadeAposVencimento": 30
},
"txid": "7978c0c97ea847e78e8849634473c1f1",
"revisao": 0,
"loc": {
"id": 789,
"location": "pix.example.com/qr/c2/cobv/9d36b84fc70b478fb95c12729b90ca25",
"tipoCob": "cobv"
},
"status": "ATIVA",
"devedor": {
"logradouro": "Alameda Souza, Numero 80, Bairro Braz",
"cidade": "Recife",
"uf": "PE",
"cep": "70011750",
"cpf": "12345678909",
"nome": "Francisco da Silva"
},
"recebedor": {
"logradouro": "Rua 15 Numero 1200, Bairro São Luiz",
"cidade": "São Paulo",
"uf": "SP",
"cep": "70800100",
"cnpj": "56989000019533",
"nome": "Empresa de Logística SA"
},
"valor": {
"original": "123.45"
},
"chave": "5f84a4c5-c5cb-4599-9f13-7eb4d419dacc",
"solicitacaoPagador": "Cobrança dos serviços prestados.",
"config": {
"id": "6aeddee74dd1a890c0000070001",
"status": "ATIVA",
"descricao": "Batatinha frita"
},
"pixCopiaECola": "00020101021226880014BR.GOV.BCB.PIX2116qrcodespix.sejaefi.com.br/v2/cobv/c24c8d65fd024836bc7bac75d5c4002f5204000053039865802BR5905EFISA6008SAOPAULO62070503***6304C225"
}

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