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
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çãoUma 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.
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"
}
}
]
}
}
As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.
{
"id": "00000000000000000abcd",
"status": "ATIVA",
"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"
}
}
]
}
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/SplitConfigOperacaoInvalida",
"title": "Operação Inválida",
"status": 400,
"detail": "A requisição que busca alterar ou criar uma configuração de split não respeita o schema ou está semanticamente errada.",
"violacoes": [
{
"razao": "A configuração de split a ser alterada não está mais ATIVA."
Ou
"razao": "A configuração de split a ser alterada não é do tipo informado."
Ou
"razao": "No momento, lançamentos só podem ser feitos de forma imediata."
Ou
"razao": "Os parâmetros de lançamento estão semanticamente incorretos ou com campos ausentes."
Ou
"razao": "O tipo especificado para a divisão de tarifa é invalido."
Ou
"razao": "O tipo do valor especificado é inválido."
Ou
"razao": "A soma total das porcentagens é inválida, resulta em mais de cem porcento."
Ou
"razao": "A soma total das porcentagens é inválida, não atinge cem porcento."
Ou
"razao": "A soma total das porcentagens atinge cem porcento mas também foi especificado valores fixos, incorretamente."
Ou
"razao": "Uma das contas informadas na configuração dos repasses não existe."
Ou
"razao": "O documento de uma das contas informadas na configuração dos repasses não condiz com o documento real da conta."
Ou
"razao": "Um dos valores informados na configuração dos repasses é inválido, deve ser maior que zero."
Ou
"propriedade": "split.config"
Ou
"propriedade": "split.config.lancamento"
Ou
"propriedade": "split.config.split"
Ou
"propriedade": "split.config.split.minhaParte"
Ou
"propriedade": "split.config.split.repasses"
}
]
}
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"
}
}
]
}
}
As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.
{
"id": "00000000000000000abcd",
"status": "ATIVA",
"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"
}
}
]
}
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/SplitConfigOperacaoInvalida",
"title": "Operação Inválida",
"status": 400,
"detail": "A requisição que busca alterar ou criar uma configuração de split não respeita o schema ou está semanticamente errada.",
"violacoes": [
{
"razao": "A configuração de split a ser alterada não está mais ATIVA."
Ou
"razao": "A configuração de split a ser alterada não é do tipo informado."
Ou
"razao": "No momento, lançamentos só podem ser feitos de forma imediata."
Ou
"razao": "Os parâmetros de lançamento estão semanticamente incorretos ou com campos ausentes."
Ou
"razao": "O tipo especificado para a divisão de tarifa é invalido."
Ou
"razao": "O tipo do valor especificado é inválido."
Ou
"razao": "A soma total das porcentagens é inválida, resulta em mais de cem porcento."
Ou
"razao": "A soma total das porcentagens é inválida, não atinge cem porcento."
Ou
"razao": "A soma total das porcentagens atinge cem porcento mas também foi especificado valores fixos, incorretamente."
Ou
"razao": "Uma das contas informadas na configuração dos repasses não existe."
Ou
"razao": "O documento de uma das contas informadas na configuração dos repasses não condiz com o documento real da conta."
Ou
"razao": "Um dos valores informados na configuração dos repasses é inválido, deve ser maior que zero."
Ou
"propriedade": "split.config"
Ou
"propriedade": "split.config.lancamento"
Ou
"propriedade": "split.config.split"
Ou
"propriedade": "split.config.split.minhaParte"
Ou
"propriedade": "split.config.split.repasses"
}
]
}
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"
}
}
]
}
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/SplitConfigNaoEncontrado",
"title": "Não Encontrado",
"status": 404,
"detail": "Configuração de split não encontrada para o id informado."
}
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
As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.
No content
* O spit foi vinculado à cobrança
{
"type": "https://pix.bcb.gov.br/api/v2/error/SplitOperacaoInvalida",
"title": "Operação Inválida",
"status": 400,
"detail": "A requisição que busca alterar ou criar um vínculo entre cobrança e configuração de split não respeita o schema ou está semanticamente errada.",
"violacoes": [
{
"razao": "A cobrança já existe, não está ATIVA, e a presente requisição busca vinculá-la."
Ou
"razao": "A configuração de split já existe, não está ATIVA, e a presente requisição busca vinculá-la."
Ou
"propriedade": "cobv.status"
Ou
"cob.status"
Ou
"split.config.status"
}
]
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/SplitNaoEncontrado",
"title": "Não encontrado",
"status": 404,
"detail": "Cobrança não encontrada."
Ou
"detail": "Configuração de Split não encontrada."
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/SplitErroInterno",
"title": "Erro interno",
"status": 500,
"detail": "Ocorreu um erro na criação do vínculo entre cobrança e configuração de split."
Ou
"detail": "'Ocorreu um erro na alteração do vínculo entre cobrança e configuração de split."
}
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
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"
}
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/CobrancaSplitNaoEncontrada",
"title": "Não encontrado",
"status": 404,
"detail": "Cobrança não encontrada."
Ou
"detail": "A cobrança informada não possui configuração de split vinculada."
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/CobrancaSplitNaoEncontrada",
"title": "Erro interno",
"status": 500,
"detail": "Ocorreu um erro interno ao processar a requisição"
}
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
As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.
{
"type": "https://pix.bcb.gov.br/api/v2/error/SplitOperacaoInvalida",
"title": "Operação Inválida",
"status": 400,
"detail": "A requisição que busca remover um vínculo entre cobrança e configuração de split não respeita o schema ou está semanticamente errada.",
"violacoes": [
{
"razao": "Algum dos parâmetros informados não respeita o schema.",
"propriedade": "split.params.txid"
}
]
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/SplitOperacaoInvalida",
"title": "Operação inválida",
"status": 400,
"detail": "A requisição que busca remover um vínculo entre cobrança e configuração de split não respeita o schema ou está semanticamente errada.",
"violacoes": [
{
"razao": "A cobrança não está ATIVA, invalidando a presente operação.",
"propriedade": "cob.status"
}
]
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/SplitNaoEncontrado",
"title": "Não encontrado",
"status": 404,
"detail": "A cobrança informada não possui configuração de split vinculada."
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/SplitNaoEncontrado",
"title": "Não encontrado",
"status": 404,
"detail": "Cobrança não encontrada."
}
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.
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
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
As respostas abaixo representam Sucesso(201) e Falhas/erros do consumo.
{
"type": "https://pix.bcb.gov.br/api/v2/error/SplitOperacaoInvalida",
"title": "Operação inválida",
"status": 400,
"detail": "A requisição que busca alterar ou criar um vínculo entre cobrança e configuração de split não respeita o schema ou está semanticamente errada."
"violacoes": [
{
"razao": "A cobrança já existe, não está ATIVA, e a presente requisição busca vinculá-la."
Ou
"razao": "A configuração de split já existe, não está ATIVA, e a presente requisição busca vinculá-la."
"propriedade":"cobv.status"
Ou
"propriedade":"cob.status"
Ou
"propriedade":"split.config.status"
}
]
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/SplitNaoEncontrado",
"title": "Não encontrado",
"status": 404,
"detail": "Cobrança não encontrada."
Ou
"detail": "Configuração de Split não encontrada."
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/SplitErroInterno",
"title": "Erro interno",
"status": 500,
"detail": "Ocorreu um erro na criação do vínculo entre cobrança e configuração de split."
Ou
"detail": "Ocorreu um erro na alteração do vínculo entre cobrança e configuração de split."
}
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
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"
}
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/CobrancaSplitNaoEncontrada",
"title": "Não encontrado",
"status": 404,
"detail": "Cobrança não encontrada."
Ou
"detail": "A cobrança informada não possui configuração de split vinculada."
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/ErroInterno",
"title": "Erro interno",
"status": 500,
"detail": "Ocorreu um erro interno ao processar a requisição"
}
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
As respostas abaixo representam Sucesso(200) e Falhas/erros do consumo.
{
"type": "https://pix.bcb.gov.br/api/v2/error/SplitOperacaoInvalida",
"title": "Operação Inválida",
"status": 400,
"detail": "A requisição que busca remover um vínculo entre cobrança e configuração de split não respeita o schema ou está semanticamente errada.",
"violacoes": [
{
"razao": "Algum dos parâmetros informados não respeita o schema.",
"propriedade": "split.params.txid"
}
]
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/SplitOperacaoInvalida",
"title": "Operação inválida",
"status": 400,
"detail": "A requisição que busca remover um vínculo entre cobrança e configuração de split não respeita o schema ou está semanticamente errada.",
"violacoes": [
{
"razao": "A cobrança não está ATIVA, invalidando a presente operação.",
"propriedade": "cobv.status"
}
]
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/SplitNaoEncontrado",
"title": "Não encontrado",
"status": 404,
"detail": "A cobrança informada não possui configuração de split vinculada."
}
{
"type": "https://pix.bcb.gov.br/api/v2/error/SplitNaoEncontrado",
"title": "Não encontrado",
"status": 404,
"detail": "Cobrança não encontrada."
}