Rinne API Documentation

Webhooks allow you to receive real-time notifications when events occur in your Rinne account. Instead of polling the API, Rinne sends HTTP POST requests to your server when important events happen.

Webhook events

Rinne sends webhooks for the following events:

Transaction events

transaction.created: New transaction created
transaction.status-changed: Transaction status updated

3D Secure events

three-d-secure-session.status-changed: 3DS session reached its outcome, AUTHENTICATED or FAILED

Dispute events

dispute.created: Dispute opened against a settled payment
dispute.funds-held: Disputed funds held in the merchant’s account, once or in growing increments
dispute.funds-released: Held funds returned to the merchant’s available balance
dispute.funds-returned: Disputed funds, in whole or in part, returned to the claimant
dispute.status-changed: Dispute status updated

Affiliation events

affiliation.created: New affiliation created
affiliation.status-changed: Affiliation status updated
affiliation.requirements-changed: What the merchant must supply for the affiliation changed
affiliation-bank-account.operational-status-changed: Affiliation bank account operational status updated

Onboarding events

onboarding-document.status-changed: Onboarding document status updated
biometric-verification.status-changed: Biometric verification reached its result, APPROVED, REPROVED or EXPIRED

Company events

company.created: New company created
company.status-changed: Company status updated

KYC events

kyc.completed: KYC check finished for a merchant company

Banking events

cashout.created: New cashout request created
cashout.status-changed: Cashout status updated
internal-transfer.created: New internal transfer created
internal-transfer.status-changed: Internal transfer status updated
judicial-blockage.created: Judicial block or release movement recorded

Pix key events

pix-key.created: New affiliation Pix key recorded
pix-key.status-changed: Pix key status updated

Ledger entry events

ledger-entry.settled: Ledger entry settled

Webhook payload structure

All webhooks follow a consistent structure:

{
  "id": "evt_123456789",
  "type": "transaction.status-changed",
  "version": 1,
  "timestamp": "2025-01-21T10:30:00.000Z",
  "source": "transaction-service",
  "company_id": "company-123",
  "correlation_id": "corr-987654321",
  "payload": {
    "transaction_id": "tx_123456789",
    "old_status": "WAITING_PAYMENT",
    "new_status": "APPROVED"
  }
}

Common fields

id: Unique event identifier
type: Event type (e.g., transaction.status-changed)
version: Event schema version
timestamp: When the event occurred (ISO 8601)
source: Service that generated the event
company_id: Company associated with the event
correlation_id: Shared by every event that one API request, one provider notification or one item of a scheduled job caused, so related events can be grouped. A scheduled job gives each item it processes its own value, so the events of one run do not share one. It is not unique per event: use id to identify and deduplicate an event.
payload: Event-specific data

Setting up webhooks

Contact Rinne support to configure your webhook endpoint URL. We’ll create a webhook configuration for your organization.

Webhook endpoint requirements

Your endpoint must:

Accept POST requests
Respond with 2xx status code within 5 seconds
Use HTTPS (required for production)
Handle duplicate events (idempotency)

Webhook security

Rinne uses Svix for webhook delivery, which provides:

Request signing for verification
Automatic retries with exponential backoff
Webhook dashboard for monitoring
Replay functionality for testing

Verifying webhook signatures

Verify that webhooks are from Rinne by checking the signature:

const svix = require('svix');

app.post('/webhooks/rinne', (req, res) => {
  const payload = req.body;
  const headers = req.headers;
  
  const wh = new svix.Webhook(WEBHOOK_SECRET);
  
  try {
    const verified = wh.verify(payload, headers);
    // Process the webhook
    res.status(200).send('OK');
  } catch (err) {
    res.status(400).send('Invalid signature');
  }
});

Handling webhook events

Transaction status changed

