Webhooks Notifications#

Two webhook endpoints#

Tuna uses two independent webhook configurations in Console Settings > Webhook:

Payment webhook: receives payment notifications only. In Console, you can choose the payment operation methods that trigger notifications: Init, Capture, Cancel, and Chargeback.
Merchant webhook: receives merchant notifications, including merchant service registration events and split payout events. This is a different endpoint from the payment webhook.

The payment webhook and merchant webhook can have different URLs and authentication settings. Configure each destination independently in Console. The payment webhook uses the payment notification schema, while the merchant webhook uses the merchant notification schema for both registration and payout events.

Each endpoint should accept JSON, authenticate the request when authentication is configured, process its notification schema, and return a successful HTTP status after the notification has been handled. Tuna considers HTTP 200, 201, 202, 204, or 208 successful delivery responses.

Payment Notifications#

To receive a payment status notification, configure the payment webhook in Console Settings > Webhook. Payment notifications are sent only for the operation methods selected there:

Method	Notification trigger
`Init`	Payment initialization event.
`Capture`	Payment capture event.
`Cancel`	Payment cancellation event.
`Chargeback`	Payment chargeback event.

See below the flow of a notification:

And here is an example of a notification payload:

{
    "id": 104574372,
    "paymentKey": "134D946015A08C9",
    "partnerUniqueId": "668ecbaff060e8001162eef6",
    "statusId": "2",
    "amount": 19.50,
    "operationId": "O005B134D946015E4CF0",
    "methods": [
        {
            "methodType": "D",
            "status": "2",
            "methodId": 0,
            "operationId": "O005B134D946015E4CF000",
            "additionalInfo": {
                "EndToEndId": "E60701190202407101759DY5BQ4HFISM"
            },
            "operationAmount": 19.50
        }
    ],
    "items": [
        {
            "paymentItemId": 0,
            "productID": 1,
            "productDescription": "841",
            "amount": 19.500000,
            "quantity": 1,
            "categoryID": 1,
            "categoryName": "Pedido",
            "data": {
                "ProductID": 1,
                "CategoryID": 1,
                "CategoryName": "Pedido",
                "DetailUniqueID": "668ecbaff060e8001162eef6",
                "ExternalMerchantId": "65677b704f42a50019188852",
                "ProductDescription": "841"
            }
        }
    ]
}

Parameters description:

Property	Description
ID	The ID of the notification
paymentKey	The unique transaction ID generated by Tuna
partnerUniqueId	The ID used by the partner to identify the transaction
statusId	The new status of the transaction
amount	The full amount of the transaction
operationId	The ID of the operation (informed, e.g., in a cancellation request)
methods	The list of payment methods used for this transaction
items	The list of payment items

See more details about the properties in the response object of the endpoint api/Payment/Init/.

Merchant Notifications#

Merchant notifications are sent for merchant service registration events. They are delivered to the merchant webhook, a separate URL from the payment webhook. For a split integration, this includes notifications for the configured Split Providers. The Split Integration guide contains provider and registration examples.

Merchant registration payload#

{
    "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",
    "minDelayDays": 2,
    "merchantStatusId": "1",
    "kycLevel": "1"
}

Property	Type	Description
`merchantId`	integer	Tuna's internal merchant identifier.
`code`	integer	`1` for a successful registration notification; `-1` for a rejected, failed, or blocked registration notification.
`message.source`	integer	Source of the message. Gateway-generated merchant registration notifications use `3`.
`message.code`	string	Registration result code. See the table below.
`message.message`	string	Human-readable result or gateway error message.
`message.info`	string, optional	Additional message information when supplied by the service.
`externalId`	string	Merchant identifier supplied during registration.
`serviceId`	integer	Tuna service identifier, such as `41`, `63`, `69`, `71`, `86`, `88`, `93`, or `101` for the Split services currently documented.
`serviceName`	string	Name of the registered service.
`conditionId`	string	Payment condition assigned to the merchant service.
`minDelayDays`	integer, optional	Minimum delay in days configured for the merchant service.
`merchantStatusId`	string, optional	Merchant status after the registration event.
`kycLevel`	string, optional	KYC result or current KYC state.

