Split por fatura
O que você irá aprender com esse artigo?
- Como criar forma de pagamento
- Como configurar o split por fatura
- Diferença entre Split por conta e split por fatura
- Como efetuar cobrança com cartão de crédito
Caso de uso
"O meu Marketplace não tem um padrão no split, ou seja, no repasse para as subcontas ou conta mestre, por exemplo. Em uma transação de um produto A, será separado 10% do valor total da compra e enviado para uma subconta, porém em outra transação de um produto B, o percentual muda para 5%, mas é enviado para essa mesma subconta. Nesse cenário não é possível manter uma única configuração para a subconta, desta forma é necessário enviar a configuração do split em toda a fatura."
Diagrama de sequência
Atenção!
O split de pagamento pode ser configurado para qualquer método de pagamento (PIX, boleto e cartão de crédito). Esse artigo irá mostrar como funciona para cartão de crédito, mas sua configuração pode ser replicada para os outros métodos.
Criar Cliente
Essa request é usada para realizar o cadastro do cliente na API Criar Cliente. Indicamos que caso exista a necessidade de utilizar o método de pagamento boleto, preencher os dados de endereço.
Modelo de request
curl --location --request POST 'https://api.iugu.com/v1/customers' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=0061e0ce76c9748e57cfd03b25563473a0fe496a-1626699286' \
--data-raw '{
"email": "[email protected]",
"name": "teste de sousa beserra",
"phone_prefix": 11,
"phone": 988776655,
"cpf_cnpj": "551.340.520-26",
"cc_emails": "[email protected]",
"zip_code": "09550000",
"number": "001",
"street": "Rua Conselheiro Lafayette",
"city": "São Caetano do Sul",
"state": "SP",
"district": "Santa Paula",
"complement": "151 "
}'
Modelo de response
Para realizar uma transação com cartão de crédito, é necessário realizar a Tokenização do cartão de crédito.
Se sua empresa não for PCI DSS
Indicamos que utilize o iugu.js, ao inserir esse trecho de código javascript em sua webpage, você garante que os dados de cartão de crédito serão transacionados apenas pelo front-end da sua aplicação, trazendo segurança para o seu negócio.
O iugu.js irá te retornar um token que deve ser usado para criar a forma de pagamento, ou realizar uma cobrança direta.
Caso sua empresa seja certificada PCI DSS
Deve ser realizado um POST na api Criar Token, onde será gerado um token id e retornado no response da api.
Modelo de request
curl --location --request POST 'https://api.iugu.com/v1/payment_token' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=ca1be8a3bc81800098d0c3711c4f38bddca4926f-1626092966' \
--data-raw '{
"data": {
"number": "4111111111111111",
"verification_value": "123",
"first_name": "Customer ",
"last_name": "Tester",
"month": "06",
"year": "2024"
},
"account_id": "{{account_id}}",
"method": "credit_card"
}'
Modelo de response
Criar forma de pagamento
Caso exista a necessidade de armazenar os dados do cartão de crédito para utilizar em outras cobranças, é necessário criar uma forma de pagamento.
Com o token gerado na chamada “Tokenização” é preciso criar uma forma de pagamento, através de um POST na API Criar Forma de Pagamento, que irá retornar um id, identificador desse novo cartão crédito.
Modelo de request
curl --location --request POST 'https://api.iugu.com/v1/customers/{{customer_id}}/payment_methods' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=ca1be8a3bc81800098d0c3711c4f38bddca4926f-1626092966' \
--data-raw '{
"token": "31d033ce-c21f-44a3-afd4-ad547fb0eca7",
"description": "Teste 3",
"set_as_default": true
}'
Modelo de response
Atenção!
É importante armazenar o id da forma de pagamento caso exista a necessidade de realizar o processo de aquisição para outras subcontas ou produtos.
Saiba que:
Caso exista a necessidade de replicar o cartão de crédito, para uso em outras subcontas indicamos que leia esse artigo aqui.
Configuração do split por faturas
Para realizar a configuração do split se faz necessário criar uma invoice. Para isso é necessário realizar um POST na API Criar Fatura nela é possível configurar como será seu split.
Na iugu, é possível realizar esse procedimento por porcentagem, valor fixo(centavos), parcelas e pelo método de pagamento.
Via API, é possível definir se será entre subcontas, contas mestre, ou ambos os tipos de conta.
Split Subconta para Conta Mestre
Caso queira apenas realizar o split da subconta para a conta mestre, você deve preencher o array de Splits.
Se você precisa realizar um split para todos os métodos de pagamento com um valor, ou porcentagem fixa, indicamos que você preencha as propriedades cents e percents do array de objetos Splits e informe o identificador da conta Mestre, desta forma, a iugu irá sempre splitar para essa conta mestre o valor definido em cada propriedade.
Para saber o identificador da conta Mestre, veja aqui.
Na prática, optar por uma combinação de tipos de split serve para você, por exemplo, definir uma taxa de comissão por transação, definindo um valor fixo (cents), e um percentual (percents) sobre o valor total do recebimento.
Você ainda conta com a flexibilidade de poder definir valores específicos para cada método de pagamento (Boleto, Cartão de Crédito e Pix), seja ele por porcentagem, ou valor fixo. Para isso, basta preencher o array splits, configurando o cartão de crédito (credit_card), boleto bancário (bank_split), ou o Pix.
Para configurar com combinação do split por valor fixo e porcentagem, preencha os dois campos e mantenha como true a propriedade permit_aggregated.
Modelo de request
curl --location --request POST 'https://api.iugu.com/v1/invoices' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=0061e0ce76c9748e57cfd03b25563473a0fe496a-1626699286' \
--data-raw '{
"ensure_workday_due_date": false,
"payer": {
"address": {
"zip_code": "09440-000",
"street": "Sao Paulo",
"number": "1234",
"city": "São Caetano do sul",
"state": "SP",
"country": "BR",
"complement": "AP 2",
"district": "Santa"
},
"cpf_cnpj": "xxxxxxxxxxxxxx",
"name": "teste 2",
"email": "[email protected]"
},
"items": [
{
"description": "item de teste ",
"quantity": 1,
"price_cents": 1500
}
],
"payable_with": [
"all"
],
"commissions": {
"cents": 1000,
"credit_card_percent": 5,
"bank_slip_percent": 5,
"pix_percent": 5
},
"email": "[email protected]",
"due_date": "2021-07-19",
"per_day_interest": true,
"per_day_interest_value": 10,
"order_id": "7"
}'
Modelo de response
Múltiplo splits
Na iugu é possível realizar múltiplos splits, ou seja, o valor da compra pode ser dividido entre uma ou mais subcontas e contas mestre.
Para realizar a configuração do seu múltiplo split, é necessário preencher o array splits, onde cada novo objeto será uma conta.
A propriedade recipient_account_id, representa o id da conta iugu. Para mais informações de como consultar esse id, consulte esse artigo aqui.
Assim como o objeto comissions no array splits, é possível configurar o split por porcentagem, centavos, métodos de pagamento, parcelas da fatura, ou cobrando um valor fixo mais um percentual.
Modelo de request
curl --location --request POST 'https://api.iugu.com/v1/invoices' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=0061e0ce76c9748e57cfd03b25563473a0fe496a-1626699286' \
--data-raw '{
"ensure_workday_due_date": false,
"payer": {
"address": {
"zip_code": "09550-000",
"street": "Sao Paulo",
"number": "2330",
"city": "São Caetano do sul",
"state": "SP",
"country": "BR",
"complement": "AP 61",
"district": "Santa Paula"
},
"cpf_cnpj": "3591484928",
"name": "iugu",
"email": "[email protected]"
},
"items": [
{
"description": "item",
"quantity": 1,
"price_cents": 100
}
],
"payable_with": [
"pix"
],
"splits": [
{
"recipient_account_id": "{{account_id}}",
"percent": 10,
"bank_slip_percent": 5,
"credit_card_percent": 5,
"pix_percent": 5,
"permit_aggregated": true
}
],
"email": "[email protected]",
"due_date": "2021-07-19",
"per_day_interest": true,
"per_day_interest_value": 10,
"order_id": "9"
}'
Modelo de response
Diferença entre Split por conta e split por fatura
A diferença entre o split por conta e o split por fatura é que no split por conta a configuração é padrão, ou seja, sempre será executado para as mesmas contas e com os mesmos valores, conforme definido na conta. Em contrapartida, o split por fatura é um split customizável, isso significa que a cada fatura pode ser enviado diferentes contas recebedoras e diferentes valores de comissão.
Efetuar cobrança com cartão de crédito
Para realizar a cobrança com cartão de crédito é necessário realizar um POST na API Cobrança Direta.
Nessa requisição, você deve preencher o id da forma de pagamento (customer_payment_method_id) ou o token do cartão de crédito(token_id).
curl --location --request POST 'https://api.iugu.com/v1/charge'\
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=0061e0ce76c9748e57cfd03b25563473a0fe496a-1626699286' \
--data-raw '{
"payer": {
"address": {
"street": "Conselheiro Lafayetti",
"number": "155",
"district": "São Paulo",
"city": "São Caetano do Sul",
"state": "SP",
"zip_code": "09550-000",
"complement": "AP 61"
},
"cpf_cnpj": "xxxxx",
"name": "de sousa beserra",
"phone": ""
},
"token": "8c3d3a21-7d29-4b92-8e2e-57befb0f4444",
"order_id": "TESTE13",
"email": "[email protected]",
"invoice_id": "38CFC6AB57C5449A91F7896B9197C87B"
}'
Updated over 3 years ago