if (event.type === 'transaction.status-changed') {
  const { transaction_id, old_status, new_status, refund_id } = event.payload;
  
  // Check the transitions into APPROVED that need their own handling first
  if (old_status === 'PENDING_REFUND' && new_status === 'APPROVED') {
    // Refund failed - transaction returned to approved
    await notifyRefundFailed(transaction_id);
  } else if (old_status === 'EXPIRED' && new_status === 'APPROVED') {
    // Paid before the expiry, confirmed after it - fulfill, or refund if the order was paid again
    await fulfillOrRefundLateApproval(transaction_id);
  } else if (new_status === 'APPROVED') {
    // Payment approved - fulfill order
    await fulfillOrder(transaction_id);
  } else if (new_status === 'REFUSED') {
    // Payment declined - notify customer
    await notifyPaymentFailed(transaction_id);
  } else if (new_status === 'PENDING_REFUND') {
    // Refund initiated - notify customer
    await notifyRefundInitiated(transaction_id);
  } else if (new_status === 'REFUNDED' || new_status === 'PARTIALLY_REFUNDED') {
    // Refund completed - update order status
    await updateOrderRefundStatus(transaction_id, new_status);
  }
}

An EXPIRED → APPROVED event and the approval of a replacement charge for the same order belong to different transactions, so deduplicating by event id does not catch them. Check and update the order in one atomic step before you choose: fulfill an open order, and refund the late payment when the order is already paid; BOLEPIX transactions do not support refunds. See Payment confirmed after expiry, and Best practices for repeated deliveries.

Refund failure handling

When a refund fails, you’ll receive a transaction.status-changed webhook where:

old_status is PENDING_REFUND
new_status is APPROVED (if no other refunds exist) or remains PENDING_REFUND (if other refunds are still processing)

This allows you to handle refund failures appropriately in your system and notify customers when a refund could not be processed.

3D Secure session status changed

if (event.type === 'three-d-secure-session.status-changed') {
  const { three_d_secure_session_id, new_status, entity } = event.payload;

  if (new_status === 'AUTHENTICATED' && entity.authentication_flow !== 'attempt') {
    // The issuer authenticated the cardholder - to pay with the session, link it before entity.expires_at
    await handleThreeDSAuthenticated(three_d_secure_session_id, entity);
  } else if (new_status === 'AUTHENTICATED') {
    // Only proof of the attempt exists: the cardholder was not authenticated
    await handleThreeDSAttempt(three_d_secure_session_id, entity);
  } else if (new_status === 'FAILED') {
    // entity.failure_reason says why - create a new session to retry
    await handleThreeDSFailed(three_d_secure_session_id, entity.failure_reason);
  }
}

Rinne writes one event per session, when the session reaches its outcome, including sessions you link to transactions. Like any webhook, it can be delivered more than once: deduplicate by the event id (see Best practices). entity is the session as a read returns it, and its expires_at still bounds the session’s use in a payment. An event delivered late, after a retry to your endpoint or an incident on our side, can arrive with expires_at already past. Linking that session to a transaction is then rejected with 400, so create a new session instead. A session that already has its outcome when you create it sends no event, and one the cardholder leaves before the challenge starts may never send it. See Read a session from your backend for both cases.

Dispute created

if (event.type === 'dispute.created') {
  const { dispute_id, transaction_id, type, status, amount, entity } = event.payload;

  await recordDispute(dispute_id, transaction_id, type, amount, entity.deadline_at);

  if (status === 'CLOSED') {
    // Created from an already finished claim - no status-change event follows
    await resolveDispute(dispute_id, event.payload.outcome);
    await notifyDisputeClosure(dispute_id, event.payload.outcome);
  }
}

Dispute status changed

if (event.type === 'dispute.status-changed') {
  const { dispute_id, new_status, outcome } = event.payload;

  if (new_status === 'UNDER_REVIEW') {
    // The claim is being analyzed
    await markDisputeUnderReview(dispute_id);
  } else if (new_status === 'CLOSED') {
    // Terminal - outcome is always set here
    await resolveDispute(dispute_id, outcome);
    await notifyDisputeClosure(dispute_id, outcome);
  }
}

