Rinne API Documentation

Onboarding reports every step by webhook, so your system can follow a merchant from the affiliation’s creation to its approval without polling. This page covers the affiliation statuses as onboarding uses them and the events each building block sends.

Affiliation statuses

The status set is the affiliation set you already use. WAITING_DOCUMENTS covers the collection Rinne does before submitting and a provider’s request for more on an open affiliation, and CANCELLED ends an attempt that waited too long or that you cancelled. Every transition between them is drawn in the affiliation lifecycle. What each one means for onboarding, and what you do:

Status	Meaning	What you do
`WAITING_DOCUMENTS`	At least one requirement is pending, before the first submission or after a provider that takes supplements asked for more. `onboarding_url` collects them	Supply the pending items through the API, or send the link
`PENDING`	Every requirement is satisfied and Rinne is submitting, or retrying after a provider outage, or holding the attempt until a previous one for the same CNPJ or CPF finishes at the provider or until Rinne’s review of a previous rejection lands	Wait
`PENDING_APPROVAL`	Submitted; the provider is checking the merchant’s data	Wait
`PROCESSING_DOCUMENTS`	The provider is analyzing the documents and the biometric verification	Wait
`PROCESSING`	The provider is processing the affiliation through its own steps; a supplement lands back here	Wait
`ACTIVE`	Approved. `onboarding_url` is `null` and the documents sent are `VALIDATED`	Transact
`REJECTED`	The provider refused the attempt. `rejection_reasons` follow once Rinne reviews it	Supply what the review asks for and create a new affiliation, unless the review’s `action` is `NONE`: the provider refuses a new attempt too
`FAILED`	A technical failure while creating or submitting	Create the affiliation again; documents and verifications are untouched
`CANCELLED`	Cancelled while waiting for documents, by you or by the 30-day deadline	Create a new affiliation when the merchant is ready

INVALID_SETTLEMENT_BANK_ACCOUNT, BLOCKED and CLOSED work as described in Affiliations.

CANCELLED

An affiliation becomes CANCELLED in two ways, recorded in cancellation_reason:

`cancellation_reason`	When
`REQUESTED`	You cancelled it while it was `WAITING_DOCUMENTS`
`EXPIRED`	It waited 30 days in `WAITING_DOCUMENTS` before its first submission

CANCELLED is terminal: nothing moves the affiliation out of it. Its link is abandoned, so nothing completed through it afterwards applies to the cancelled affiliation, while documents, verifications and answers stay with the merchant and satisfy its next affiliation. When an attempt the provider had already received is cancelled, the provider’s process can stay open on its side, and its later result is ignored. At CELCOIN, a new affiliation for the same CNPJ or CPF is created normally and collects what is pending in WAITING_DOCUMENTS; once nothing is pending, it waits as PENDING until that process ends, at most 33 days after the cancelled attempt was submitted. At CAPPTA nothing is held: the new affiliation is submitted as soon as its requirements are satisfied.

Cancel an affiliation

Cancel an affiliation that is waiting for documents to start over, for example after correcting the merchant’s data:

cURL

curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/a7089150-0d61-498f-b7ca-4767e4e4d6a4/affiliations/2352ebe5-97c2-4625-8535-cc21b732787a/cancel \
  -H "x-api-key: YOUR_API_KEY"

The call takes no body and answers 200 with the affiliation CANCELLED, cancellation_reason REQUESTED and onboarding_url null, and affiliation.status-changed fires. Any status other than WAITING_DOCUMENTS answers 409, whose message names the status found: once submitted, the provider decides. A status change racing the cancel answers 409 too, and when the affiliation is back in WAITING_DOCUMENTS by then, the message asks you to retry. Organizations onboarding themselves call POST /v1/affiliations/{id}/cancel. Both routes require the affiliation.edit permission (merchant.affiliation.edit on the merchant route).

Events

Every event uses the standard webhook envelope and is delivered at least once, so deduplicate by the envelope id. Events about a merchant reach the merchant’s own endpoint, when it has one, and its organization’s.

Event	When
`affiliation.created`	An affiliation was created; carries `onboarding_url` when it was created `WAITING_DOCUMENTS`
`affiliation.status-changed`	The affiliation changed status; carries `onboarding_url` when `new_status` is `WAITING_DOCUMENTS`
`affiliation.requirements-changed`	What the merchant must supply for the affiliation changed
`onboarding-document.status-changed`	A document changed status
`biometric-verification.status-changed`	A biometric verification left `PENDING`

The handlers below run inside the verified handler of the webhooks guide, after the signature check.

Affiliation requirements changed

Fires when the merchant’s requirements for the affiliation’s provider change while the affiliation is not ACTIVE: Rinne reviewed a rejection or a provider’s request, Rinne staff added a requirement, or an approved biometric verification has to be redone. When the change also sends the affiliation back to WAITING_DOCUMENTS, affiliation.status-changed fires as well.

Event (entity trimmed)

{
  "id": "38564e6c-7d12-45e1-8998-3b5b472a6928",
  "type": "affiliation.requirements-changed",
  "version": 1,
  "timestamp": "2026-10-03T16:40:00.000Z",
  "source": "affiliation-service",
  "company_id": "a7089150-0d61-498f-b7ca-4767e4e4d6a4",
  "correlation_id": "38564e6c-7d12-45e1-8998-3b5b472a6928",
  "payload": {
    "affiliation_id": "2352ebe5-97c2-4625-8535-cc21b732787a",
    "company_id": "a7089150-0d61-498f-b7ca-4767e4e4d6a4",
    "changed_requirement_ids": ["9d6c5c69-1c92-4d25-93cf-fc0a63f1251c"],
    "occurred_at": "2026-10-03T16:40:00.000Z",
    "entity": {
      "id": "2352ebe5-97c2-4625-8535-cc21b732787a",
      "provider": "CELCOIN",
      "status": "REJECTED",
      "rejection_reviewed_at": "2026-10-03T16:40:00.000Z",
      "rejection_reasons": [
        {
          "code": "DOCUMENT_UNREADABLE",
          "message": "The contact's identity document could not be read. Send a new, sharp photo of the front and the back.",
          "action": "RESUBMIT_DOCUMENT",
          "requirement_id": null,
          "onboarding_document_id": "161e2065-1179-4484-9ea3-faf62199595e"
        }
      ]
    }
  }
}

