In this section, you will find all available endpoints for performing Payment Split in the Efí's Pix API.
Payment Split Configuration
Important!The Pix Payment Split can only be performed between Efí accounts, with a maximum limit of 20 accounts for the split.
NOTE: It is not possible to refund charges that were passed on to other accounts through the split.
The following set of endpoints is responsible for configuring Payment Splits in the Pix API. Charges, in the context of the Pix API, represent a financial transaction between a payer and a receiver, whose payment method is Pix.
InformationThe same Split configuration can be used in various charges. This means that you can define a division of values for a partner and apply it to all related charges.
Configure Payment Split in QR Code and static copy and paste!You have the flexibility to divide the payment of QR Codes and static copy and paste among different Efí accounts. This means that when generating a QR Code or a static copy and paste code for payment, you can specify how the received amount will be distributed, facilitating financial management and ensuring that funds are allocated correctly from the start.
Instructions for Testing in Sandbox EnvironmentIn the payment split process, it is essential to provide a valid EFÍ digital account.
It is important to note that it is not possible to split to your own account. Therefore, if you are testing in a Sandbox environment and do not have a valid account for the splits, you will need to create a sub-account. See how to do this here.
Payment Split Configuration (without providing an id)
Endpoint to create a Payment Split without specifying an id.
Generally, the id is created by the receiving party and is their responsibility. However, in this case, the id will be defined by Efí, making an exception to the standard rule.
POST /v2/gn/split/config
Requires authorization for the scope: gn.split.write
Request
- Example config dynamic percentage
- Example config dynamic fixed
- Example config static
{
"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"
}
}
]
}
}
{
"descricao": "Batatinha frita 1, 2, 3",
"lancamento": {
"imediato": true
},
"split": {
"divisaoTarifa": "assumir_total",
"minhaParte": {
"tipo": "fixo",
"valor": "50.00"
},
"repasses": [
{
"tipo": "fixo",
"valor": "5.00",
"favorecido": {
"cpf": "12345678909",
"conta": "1234567"
}
},
{
"tipo": "fixo",
"valor": "10.00",
"favorecido": {
"cpf": "94271564656",
"conta": "7654321"
}
}
]
}
}
{
"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": {
"cpf": "12345678909",
"conta": "1234567"
}
},
{
"tipo": "porcentagem",
"valor": "25.00",
"favorecido": {
"cpf": "94271564656",
"conta": "7654321"
}
}
]
}
}
Responses The responses below represent Success(201) and consumption failures/errors.
{
"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"
}
}
]
}
}
{
"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"
}
]
}
Payment Split Configuration (with id)
This is the endpoint to register a charge with a transaction identifier (id). The id is created by the receiving user and is their responsibility. If the user provides an id that already exists, this endpoint will update the charge configuration.
PUT /v2/gn/split/config/:id
Requires authorization for the scope: cgn.split.write
Request
- Example config dynamic percentage
- Example config dynamic fixed
- Example config static
{
"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"
}
}
]
}
}
{
"descricao": "Batatinha frita 1, 2, 3",
"lancamento": {
"imediato": true
},
"split": {
"divisaoTarifa": "assumir_total",
"minhaParte": {
"tipo": "fixo",
"valor": "50.00"
},
"repasses": [
{
"tipo": "fixo",
"valor": "5.00",
"favorecido": {
"cpf": "12345678909",
"conta": "1234567"
}
},
{
"tipo": "fixo",
"valor": "10.00",
"favorecido": {
"cpf": "94271564656",
"conta": "7654321"
}
}
]
}
}
{
"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": {
"cpf": "12345678909",
"conta": "1234567"
}
},
{
"tipo": "porcentagem",
"valor": "25.00",
"favorecido": {
"cpf": "94271564656",
"conta": "7654321"
}
}
]
}
}
Responses The responses below represent Success(201) and consumption failures/errors.
{
"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"
}
}
]
}
}
{
"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"
}
]
}
Get Payment Split Configuration by id
Endpoint to retrieve a Payment Split configuration by id.
GET /v2/gn/split/config/:id
Requires authorization for the scope: gn.split.read
Request
It's also possible to query information from a specific revision of the configuration. To do this, it's necessary to provide the revisao query param. Example:
/v2/gn/split/config/:id?revisao=2. When the parameter is not provided, the most recent revision is returned by default.
Responses The responses below represent Success(200) and consumption failures/errors.
{
"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."
}
Split charges
The following set of endpoints is responsible for managing charges with payment split in the Pix API. Charges, in the context of Split, represent a financial transaction between a payer and multiple receivers, whose payment method is Pix.
Create Charge
Endpoint to register a charge with a transaction identifier (txid).
InformationTo consume this endpoint and generate the charge, you can follow the same example from the immediate charge generation endpoint with :txid in the Pix API by following this link.
PUT /v2/cob/:txid
Requires authorization for the scope: cob.write
Link a Charge to a Payment Split
This is the endpoint to link a Pix charge to a Payment Split. It uses two fields (charge txid and Payment Split splitConfigId) to make this linkage when the Pix charge is active.
PUT /v2/gn/split/cob/:txid/vinculo/:splitConfigId
Requires authorization for the scope: gn.split.write
Responses The responses below represent Success(204) and consumption failures/errors.
No content
* O split 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
"razao": "O valor da cobrança não corresponde à soma dos valores fixos da configuração de split."
Ou
"propriedade": "cobv.status"
Ou
"propriedade": "cob.status"
Ou
"propriedade": "split.config.status"
Ou
"propriedade": "cob.valor.original"
Ou
"propriedade": "cobv.valor.original"
}
]
}
{
"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."
}
Get Charge with Payment Split by txid
Endpoint to retrieve a charge with Payment Split using the txid.
GET /v2/gn/split/cob/:txid
Requires authorization for the scope: gn.split.read
Responses The responses below represent Success(200) and consumption failures/errors.
{
"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"
}
{
"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"
}
Delete the link between a Payment Split and a charge
Endpoint to delete the link between a Payment Split and a charge using the txid.
DELETE /v2/gn/split/cob/:txid/vinculo
Requires authorization for the scope: gn.split.write
Responses The responses below represent Success(200) and consumption failures/errors.
{
"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."
}
Due charges and Payment Split
The following set of endpoints is responsible for managing due charges and payment split in the Pix API. Charges, in the context of Split in the Pix API, represent a financial transaction between a payer and multiple receivers, whose payment method is Pix.
Create Due Charge
Endpoint to register a due charge with a transaction identifier (txid).
InformationTo consume this endpoint and generate the charge, you can follow the same example from the endpoint for generating a charge with due date in the Pix API by following this link.
PUT /v2/cobv/:txid
Requires authorization for the scope: cob.write
Link a due charge a Payment Split by txid
Endpoint to link a charge with due date (COBV) to a Payment Split.
PUT /v2/gn/split/cobv/:txid/vinculo/:splitConfigId
Requires authorization for the scope: gn.split.write
Responses The responses below represent Success(201) and consumption failures/errors.
{
"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."
}
Get due charge and Payment Split by txid
Endpoint to retrieve a charge with due date and Payment Split using the txid.
GET /v2/gn/split/cobv/:txid
Requires authorization for the scope: gn.split.read
Responses The responses below represent Success(200) and consumption failures/errors.
{
"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"
}
{
"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"
}
Delete the link between a Payment Split and a due charge
Endpoint to delete the link between a Payment Split and a charge with due date using the txid.
DELETE /v2/gn/split/cobv/:txid/vinculo
Requires authorization for the scope: gn.split.write
Responses The responses below represent Success(200) and consumption failures/errors.
{
"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."
}