Flow

The flow for the marketplace does not differ from the flow for regular companies.

The difference is that during the marketplace can send the seller_id field in the items. This information is optional, but important in certain cases, when you want to ensure that at capture time the total captured value for a seller is not greater than the amount sold through the sum of their items in the order.

Another piece of information that changes for the marketplace is the sending of the recipients field when creating the Payment. This field is used to inform the amounts and configurations of the merchants involved in the operation.

{
    "amount": 3000,
    "checkout_id": "2a21ce54-04c1-4ec3-81eb-6d46d5df8000",
    "currency": "BRL",
    "intent": "CAPTURE",
    "reference": "47EAEC72B7F74B08BB0B581ADA827000",
    "recipients": [
        {
            "provider_id": "example-marketplace",
            "name": "Marketplace de Teste 01",
            "role": "marketplace",
            "amount": 300,
            "charge_processing_fee": true,
            "chargeback_liable": true
        },
        {
            "provider_id": "example-seller",
            "name": "Lojista 10",
            "role": "seller",
            "amount": 2700,
            "charge_processing_fee": false,
            "chargeback_liable": false,
            "commission_amount": 300
        }
    ]
}

The example above shows the body of a request to the. In it, you can analyze the recipients field with the merchant information.

The marketplace "Test Marketplace 01" in this case did not make any sale, it is only receiving R$3.00 commission from the seller "Merchant 10". The seller sold R$30.00. They paid the R$3.00 commission and will receive R$27.00. In this case, the marketplace was configured to be responsible for Pagaleve fees, both for sales and refunds. So it will receive R$3.00 - Pagaleve fees configured in its registration.

Structure and Configuration

Pagaleve provides support for Settlement Split, which means we support Marketplace-type companies and Sellers. This behavior is explained on the page. There you can see that it is possible to configure which merchants will be responsible for paying the fees.

Important Information

Only the marketplace receives commissions from sellers
Sellers do not need to have a username and password. This is optional in their registration. Username and password are used both for API access and for Dashboard access.
The provider_id field for both the seller and the marketplace represents the store ID on the retailer side. They must be provided at the time of registration. It is through this that we link companies between Pagaleve and the retailer. This information will be the value of the seller_id field when creating the payment or creating the order items.

Marketplace configurations with Pagaleve

These are configurations made at the time of company registration with Pagaleve. These settings are internal and can be adjusted by requesting our support team.

Responsible for commission calculation

It is possible to define who will be responsible for commission calculation. There are two options:

Marketplace: Used when, during payment creation, the commission in cents is already sent by the marketplace. In this case, the commission percentage configured on the seller is ignored.

{
    "amount": 3000,
    "checkout_id": "2a21ce54-04c1-4ec3-81eb-6d46d5df8000",
    "currency": "BRL",
    "intent": "CAPTURE",
    "reference": "47EAEC72B7F74B08BB0B581ADA827000",
    "recipients": [
        {
            "provider_id": "example-marketplace",
            "name": "Marketplace de Teste 01",
            "role": "marketplace",
            "amount": 300,
            "charge_processing_fee": true,
            "chargeback_liable": true
        },
        {
            "provider_id": "example-seller",
            "name": "Lojista 10",
            "role": "seller",
            "amount": 2700,
            "charge_processing_fee": false,
            "chargeback_liable": false,
            "commission_amount": 300
        }
    ]
}

In the example above, the marketplace already sends the calculated commission.

Pagaleve: The request field when creating the payment can be sent as zero, since it will be ignored. We will use the commission configured in the Seller’s registration within Pagaleve. This means that if a seller is configured with a 20% commission rate, that rate will be applied to the seller’s total purchase amount.

Automatic pre-registration of sellers (VTEX only)

If the marketplace uses the VTEX platform, we perform an automatic pre-registration of merchants if the company is registered with a specific flag enabled. It is also necessary to inform the store ID in VTEX; internally this value will be stored in the provider_id field.

The pre-registration will use the basic company information available in VTEX. The store within Pagaleve will have a pending status. This means that it will not receive transfers until the registration is completed, providing banking information, address, etc.

