Skip to main content

Split Integration#

If you are interested in the registration process with our API, go to session API Registration.

There are five main steps to set up:

  1. Create an account at Tuna
  2. Define your Split Provider
  3. Configure your Payment Plans
  4. Merchant Registration Process
  5. Split Payment Request

each step will be described in the following.

Additionally, you can add customized Anti-frauds to your payment flow. After these steps, your registered merchant can start paying with Tuna within your Split Integration.


Merchant is a store in a marketplace.

You can checkout more methods related with Merchants, such as Transactions and Statement Reports, at our Merchant API official documentation.


Create an account at Tuna#

You can start your registration at Tuna here.


Define your Split Provider#

We can perform split operations with the providers shown in the table below, where the payment methods are given accordingly.

Split ProviderPayment Methods

Configure your Payment Plans#

You must define at least one payment plan to provide for your merchants. The following parameters are available in a payment plan definition:

  • frequency: can be daily, weekly, or monthly. It refers to the frequency where the available amounts will be updated;
  • days: the number of days when the money will be available. The counting of days starts after the payment has been captured;
  • fee: the tax you will offer to your merchants can be a fixed amount or a percentage of the transaction. You can set fees for different payment methods and/or card brands.

Our commercial team will help with the configuration of your payment plans.


Merchant Registration Process#

The registration process can be done:

  • programmatically with the api/Merchant, calling the endpoint Register
  • manually in the Merchant Portal at your Console - you must ask our commercial team to enable it
  • customized with our Merchant Module solution, a small website app customized with your branding. Please, ask our commercial team how this solution can be made available for you.

The registration of a merchant can take up to 48 hours to be validated.

API Registration#


API Requests#

The minimum payloads for merchant registration are given for the company (PJ) and person (PF) usecases:

curl -X 'POST' \
'' \
-H 'accept: application/json' \
-H 'x-tuna-account: demo' \
-H 'x-tuna-apptoken: a3823a59-66bb-49e2-95eb-b47c447ec7a7' \
-H 'Content-Type: application/json' \
-d '{
"externalId": "##004",
"document": "90.920.135/0001-68",
"documentType": "CNPJ",
"condition": "1",
"acceptedContract": true,
"websiteUrl": "",
"registrationDate": "2022-02-15",
"stateFiscalDocument": "ISENTO",
"mccCode": "5812",
"name": "Synacomp Corp.",
"fantasyName": "Synacomp",
"pixKeyType": "2",
"pixKey": "90.920.135/0001-68",
"contact": {
"name": "Natalia Cheapetta",
"email": "",
"cellPhone": "(11) 98071-9391"
"bankAccounts": [
"externalId": "1",
"document": "90.920.135/0001-68",
"documentType": "CNPJ",
"accountType": "C",
"bankCode": "001",
"bankName": "Banco Do Brasil S.A (BB)",
"agency": "2946",
"number": "0733-7"
"address": {
"street": "Rua João Longo",
"number": "1004",
"neighborhood": "Jandira",
"complement": "",
"city": "São Paulo",
"state": "SP",
"postalCode": "06608-420"

If you want to know more or require more fields in the registration process, you can check out the complete documentation for the api/Merchant/Register endpoint.

Webhook Notification#

The notifications will be send for all Split Provider registred in your account, even if the merchant ask to use just some of them. Each provider is identified by:

Service NameService Id
Tuna Split para PIX40
Tuna Split para Cartão41

Also, you will receive notifications for the possible status:


The registration of a merchant can take up to 48 hours to be validated.

The notification payload is exemplarily shown for success and error cases. Please note that the message property in the message object may contain a generic message or further details about the errors that need to be fixed.

"merchantId": 2,
"code": 1,
"message": {
"source": 3,
"code": "SRVMerchantRegisterOk",
"message": "Service registration done"
"externalId": "36189",
"serviceId": 40,
"serviceName": "Tuna Split para PIX"

Split Payment Request#

First, check out the guide Payment Integration for a step-by-step explanation of how to start receiving payments with Tuna.

Add the split object for each item in your paymentItems object during the Init request for the Payment API. The split object in its simplest and usual form only provides the merchantId information:

"split": {
"merchantId": "##001"

You can set additional properties only if you need to override the default configurations.

Here it is an exemplarily of a paymentItems object. There is also an exemplarily Init request:

"paymentItems": {
"items": [
"amount": 20,
"detailUniqueId": "A01",
"productDescription": "Test product",
"itemQuantity": 1,
"split": {
"merchantId": "##001"