Skip to main content

Split payment

Step by step to generate a charge with the split payment configuration in the Efí API


Introduction​

Important!

Payment Split can only be performed between Efí accounts, with no maximum limit on the number of accounts for the transfer.


The Efí Payment Split can be used in situations where the amount paid by the buyer needs to be divided among two or more sellers, according to a percentage or fixed value defined at the time the charge is created.

The concept of Payment Split is simple. It is an online retail environment where multiple sellers offer their products in one place. Imagine it as a virtual mall, where various stores come together to sell different products and services, offering a wider variety of options to customers.

With Efí Payment Split, any Efí account can create its own sales platform with multiple sellers. With this solution, you can use your website to make sales and, through integration, define how the received amount will be divided among the different Efí accounts. This works for both your account and those of your partners, enabling a more complete and integrated shopping experience.


How it works​

  • If an item in a transaction is marked as a payment Split item, all items will be considered payment Split items;

  • The integrator has the flexibility to configure the split, choosing between percentage division or a fixed amount. In percentage transfer configurations, the Efí intermediation fee can be configured in two ways: mode = 1 for the fee to be deducted only from the main account that issued the charge, and mode = 2 for the fee to be deducted proportionally to the percentage defined for each account receiving the transfer. If the mode attribute is not provided in the request, the default will be mode = 2.

  • In fixed amount transfer configurations, the fee must be deducted only from the main account that generated the charge. Therefore, the integrator must specify mode = 1.

  • When using percentage division, if the total transfers of an item are less than 100%, the remaining amount will be automatically transferred to the integrator's account. If the total transfers of an item exceed 100%, the transaction cannot be generated;

  • When using fixed amount division, if the total transfers of an item are less than the total charge amount, the remaining amount will be automatically transferred to the integrator's account. If the total transfers of an item exceed the total charge amount, the transaction cannot be generated;

  • Payment Split transfers are made individually for each product in the charge. Each product can have transfers to different accounts in the same charge;

  • It is not possible to make a partial transfer of the shipping amount;

  • For the Payment Split to work, the only necessary data is the account identifier ("payee_code") of the accounts that will receive the transfers;

  • Transfers cannot have a value equal to zero percent;

  • It is possible to generate charges with multiple items, some with Payment Split configuration and others without;

  • It is not possible to make two transfers to the same account on the same item;

  • It is allowed to have different or equal transfer amounts to the same account on different items of the same transaction.

Payment Split Configurations
Description of the attributes for configuring Payment Split



Creating a Payment Split Transaction in One Step​

In this option, the request body must contain all the minimum required attributes for issuing the title.

This option allows you to create a transaction and associate a payment method (bank slip or credit card) in just one step.

Important!

For One Step transaction creation to occur smoothly, it is necessary to update your SDK. All necessary files for this are available in our repository and in the documentation.


Hierarchical structure of Schema attributes that can be used:
"items"  
    "name"  
    "value"  
    "amount"  
    "marketplace" 
        "mode"
        "repasses" 
            "payee_code"  
            "percentage"  
            "fixed"
"shippings"  
    "name"  
    "value"  
    "payee_code"  
"metadata"  
    "custom_id"  
    "notification_url"  
"payment"  
    "banking_billet"  
        "customer"  
            "name"  
            "cpf"  
            "email"  
            "phone_number"  
            "birth"  
            "address"  
                "street"  
                "number"  
                "neighborhood"  
                "zipcode"  
                "city"  
                "complement"  
                "state"  
            "juridical_person"  
                "corporate_name"  
                "cnpj"  
        "expire_at"  
        "discount"  
            "type"  
                "percentage",  
                "currency"  
            "value"  
        "conditional_discount"  
            "type"  
                "percentage",  
                "currency"  
            "value"  
            "until_date"  
        "configurations"   
            "days_to_write_off" 
            "fine"
            "interest"  
                "value"
                "type"
        "message"
POST /v1/charge/one-step
Requires activation of the Billing API in your application


Request

{
  "items": [
    {
      "name": "Meu Produto",
      "value": 5990,
      "amount": 1,
      "marketplace": {
        "repasses": [
          {
            "payee_code": "payee_code1",
            "percentage": 2500
          },
          {
            "payee_code": "payee_code2",
            "percentage": 1500
          }
        ]
      }
    }
  ],
  "payment": {
    "banking_billet": {
      "customer": {
        "name": "Gorbadoc Oldbuck",
        "cpf": "94271564656",
        "email": "[email protected]",
        "phone_number": "5144916523",
        "address": {
          "street": "Avenida Juscelino Kubitschek",
          "number": "909",
          "neighborhood": "Bauxita",
          "zipcode": "35400000",
          "city": "Ouro Preto",
          "complement": "",
          "state": "MG"
        }
      },
      "expire_at": "2023-12-15",
      "configurations": {
        "fine": 200,
        "interest": 33
      },
      "message": "Usando o atributo message, este conteúdo é exibido no campo OBSERVAÇÃO da cobrança emitida via API 
       e também no campo OBSERVAÇÃO DO VENDEDOR nos e-mails de cobrança enviados ao cliente 
       É possível utilizar até 4 linhas de conteúdo, com no máximo 100 caracteres por linha 
       Essa mensagem poderá ser vista nos e-mails relacionados à cobrança, no boleto ou carnê"
    }
  }
}