Default commission

The marketplace is configured with a default commission, which applies to new merchants that are pre-registered when they do not already exist within Pagaleve.

Example: Suppose all existing merchants today are registered with a 20% commission, but the Marketplace is configured with a 10% default commission. When a sale occurs and the payment creation includes a provider_id that does not exist in Pagaleve’s database, we will pre-register the store with the default 10% commission. For this order, we will already apply the 10% commission.

Send recipients only at the time of payment capture

In Pagaleve it is possible to create an authorization-type payment. This means the merchant allocated the purchase amount to be received but needs to confirm, for example, that they have the items in stock. If they do, they can capture the amount; if not, they can release it.
In this scenario, the marketplace may only provide which sellers will receive the amounts at the time of payment capture. In other words, the payment creation request will be made as follows:

{
    "amount": 3000,
    "checkout_id": "2a21ce54-04c1-4ec3-81eb-6d46d5df8000",
    "currency": "BRL",
    "intent": "AUTH",
    "reference": "47EAEC72B7F74B08BB0B581ADA827000"
}

Then the payment will have the status AUTHORIZED. After confirming the items, the marketplace will capture the payment by informing the recipients, as in the example below:

{
    "amount": 3000,
    "checkout_id": "2a21ce54-04c1-4ec3-81eb-6d46d5df8000",
    "currency": "BRL",
    "intent": "CAPTURE",
    "reference": "47EAEC72B7F74B08BB0B581ADA827000",
    "recipients": [
        {
            "provider_id": "example-marketplace",
            "name": "Marketplace de Teste 01",
            "role": "marketplace",
            "amount": 300,
            "charge_processing_fee": true,
            "chargeback_liable": true
        },
        {
            "provider_id": "example-seller",
            "name": "Lojista 10",
            "role": "seller",
            "amount": 2700,
            "charge_processing_fee": false,
            "chargeback_liable": false,
            "commission_amount": 300
        }
    ]
}

All payments as authorization type (VTEX only)

It is possible to configure for VTEX platform clients that all captures be of type AUTH, so the marketplace can manually capture orders later.

Display page in Dashboard for authorized payments

When the marketplace creates authorization-type payments, we provide a page where they can view orders with authorized status and track whether the amounts have already been captured or not.

Merchant Registration

There are two options for seller registration by the marketplace in Pagaleve

Registration via Dashboard

The Pagaleve Dashboard allows managing merchants, registering them, viewing their status, commissions, etc. Remember that it is not necessary to provide a username and password at the time of registration.

Sending a CSV with all seller information

For this option, just contact our operations team. They will provide a sample spreadsheet that must be filled out with all seller information. We will import the information into our back office.

Automatic pre-registration at payment capture

When a sale occurs and the marketplace passes a seller provider_id that is not present in Pagaleve’s database, we will pre-register the seller and apply the default commission rate configured on the marketplace.

In this case, the seller will be registered with a pending status, which means they will not receive transfers and the amounts will accumulate until the registration is completed. By completing the full registration via the Dashboard or by sending a CSV to the operations team, the status automatically changes to complete and the transfer will be generated on D+2.

Note: The commission rate will only affect the calculation if the marketplace is configured for Pagaleve to calculate the commissions.

In the example below, a seller is registered with a provider_id "new-example-seller", which does not exist in Pagaleve’s database. It will be registered with pending status.

{
    "amount": 3000,
    "checkout_id": "2a21ce54-04c1-4ec3-81eb-6d46d5df8000",
    "currency": "BRL",
    "intent": "CAPTURE",
    "reference": "47EAEC72B7F74B08BB0B581ADA827000",
    "recipients": [
        {
            "provider_id": "example-marketplace",
            "name": "Marketplace de Teste 01",
            "role": "marketplace",
            "amount": 300,
            "charge_processing_fee": true,
            "chargeback_liable": true
        },
        {
            "provider_id": "new-example-seller",
            "name": "Lojista Novo",
            "role": "seller",
            "amount": 2700,
            "charge_processing_fee": false,
            "chargeback_liable": false,
            "commission_amount": 300
        }
    ]
}