changed_requirement_ids lists the requirements whose evidence was refused, the ones the review added, or the biometric one sent back to PENDING. It is empty when the review recorded reasons that reset nothing (FIX_COMPANY_DATA, NONE). entity is the affiliation as GET /v1/affiliations/{id} returns it, without company_snapshot.

if (event.type === 'affiliation.requirements-changed') {
  const { affiliation_id, company_id, entity } = event.payload;

  if (entity.status === 'REJECTED' && entity.rejection_reviewed_at) {
    // The rejection was reviewed - show the merchant what to fix
    await showRejectionReasons(affiliation_id, entity.rejection_reasons);
  }
  // Refresh the checklist you show the merchant
  await refreshRequirements(company_id, entity.provider);
}

Onboarding document status changed

Fires on every document status change after creation: an upload completed (NOT_VALIDATED), an affiliation that sent it was approved (VALIDATED), a provider refused it (REJECTED, with rejections), or a newer upload replaced it (SUPERSEDED). A document shared from another organization arrives VALIDATED with old_status null.

Event (entity trimmed)

{
  "id": "7dc6060d-f12f-4f4d-97d1-291e993f77da",
  "type": "onboarding-document.status-changed",
  "version": 1,
  "timestamp": "2026-10-02T12:01:30.000Z",
  "source": "onboarding-service",
  "company_id": "a7089150-0d61-498f-b7ca-4767e4e4d6a4",
  "correlation_id": "d5defce5-d859-4a58-a504-3ad470b6de08",
  "payload": {
    "onboarding_document_id": "d5defce5-d859-4a58-a504-3ad470b6de08",
    "company_id": "a7089150-0d61-498f-b7ca-4767e4e4d6a4",
    "old_status": "PENDING_UPLOAD",
    "new_status": "NOT_VALIDATED",
    "occurred_at": "2026-10-02T12:01:30.000Z",
    "entity": {
      "id": "d5defce5-d859-4a58-a504-3ad470b6de08",
      "type": "ARTICLES_OF_INCORPORATION",
      "subject_document_number": "12345678000195",
      "status": "NOT_VALIDATED",
      "source": "UPLOAD",
      "file_size_bytes": 482133
    }
  }
}

if (event.type === 'onboarding-document.status-changed') {
  const { onboarding_document_id, new_status, entity } = event.payload;

  await recordDocumentStatus(onboarding_document_id, new_status);

  if (new_status === 'REJECTED') {
    // A provider refused it - ask the merchant for a new one of the same type
    await requestNewDocument(entity.subject_document_number, entity.type, entity.rejections);
  }
}

Biometric verification status changed

Fires when a verification leaves PENDING: APPROVED, REPROVED with rejection_reason, or EXPIRED. It reaches the merchant the verification was created for and, when that merchant is not your organization itself, your organization too.

Event (entity trimmed)

{
  "id": "030c761f-f1d9-4e32-985f-1069fff71744",
  "type": "biometric-verification.status-changed",
  "version": 1,
  "timestamp": "2026-10-02T12:09:12.000Z",
  "source": "onboarding-service",
  "company_id": "a7089150-0d61-498f-b7ca-4767e4e4d6a4",
  "correlation_id": "336b4995-d8ed-4837-97b2-b94990b30240",
  "payload": {
    "biometric_verification_id": "336b4995-d8ed-4837-97b2-b94990b30240",
    "company_id": "a7089150-0d61-498f-b7ca-4767e4e4d6a4",
    "old_status": "PENDING",
    "new_status": "APPROVED",
    "occurred_at": "2026-10-02T12:09:12.000Z",
    "entity": {
      "id": "336b4995-d8ed-4837-97b2-b94990b30240",
      "provider": "CELCOIN",
      "subject_document_number": "52998224806",
      "status": "APPROVED",
      "selfie_onboarding_document_id": "9f9f4193-9291-4b12-a7da-763e30880811",
      "approved_at": "2026-10-02T12:09:12.000Z",
      "rejection_reason": null
    }
  }
}

if (event.type === 'biometric-verification.status-changed') {
  const { biometric_verification_id, new_status, entity } = event.payload;

  if (new_status === 'APPROVED') {
    // Satisfies the person's BIOMETRIC_VERIFICATION requirement in every merchant of your organization
    await markPersonVerified(entity.subject_document_number, biometric_verification_id);
  } else {
    // REPROVED (entity.rejection_reason) or EXPIRED - start a new verification
    await askForNewVerification(entity.subject_document_number, entity.rejection_reason);
  }
}

Overview

Choose your integration

Building blocks

Lifecycle

Statuses and events

Affiliation statuses

CANCELLED

Cancel an affiliation

Events

Affiliation requirements changed

Onboarding document status changed

Biometric verification status changed

Next steps

Webhooks guide

Test in the sandbox

​Affiliation statuses

​CANCELLED

​Cancel an affiliation

​Events

​Affiliation requirements changed

​Onboarding document status changed

​Biometric verification status changed

​Next steps

Webhooks guide

Test in the sandbox

Affiliation statuses

CANCELLED

Cancel an affiliation

Events

Affiliation requirements changed

Onboarding document status changed

Biometric verification status changed

Next steps