The registration message codes currently produced by the merchant notification flow are:

`message.code`	`code`	Meaning
`SRVMerchantRegisterOk`	`1`	Service registration completed successfully.
`SRVMerchantRegisterRejected`	`-1`	The gateway rejected the registration.
`SRVMerchantRegisterError`	`-1`	Registration failed or returned an error.
`SRVMerchantRegisterBlocked`	`-1`	Registration was blocked because the merchant requires additional analysis or is not allowed to register.

The merchantStatusId values used by the registration responses are:

Value	Meaning
`0`	In analysis.
`1`	Active.
`2`	Inactive.
`3`	Suspended.
`P`	Pre-registration.

The kycLevel values are:

Value	Meaning
`0` or omitted	KYC is still under analysis.
`1`	Approved.
`A`	Approved with alert.
`P`	Approved and classified as a politically exposed person (PEP).
`R`	Rejected.

Merchant registration is asynchronous and can take up to 48 hours to be validated. Treat the webhook as the source of the registration result rather than assuming that a successful registration request means that every Split Provider is already active.

Payout Notifications#

Payout notifications use the same merchant notification endpoint and the same top-level envelope as merchant registration notifications. They are generated when a split payout reaches its final successful state and are intended to inform the merchant that the payout was completed.

Successful payout payload#

{
    "merchantId": 190329,
    "code": 1,
    "message": {
        "source": 1,
        "code": "SRVMerchantPaymentOk",
        "message": "Payment OK"
    },
    "externalId": "68d16d9c879c8c630428a0c1",
    "serviceId": 0,
    "serviceName": "SYSTEM"
}

Property	Value for a payout notification	Description
`merchantId`	integer	Tuna's internal merchant identifier receiving the payout.
`code`	`1`	The payout notification is successful.
`message.source`	`1`	System-generated payout status message.
`message.code`	`SRVMerchantPaymentOk`	The payout was completed successfully.
`message.message`	`Payment OK`	Success message.
`externalId`	string	The merchant's external identifier.
`serviceId`	`0`	System service identifier in the payout notification payload. This is not the payout ID.
`serviceName`	`SYSTEM`	Identifies this as a system-generated payout event.

Payout error payload#

{
    "merchantId": 190329,
    "code": -1,
    "message": {
        "source": 1,
        "code": "SRVMerchantPaymenError",
        "message": "Pagamento não realizado: 910 - Documento favorecido invalido"
    },
    "externalId": "68d16d9c879c8c630428a0c1",
    "serviceId": 0,
    "serviceName": "SYSTEM"
}

For a payout error, code is -1 and message.code is SRVMerchantPaymenError. The message can contain the gateway or processing reason, such as Pagamento não realizado: 910 - Documento favorecido invalido. The spelling Paymen in SRVMerchantPaymenError is part of the existing notification contract.

The payout ID, payout date, amount, payout type, bank account, PIX key, and gateway response are not exposed in this webhook payload. The serviceId: 0 field is also not a payout identifier. If your reconciliation process needs those values, use the payout or settlement data available through the relevant merchant or split APIs and treat this notification as a status signal.

Handling payout notifications#

Verify the configured webhook authentication.
Check message.code === "SRVMerchantPaymentOk" and code === 1.
Associate the event with your merchant using merchantId or externalId.
Make processing idempotent. A notification has a delivery retry lifecycle, so receiving the same business event more than once must not create a duplicate payout in your system.
Return a successful HTTP status after storing or processing the event.

Delivery and authentication#

Tuna can send payment, merchant, and payout notifications over HTTP. The Console configuration supports an optional authorization value for each webhook. Depending on the configured mode, Tuna sends it either as a Bearer token in the Authorization header or as the value of a custom header. Keep both endpoints HTTPS, validate the appropriate header before processing the body, and avoid logging credentials or complete customer data.