Responses

The responses below represent consumption Success.

{
  "code": 200, // HTTP return "200" stating that the request was successful
  "data": {
    "barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000", // digitable line of the boleto
    "pix": {
      "qrcode": "00020101021226990014BR.GOV.BCB.PIX2577qrcodes-pix.gerencianet.com.br/bolix/v2/cobv/0000000000000000000000000000GERENCIANET SA6010OURO PRETO62070503***63047CB1", // BRCode or copy and paste
      "qrcode_image": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NSA0NSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48cGF0aCBmaWxsPSIjZmZmZmZmIiBkPSJNMCAwaDQ1djQ1SD..." // QR Code image
    },
    "link": "link_https_para_acesso_o_bolix", // responsive link to the generated Bolix
    "billet_link": "link_https_para_acesso_o_bolix", // link to the generated Bolix
    "pdf": {
      "charge": "link_https_do_pdf_da_cobranca" // link to the PDF of the Bolix
    },
    "expire_at": "2023-12-15", // due date of the boleto in the following format: 2022-12-15 (i.e., equivalent to 15/12/2022)
    "charge_id": numero_charge_id, // ID number of the generated transaction
    "status": "waiting", // selected payment method, awaiting payment confirmation ("waiting" equals "aguardando")
    "total": 5990, // value, in cents. For example: 5990 (equals R$ 59.90)
    "payment": "banking_billet" // payment method associated with this transaction ("banking_billet" equals "boleto bancário")
  }
}

Creating a Payment Split Transaction in Two Steps​

  1. Create the transaction, providing account(s) for payout, item/product/service, value, quantity, etc;
  2. Associate the desired payment method, providing the charge_id of the transaction and payer customer data.

The rest of this page presents detailed procedures, but remember to install one of our libraries on your server to execute the example codes. Make sure the Efí SDK has been installed.

1. Create transaction​

Transactions with at least one item defined as 'Split Payment item' or freight values destined to different accounts from the integrator account are called 'Split Payment Transactions'. With Efí Split Payment, it's possible to automatically divide the amount paid by the end customer between the seller and the supplier, without the need to do this manually.

To start, we need to generate the transaction, providing the Efí accounts for payout, the name of the item/product/service, the transaction value, quantity, and other relevant information.

It's important to note that the Efí intermediary fee can be configured in two ways: mode = 1, so that the fee is deducted only from the account that issued the charge, or mode = 2 so that the fee is deducted proportionally to the percentage defined for all accounts that will receive the payouts. If the mode attribute is not informed in the request, it will be set as default mode = 2.

In the example below, we show how to use payouts in a transaction of R$ 50.00. According to the code, the amount will be divided among 3 Efí accounts. The first account will receive 25% of the value, the second account will receive 15%, and the third will receive the remainder, which in this case is 60% of the value.

The payee_code attribute is the Efí 'account identifier' and will be used to identify the accounts that will receive the payouts. You can find this identifier on your platform at (see where to find it).

POST /v1/charge
Requires activation of the Billing API in your application


Request

{
  "items": [
    {
      "name": "Meu Produto",
      "value": 5990,
      "amount": 1,
      "marketplace": {
        "repasses": [
          {
            "payee_code": "payee_code1",
            "percentage": 2500
          },
          {
            "payee_code": "payee_code2",
            "percentage": 1500
          }
        ]
      }
    }
  ]
}

Responses

The responses below represent consumption Success.

{
  "code": 200, // HTTP return "200" stating that the request was successful
  "data": {
    "charge_id": numero_charge_id, // ID number of the generated transaction
    "status": "new", // charge generated, waiting for payment method to be defined
    "total": 8900, // total amount of the transaction (in cents, where 8900 = R$89.00)
    "custom_id": null, // optional custom identifier
    "created_at": "2021-06-01 14:58:46" // date and time of transaction creation
  }
}

2. Associate with payment method via boleto​

After creating the Split Payment transaction, you will receive the charge_id. This identifier will be used for you to choose which payment method you want to use for this transaction.

POST /v1/charge/:id/pay
Requires activation of the Billing API in your application


Request

{
  "payment": {
    "banking_billet": {
      "customer": {
        "name": "Gorbadoc Oldbuck",
        "cpf": "94271564656",
        "email": "[email protected]",
        "phone_number": "5144916523",
        "address": {
          "street": "Avenida Juscelino Kubitschek",
          "number": "909",
          "neighborhood": "Bauxita",
          "zipcode": "35400000",
          "city": "Ouro Preto",
          "complement": "",
          "state": "MG"
        }
      },
      "expire_at": "2023-12-30",
      "configurations": {
        "fine": 200,
        "interest": 33
      },
      "message": "Pague pelo código de barras ou pelo QR Code"
    }
  }
}

