Skip to main content

Pix payment split

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.

Information

The 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 Environment

In 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

{
"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"
}
}
]
}
}

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"
}
}
]
}
}

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

{
"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"
}
}
]
}
}

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"
}
}
]
}
}

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"
}
}
]
}
}

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

Information

To 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


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

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"
}

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.

status: 200

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

Information

To 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


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.

status 200

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"
}

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.

status: 200