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 Id
Tuna Split para PIX	40
Tuna Split para Cartão	41
GetNetSplit	36

Also, you will receive notifications for the possible status:

Status	Code
Success	SRVMerchantRegisterOk
Error	SRVMerchantRegisterError

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.

Tuna PIX
Error

{
  "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:

Payment Items
Init Request

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