Responses

The responses below represent consumption Success.

{
  "code": 200, // HTTP return "200" stating that the request was successful
  "data": {
    "barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000", // typable line of the boleto
    "pix":{
      "qrcode": "00020101021226990014BR.GOV.BCB.PIX2577qrcodes-pix.gerencianet.com.br/bolix/v2/cobv/0000000000000000000000000000GERENCIANET SA6010OURO PRETO62070503***63047CB1", // BRCode or copy and paste
      "qrcode_image": "data: image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmc vMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NSA0NSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48cGF0aCBmaWxsPSIjZmZmIiBkPSJNMCAwaDQ1djQ1SD. .." // QR Code imagem
    },
    "link": "link_https_to_access_the_bolix", // responsive Bolix link generated
    "billet_link":"link_https_to_access_the_bolix", // Bolix link generated
    "pdf": {
      "charge":"link_https_do_pdf_da_cobranca" // Bolix PDF link
    },
    "expire_at": "2023-12-30", // expiration date of the boleto in the following format: 2022-12-15 (i.e. equivalent to 15/12/2022)
    "charge_id": numero_charge_id, // ID number of the transaction generated
    "status": "waiting", // payment method selected, waiting for payment confirmation 
    "total": 8900, // amount, in cents. For example: 5990 (equals R$59.90)
    "payment": "banking_billet" // payment method associated with this transaction 
}

Return information of existing transaction​

To retrieve information about a transaction (billet or credit card), you must send a GET request to the route /v1/charge/:id.

GET /v1/charge/:id
Requires activation of the Billing API in your application


Request

Input parameter: enter the "charge_id" of the desired transaction

Responses

The responses below represent consumption Success(200).

{
  "code": 200,
  "data": {
      "charge_id": 661176817,
      "total": 1100,
      "status": "waiting",
      "custom_id": null,
      "created_at": "2024-01-08 11:25:28",
      "notification_url": null,
      "items": [{
          "name": "Product 1",
          "value": 1000,
          "amount": 1,
          "marketplace": {
              "repasses": [{
                      "percentage": 1000,
                      "payee_code": "84569721306548792010354876123456"
                  },
                  {
                      "percentage": 9000,
                      "payee_code": "36987410213546789104587410235689"
                  }
              ]
          }
      }],
      "history": [{
              "message": "Cobrança criada",
              "created_at": "2024-01-08 11:25:28"
          },
          {
              "message": "Pagamento via boleto aguardando confirmação",
              "created_at": "2024-01-08 11:25:29"
          },
          {
              "message": "Cobrança enviada para [email protected]",
              "created_at": "2024-01-08 11:25:29"
          }
      ],
      "shippings": [{
          "name": "Default Shipping Cost",
          "value": 100,
          "payee_code": "3804b62b6241d2ae9dd0896297d4ea74"
      }],
      "customer": {
          "name": "Gorbadoc Oldbuck",
          "cpf": "94271564656",
          "birth": "1977-01-15",
          "email": "[email protected]",
          "phone_number": "5144916523"
      },
      "payment": {
          "method": "banking_billet",
          "created_at": "2024-01-08 11:25:28",
          "message": null,
          "banking_billet": {
              "barcode": "00000.00000 00000.000000 00000.000000 0 00000000000000",
              "pix": {
                  "qrcode": "00020101021226990014BR.GOV.BCB.PIX2577qrcodes-pix.gerencianet.com.br/bolix/v2/cobv/0000000000000000000000000000GERENCIANET SA6010OURO PRETO62070503***63047CB1",
                  "qrcode_image": "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmc vMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA0NSA0NSIgc2hhcGUtcmVuZGVyaW5nPSJjcmlzcEVkZ2VzIj48cGF0aCBmaWxsPSIjZmZmZmZmIiBkPSJNMCAwaDQ1djQ1SD..."
              },
              "link": "link_https_para_acesso_o_bolix",
              "billet_link": "link_https_para_acesso_o_bolix",
              "pdf": {
                  "charge": "link_https_do_pdf_da_cobranca"
              },
              "expire_at": "2023-12-15"
          }
      }
  }
}

Payment made as a Juridical person (PJ)

The customer associated with the transaction can be a Juridical person. In this case, it is necessary to inform the Company Name and CNPJ of the paying company in the attribute juridical_person.


List of all possible transaction statuses

All transactions have a status that represents the "situation" of that transaction. It is important to know the possible statuses of a transaction in the API to apply the appropriate treatments in your system.


Callbacks (notifications) from API transactions to your system

Notifications allow you to receive information when the status of a transaction changes, such as when a boleto is paid, for example.

Check here all the details on how to implement your notification URL.

Last updated on