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


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 QRCode e copia e cola estático!

Você tem a flexibilidade de dividir o pagamento dos QRCodes 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(201) 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
Última atualização em