async function notifyDisputeClosure(dispute_id, outcome) {
  if (outcome === 'UPHELD') {
    // The claim succeeded and funds are returned
    await notifyDisputeLost(dispute_id);
  } else {
    // DISMISSED or WITHDRAWN - no financial movement
    await notifyDisputeClosedWithoutLoss(dispute_id, outcome);
  }
}

Disputes only move forward and never reopen, so old_status is always strictly earlier than new_status. Deliveries can repeat or arrive out of order, so make these handlers idempotent and apply an update only when it moves the dispute forward from the status you stored, ideally as a single conditional write. See Best practices. Group events belonging to one dispute by dispute_id: correlation_id groups the events that one request or notification caused, not the events of one dispute.

See Disputes for the full lifecycle, outcomes, and payload fields.

Affiliation created

if (event.type === 'affiliation.created') {
  const { affiliation_id, status, onboarding_url } = event.payload;

  if (status === 'WAITING_DOCUMENTS' && onboarding_url) {
    // Created waiting for documents - no status change follows, so send the link now
    await sendOnboardingLink(affiliation_id, onboarding_url);
  }
}

An affiliation created directly in WAITING_DOCUMENTS carries its onboarding_url only here and in the creation response; no affiliation.status-changed follows for that entry. When onboarding_url is null, the link arrives later on affiliation.status-changed, as below.

Affiliation status changed

if (event.type === 'affiliation.status-changed') {
  const { affiliation_id, new_status, onboarding_url, provider_status_message } = event.payload;
  
  if (new_status === 'ACTIVE') {
    // Affiliation activated - merchant can process transactions
    await enableMerchantPayments(affiliation_id);
  } else if (new_status === 'WAITING_DOCUMENTS') {
    // Something is pending - send the onboarding link to the merchant's contact
    await sendOnboardingLink(affiliation_id, onboarding_url);
  } else if (new_status === 'CANCELLED') {
    // Cancelled while waiting - terminal; create a new affiliation when the merchant is ready
    await markOnboardingCancelled(affiliation_id);
  } else if (new_status === 'BLOCKED' && provider_status_message) {
    // Affiliation blocked - log provider message for debugging
    await logAffiliationBlocked(affiliation_id, provider_status_message);
  } else if (new_status === 'CLOSED') {
    // Provider closed the account - terminal; a new affiliation is needed to onboard again
    await disableMerchantPayments(affiliation_id, provider_status_message);
  } else if (new_status === 'INVALID_SETTLEMENT_BANK_ACCOUNT') {
    // Settlement bank account rejected by provider — notify and prompt a replacement
    await notifyInvalidSettlementBank(affiliation_id, provider_status_message);
  }
}

The provider_status_message field contains additional context from the payment provider when available, including possible error messages.

Onboarding events

affiliation.requirements-changed, onboarding-document.status-changed and biometric-verification.status-changed follow a merchant through onboarding: a reviewed rejection or a provider’s request, a document accepted or refused, a biometric verification approved or reproved. Their payloads and handlers are in Statuses and events.

Affiliation bank account operational status changed

if (event.type === 'affiliation-bank-account.operational-status-changed') {
  const { bank_account_id, affiliation_id, old_status, new_status, entity } = event.payload;

  if (new_status === 'JUDICIAL_BLOCK') {
    // Account under court-ordered restriction — funds may be unavailable
    await notifyJudicialBlock(affiliation_id, bank_account_id, entity);
  } else if (new_status === 'REGULAR' && old_status === 'JUDICIAL_BLOCK') {
    // Judicial block lifted — account operates normally again
    await notifyJudicialBlockReleased(affiliation_id, bank_account_id, entity);
  }
}

The entity field is a full write-time snapshot of the affiliation bank account (including operational_status). You do not need a follow-up API call to inspect the account.

Cashout created

if (event.type === 'cashout.created') {
  const { cashout_id, amount, currency, status } = event.payload;
  
  // Cashout request created
  await logCashoutCreated(cashout_id, amount, currency);
}

Cashout status changed

