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:

Create an account at Tuna
Define your Split Payment Methods
Configure your Payment Plans
Merchant Registration Process
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.

Definition

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 Payment Methods#

We can perform split operations with the payment methods shown in the table below:

Split Provider	Payment Methods
Split Provider	Card	PIX	Boleto	Nupay
Tuna	x	x	x	x

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, and all parameters must be defined in each payment plan:

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.

Support

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#

Resources#

official documentation: api/Merchant/Register
list of banks: banks.json
list of merchant category codes: mccCodes.json
list of occupations: occupations.json
list with all merchant registration error codes: srvTunaCodes.json

API Requests#

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

Company (PJ)
Person (PF)

curl -X 'POST' \
  'https://sandbox.tuna-demo.uy/api/Merchant/Register' \
  -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": "www.synapcom.com.br",
    "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": "natalia.cheapetta@synapcom.com.br",
      "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:

Connection Name	Connection Ids
Tuna Split para PIX	69, 71, 86, 88, 93, 101
Tuna Split para Cartão	41, 63

Also, you will receive notifications for the possible status:

Status	Code	Description
Success	SRVMerchantRegisterOk	Merchant registration successful
Error	SRVMerchantRegisterError	General registration error
Rejected	SRVMerchantRegisterRejected	Registration was rejected by gateway
Blocked	SRVMerchantRegisterBlocked	Registration blocked (KYC Level 2)

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.

Payload Field Descriptions#

Field	Type	Description
merchantId	integer	The merchant's unique identifier in Tuna system
code	integer	Response code (1 for success)
message	object	Contains detailed message information about the registration status
message.source	integer	Source identifier for the message
message.code	string	Status code (e.g., "SRVMerchantRegisterOk", "SRVMerchantRegisterError")
message.message	string	Human-readable status message
externalId	string	External identifier provided during registration
serviceId	integer	Internal service identifier
serviceName	string	Name of the split service (e.g., "Tuna Split para PIX V4")
conditionId	string	Payment condition set for this merchant
merchantStatusId	string	Current status of the merchant (see table below)
kycLevel	string	KYC (Know Your Customer) level (see descriptions below)

Merchant Status Values#

merchantStatusId	Description
0	InAnalysis - Merchant registration is under review
1	Active - Merchant is approved and can transact
2	Inactive - Merchant account is temporarily disabled
3	Suspended - Merchant account is suspended
P	PreRegister - Merchant is in pre-registration status

KYC Level Descriptions#

KYC Level R (Rejected): The merchant was not approved in the KYC process. This indicates serious problems, registration inconsistencies, invalid legal documents, or high risks that prevent operation through Tuna. In this status, the merchant cannot transact in any modality.
KYC Level 1 (Approved): The merchant has fully passed the KYC process, provided adequate information, and shows no signs of relevant risk. This status ensures the merchant is cleared to transact normally in all modalities.
KYC Level A (Approved with Alert): The merchant is under alert status. While there are no serious problems sufficient for rejection, there is also not the same reliability as a Level 1 merchant. This level is assigned when there is insufficient information or minor risk indicators. Merchants at this level transact normally but undergo re-analysis at shorter intervals with reinforced monitoring.
KYC Level P (Approved – PEP): The merchant is classified as a Politically Exposed Person (PEP). Although approved to transact, due to regulatory requirements, they must remain under continuous and reinforced monitoring, with mandatory periodic reviews and additional anti-money laundering and counter-terrorism financing (AML/CFT) controls.
KYC Level 0 / Null (Under Analysis): The merchant's KYC process has not yet been completed. While analysis is ongoing, the merchant can transact only via Pix in a limited manner. After completion, the status will be updated to one of the definitive levels (R, 1, A, or P).

{
  "merchantId": 190329,
  "code": 1,
  "message": {
    "source": 3,
    "code": "SRVMerchantRegisterOk",
    "message": "Service registration done"
  },
  "externalId": "68d16d9c879c8c630428a0c1",
  "serviceId": 71,
  "serviceName": "Tuna Split para PIX V4",
  "conditionId": "5149",
  "merchantStatusId": "1",
  "kycLevel": "1"
}

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:

Payment Items
Init Request

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