if (event.type === 'cashout.status-changed') {
  const { cashout_id, old_status, new_status, error_message } = event.payload;
  
  if (new_status === 'COMPLETED') {
    // Cashout completed successfully
    await notifyCashoutCompleted(cashout_id);
  } else if (new_status === 'PARTIALLY_RETURNED') {
    // Part of the cashout was returned
    const cashout = await getCashoutDetails(cashout_id);
    await notifyPartialReturn(cashout_id, cashout.returned_amount);
  } else if (new_status === 'RETURNED') {
    // Full cashout amount was returned
    await notifyFullReturn(cashout_id);
  } else if (new_status === 'FAILED') {
    // Cashout failed - error_message contains details when available
    await notifyCashoutFailed(cashout_id, error_message);
  }
}

KYC completed

if (event.type === 'kyc.completed') {
  const { kyc_check_id, company_id, kyc_type, rule_executions } = event.payload;

  const issues = rule_executions.filter((rule) => rule.status === 'ISSUES_FOUND');
  const inconclusive = rule_executions.filter((rule) => rule.status === 'FAILED');

  if (issues.length > 0) {
    // Discrepancies found - review the merchant's data
    await flagMerchantForReview(company_id, kyc_check_id, issues.map(describeRuleResult));
  } else if (inconclusive.length === 0) {
    // All rules passed
    await markMerchantVerified(company_id, kyc_check_id);
  }

  // FAILED rules are inconclusive (data source could not evaluate them),
  // not a problem with the merchant
}

// Each entry carries the pair of fields its type defines
function describeRuleResult(rule) {
  const { rule_name, type, description } = rule;

  if (type === 'COMPARISON') {
    // The data source reported `expected`; the merchant declared `received`
    return { rule_name, type, source: rule.expected, reference: rule.received, description };
  }
  if (type === 'CHECK') {
    // The data source reported `found`; the rule requires `required` to pass
    return { rule_name, type, source: rule.found, reference: rule.required, description };
  }
  return { rule_name, type, description };
}

A COMPARISON rule carries expected and received, and a CHECK rule carries found and required; an entry never carries both pairs. Read the pair from type rather than from rule_name. The source field (expected or found) is absent only when the data source was unreachable, and such a rule is always FAILED, so every ISSUES_FOUND entry above has both fields of its pair. See KYC Verification for rule names, their types, statuses, and the full payload.

Internal transfer status changed

if (event.type === 'internal-transfer.status-changed') {
  const { internal_transfer_id, old_status, new_status, error_message } = event.payload;
  
  if (new_status === 'COMPLETED') {
    // Transfer completed successfully
    await notifyTransferCompleted(internal_transfer_id);
  } else if (new_status === 'FAILED') {
    // Transfer failed - error_message contains details when available
    await notifyTransferFailed(internal_transfer_id, error_message);
  }
}

Judicial blockage created

if (event.type === 'judicial-blockage.created') {
  const {
    judicial_blockage_id,
    affiliation_bank_account_id,
    affiliation_id,
    type,
    entity,
  } = event.payload;

  if (type === 'BLOCK') {
    // Funds frozen by court order — amount is in entity.amount (cents)
    await notifyJudicialMovementBlocked(affiliation_id, affiliation_bank_account_id, entity);
  } else if (type === 'RELEASE') {
    // Previously blocked funds were released
    await notifyJudicialMovementReleased(affiliation_id, affiliation_bank_account_id, entity);
  }
}

The entity field is a full write-time snapshot of the judicial blockage movement. Use it for amount, process details, and occurred_at without listing movements from the API. Account-level restriction changes arrive separately as affiliation-bank-account.operational-status-changed.

Webhook dashboard

Access your webhook dashboard to:

View webhook delivery history
Replay failed webhooks
Test webhook endpoints
Monitor delivery success rates

Get your dashboard URL:

curl https://api-sandbox.rinne.com.br/core/v1/webhooks/dashboard \
  -H "x-api-key: YOUR_API_KEY"

Retry behavior

If your endpoint returns an error or times out, Rinne automatically retries:

Immediate retry
After 5 seconds
After 5 minutes
After 30 minutes
After 2 hours
After 5 hours
After 10 hours
After 24 hours

After all retries fail, the webhook is marked as failed in your dashboard.

Best practices

Respond quickly

Return a 200 status code immediately, then process the webhook asynchronously. Don’t perform long-running operations in the webhook handler.

Handle duplicates

Use the event id to track processed events and ignore duplicates. Webhooks may be delivered more than once.

Verify signatures

Always verify webhook signatures to ensure requests are from Rinne.

Use correlation IDs

Use correlation_id to group the events that one API request, one provider notification or one item of a scheduled job caused, across event types. Never deduplicate by it: several events share it, so use the event id.

Monitor webhook health

Regularly check your webhook dashboard for failed deliveries and fix issues promptly.

Testing webhooks

Local testing with ngrok

Use ngrok to expose your local server for webhook testing:

ngrok http 3000

Provide the ngrok URL to Rinne support for webhook configuration.

Webhook replay

Use the webhook dashboard to replay events to your endpoint for testing.

Example webhook handler

const express = require('express');
const { Webhook } = require('svix');

const app = express();
app.use(express.json());

app.post('/webhooks/rinne', async (req, res) => {
  const payload = JSON.stringify(req.body);
  const headers = req.headers;
  
  const wh = new Webhook(process.env.WEBHOOK_SECRET);
  
  let event;
  try {
    event = wh.verify(payload, headers);
  } catch (err) {
    return res.status(400).send('Invalid signature');
  }
  
  // Respond immediately
  res.status(200).send('OK');
  
  // Process asynchronously
  processWebhook(event).catch(console.error);
});

async function processWebhook(event) {
  switch (event.type) {
    case 'transaction.status-changed':
      await handleTransactionStatusChanged(event.payload);
      break;
    case 'affiliation.created':
      await handleAffiliationCreated(event.payload);
      break;
    case 'affiliation.status-changed':
      await handleAffiliationStatusChanged(event.payload);
      break;
    case 'affiliation-bank-account.operational-status-changed':
      await handleAffiliationBankAccountOperationalStatusChanged(event.payload);
      break;
    case 'dispute.created':
      await handleDisputeCreated(event.payload);
      break;
    case 'dispute.status-changed':
      await handleDisputeStatusChanged(event.payload);
      break;
    case 'judicial-blockage.created':
      await handleJudicialBlockageCreated(event.payload);
      break;
    // Handle other event types
  }
}

app.listen(3000);

​Webhook events

​Transaction events

​3D Secure events

​Dispute events

​Affiliation events

​Onboarding events

​Company events

​KYC events

​Banking events

​Pix key events

​Ledger entry events

​Webhook payload structure

​Common fields

​Setting up webhooks

​Webhook endpoint requirements

​Webhook security

​Verifying webhook signatures

​Handling webhook events

​Transaction status changed

​Refund failure handling

​3D Secure session status changed

​Dispute created

​Dispute status changed

​Affiliation created

​Affiliation status changed

​Onboarding events

​Affiliation bank account operational status changed

​Cashout created

​Cashout status changed

​KYC completed

​Internal transfer status changed

​Judicial blockage created

​Webhook dashboard

​Retry behavior

​Best practices

​Testing webhooks

​Local testing with ngrok

​Webhook replay

​Example webhook handler

​Next steps

API Reference

Error Handling

Webhook events

Transaction events

3D Secure events

Dispute events

Affiliation events

Onboarding events

Company events

KYC events

Banking events

Pix key events

Ledger entry events

Webhook payload structure

Common fields

Setting up webhooks

Webhook endpoint requirements

Webhook security

Verifying webhook signatures

Handling webhook events

Transaction status changed

Refund failure handling

3D Secure session status changed

Dispute created

Dispute status changed

Affiliation created

Affiliation status changed

Onboarding events

Affiliation bank account operational status changed

Cashout created

Cashout status changed

KYC completed

Internal transfer status changed

Judicial blockage created

Webhook dashboard

Retry behavior

Best practices

Testing webhooks

Local testing with ngrok

Webhook replay

Example webhook handler

Next steps