> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rinne.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# When the provider asks for more

> How Rinne turns a provider's rejection or request for more into structured reasons and requirements, and how the next attempt asks only for what the provider refused or added.

A provider can answer with something a person has to read: a rejection, or a request for more documents or information on an affiliation it is still analyzing. Rinne reads that answer, translates it into Rinne's vocabulary, and updates the merchant's [requirements](/onboarding/requirements). You get structured reasons and a precise list of what to send, and nothing that is still valid is ever asked again.

```mermaid theme={null}
flowchart TD
    PR[Provider rejects, or asks<br/>for more on an open affiliation] --> RV[Rinne reviews<br/>the provider's text]
    RV --> RC[affiliation.requirements-changed<br/>refused evidence, new requirements,<br/>rejection_reasons on a rejection]
    RC --> S[You or the contact supply<br/>what is missing]
    S --> C{What did the<br/>provider answer?}
    C -- A rejection, at any provider --> N[Create a new affiliation:<br/>everything still valid is SATISFIED]
    C -- A request on an open<br/>CAPPTA affiliation --> K[The same affiliation continues]
```

## 1. The provider answers

* **A rejection** moves the affiliation to `REJECTED` at once. `provider_status_message` carries the provider's own text, and `rejection_reasons` stays empty until Rinne's review.
* **A request for more** on an affiliation the provider is still analyzing leaves the status where it is until the review lands. `provider_status_message` carries what the provider said.

## 2. Rinne reviews it

Rinne reads the provider's text and records what it means, aiming to finish the same business day:

* Which documents or verifications were refused. They become `REJECTED` for that provider and are never sent to it again, and their requirements read `REJECTED` until new evidence arrives.
* Which requirements the provider added for this merchant: documents, an `INFORMATION` question, or an `EVIDENCE_PACKAGE` request. Each carries a `description` written for the merchant's contact.
* Which merchant data has to be corrected, or that the refusal is final.

`affiliation.requirements-changed` fires with the IDs of the requirements that changed. On a rejection, the affiliation also gets `rejection_reasons` and `rejection_reviewed_at`:

```json Affiliation after the review theme={null}
{
  "id": "2352ebe5-97c2-4625-8535-cc21b732787a",
  "provider": "CELCOIN",
  "status": "REJECTED",
  "provider_status_code": "reproved",
  "provider_status_message": "Documento do sócio ilegível",
  "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"
    }
  ],
  "onboarding_url": null
}
```

A review that finds nothing for the merchant to do sets `rejection_reviewed_at` with an empty `rejection_reasons`.

### Reason codes

| `code` | Meaning |
| - | - |
| `DOCUMENT_UNREADABLE` | A document could not be read |
| `DOCUMENT_DATA_MISMATCH` | A document's data does not match the merchant's registration |
| `DOCUMENT_EXPIRED` | A document is past its validity |
| `DOCUMENT_MISSING` | A document the provider needs was not sent |
| `FACEMATCH_FAILED` | The selfie does not match the identity document |
| `COMPANY_DATA_MISMATCH` | The merchant's data does not match official records |
| `COMPLIANCE_REFUSAL` | The provider refused the merchant for compliance reasons |
| `OTHER` | Anything else; `message` explains it |

### Actions

| `action` | What you do |
| - | - |
| `RESUBMIT_DOCUMENT` | Send new evidence for the document named in `onboarding_document_id` (or the requirement in `requirement_id`). The refused one no longer counts at this provider |
| `NEW_REQUIREMENT` | Satisfy the requirement named in `requirement_id`, which the review added |
| `FIX_COMPANY_DATA` | Correct the merchant with `PATCH /v1/merchants/{merchantId}` (or `PATCH /v1/companies/me` for your organization), then create the affiliation again |
| `NONE` | Final: there is nothing to resend, and a new affiliation would be refused again. `message` says why |

## 3. Supply what is missing and try again

Supply the new items through the [API](/onboarding/api) or the [onboarding link](/onboarding/onboarding-link). What happens next depends on what the provider answered:

<Tabs>
  <Tab title="A rejection: a new affiliation">
    A `REJECTED` affiliation never goes back to collecting at any provider; it leaves `REJECTED` only if the provider [reverses its refusal](#edge-cases). So every correction after a rejection is a new submission. Create a new affiliation for the same provider: it starts from the merchant's updated requirements, with everything still valid already `SATISFIED`, such as an approved biometric verification and the documents the provider did not refuse. If something is pending it comes with its own onboarding link; a rejected affiliation has none.

    ```bash cURL theme={null}
    curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/a7089150-0d61-498f-b7ca-4767e4e4d6a4/affiliations \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "provider": "CELCOIN",
        "allowed_capture_methods": ["ECOMMERCE"],
        "allowed_payment_methods": ["PIX"]
      }'
    ```

    In the example above, the new affiliation asks only for a new identity document. When it arrives, Rinne submits.
  </Tab>

  <Tab title="A request for more: the same affiliation continues">
    Only `CAPPTA` asks for more on an affiliation it is still analyzing, and it takes the supplement on that same affiliation. After the review the affiliation is `WAITING_DOCUMENTS` and its `onboarding_url` carries a link for the new items. This wait has no deadline: the affiliation stays there until the items arrive or you cancel it. Once the last one is satisfied, Rinne delivers the supplement and the affiliation moves to `PENDING`, then back to `PROCESSING`. See [the example below](#example-a-provider-asks-for-proof-of-the-business), through the link and through the API.
  </Tab>
</Tabs>

<Note>
  Created a new affiliation before the review of the previous rejection landed? It is created `PENDING` and held. When the review lands it moves to `WAITING_DOCUMENTS` if something was reset or added, or is submitted at once.
</Note>

## Example: a provider asks for proof of the business

A typical request on an open `CAPPTA` affiliation asks how the merchant earns its revenue and for proof that the business operates. After Rinne's review the merchant has two new requirements, both with `origin` `PROVIDER_REQUEST`: an `INFORMATION` question and an `EVIDENCE_PACKAGE`, each with a `description` written for the contact. `affiliation.requirements-changed` names them, and the affiliation is `WAITING_DOCUMENTS`. Either path below satisfies them; what one supplies disappears from the other.

<Tabs>
  <Tab title="Through the onboarding link">
    Send the contact the affiliation's `onboarding_url`. The new items appear tagged "Pedido do provedor", each in the provider's words, beside anything a refusal sent back:

    <div className="grid grid-cols-1 gap-4 sm:grid-cols-3">
      <Frame caption="1. The new requests">
        <img src="https://mintcdn.com/rinne/yv4xKlCoaVi2R_j5/images/company-onboarding/link-after-review.png?fit=max&auto=format&n=yv4xKlCoaVi2R_j5&q=85&s=8e9a1f168b9f54e674ca85faeb9572ec" alt="Onboarding link checklist in Portuguese after a provider review: the identity document marked 'Enviar de novo', a power of attorney, and a proof of address and a question about revenue both tagged 'Pedido do provedor'" width="804" height="1748" data-path="images/company-onboarding/link-after-review.png" />
      </Frame>

      <Frame caption="2. A text answer">
        <img src="https://mintcdn.com/rinne/yv4xKlCoaVi2R_j5/images/company-onboarding/link-request-question.png?fit=max&auto=format&n=yv4xKlCoaVi2R_j5&q=85&s=a7e5eab672daa08a3f1188034e464500" alt="Onboarding link question screen in Portuguese: 'Pergunta do provedor' asks where most of the merchant's revenue comes from, with the contact's answer about bread and pastry sales at the counter and orders by message, and an 'Enviar resposta' button" width="804" height="1748" data-path="images/company-onboarding/link-request-question.png" />
      </Frame>

      <Frame caption="3. Files and a note">
        <img src="https://mintcdn.com/rinne/yv4xKlCoaVi2R_j5/images/company-onboarding/link-request-evidence.png?fit=max&auto=format&n=yv4xKlCoaVi2R_j5&q=85&s=8d5919f9109eab4d38a52191de30f9cd" alt="Onboarding link evidence screen in Portuguese: 'Comprovação do negócio' asks for photos of the storefront and interior, a website, social profiles or recent invoices, with buttons to take a photo or choose a file, an optional explanation and an 'Enviar comprovação' button" width="804" height="1748" data-path="images/company-onboarding/link-request-evidence.png" />
      </Frame>
    </div>

    The proof closes when the contact sends it: no more files can be added unless the provider asks again.
  </Tab>

  <Tab title="Through the API">
    <Steps>
      <Step title="Read what was asked">
        ```bash cURL theme={null}
        curl "https://api-sandbox.rinne.com.br/core/v1/merchants/a7089150-0d61-498f-b7ca-4767e4e4d6a4/onboarding-requirements?provider=CAPPTA" \
          -H "x-api-key: YOUR_API_KEY"
        ```

        ```json 200 OK theme={null}
        {
          "data": [
            {
              "id": "c789cd1d-5b85-4a01-af0c-02ce13c47926",
              "company_id": "a7089150-0d61-498f-b7ca-4767e4e4d6a4",
              "provider": "CAPPTA",
              "type": "INFORMATION",
              "subject_document_number": "12345678000195",
              "subject_role": "COMPANY",
              "origin": "PROVIDER_REQUEST",
              "description": "Where does most of the company's revenue come from? Describe the products or services and the sales channels.",
              "status": "PENDING",
              "accepted_document_types": null,
              "satisfied_by": null,
              "waived_at": null,
              "created_at": "2026-10-14T15:20:00.000Z",
              "updated_at": "2026-10-14T15:20:00.000Z"
            },
            {
              "id": "56540bc6-946c-4089-a873-2e6bf823766b",
              "company_id": "a7089150-0d61-498f-b7ca-4767e4e4d6a4",
              "provider": "CAPPTA",
              "type": "EVIDENCE_PACKAGE",
              "subject_document_number": "12345678000195",
              "subject_role": "COMPANY",
              "origin": "PROVIDER_REQUEST",
              "description": "Show that the business exists and operates: photos of the storefront and interior, a website, social profiles or recent invoices.",
              "status": "PENDING",
              "accepted_document_types": null,
              "satisfied_by": null,
              "waived_at": null,
              "created_at": "2026-10-14T15:20:00.000Z",
              "updated_at": "2026-10-14T15:20:00.000Z"
            }
          ]
        }
        ```
      </Step>

      <Step title="Answer the question">
        ```bash cURL theme={null}
        curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/a7089150-0d61-498f-b7ca-4767e4e4d6a4/onboarding-requirements/c789cd1d-5b85-4a01-af0c-02ce13c47926/answer \
          -H "x-api-key: YOUR_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{
            "text": "Most of it comes from bread and pastries sold at the counter of the physical store. We also take orders by message for pickup."
          }'
        ```

        The response is `201` with the question `SATISFIED` and the text in `satisfied_by.answer`.
      </Step>

      <Step title="Attach the files to the package">
        Open one upload per file with `type` `OTHER` and the package's ID in `requirement_id`, then send the bytes and confirm it, as in [Upload documents](/onboarding/api#2-upload-documents):

        ```bash cURL theme={null}
        curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/a7089150-0d61-498f-b7ca-4767e4e4d6a4/onboarding-documents \
          -H "x-api-key: YOUR_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{
            "type": "OTHER",
            "subject_document_number": "12345678000195",
            "requirement_id": "56540bc6-946c-4089-a873-2e6bf823766b",
            "file_name": "storefront.jpg",
            "content_type": "image/jpeg"
          }'
        ```

        Repeat for each file, here also `interior.jpg`. Until the package is closed, its requirement stays `PENDING` however many files it holds.
      </Step>

      <Step title="Close the package with its explanation">
        ```bash cURL theme={null}
        curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/a7089150-0d61-498f-b7ca-4767e4e4d6a4/onboarding-requirements/56540bc6-946c-4089-a873-2e6bf823766b/answer \
          -H "x-api-key: YOUR_API_KEY" \
          -H "Content-Type: application/json" \
          -d '{
            "text": "The bakery has operated at the registered address since 2019. Attached: the storefront and the counter during opening hours."
          }'
        ```

        ```json 201 Created theme={null}
        {
          "id": "56540bc6-946c-4089-a873-2e6bf823766b",
          "company_id": "a7089150-0d61-498f-b7ca-4767e4e4d6a4",
          "provider": "CAPPTA",
          "type": "EVIDENCE_PACKAGE",
          "subject_document_number": "12345678000195",
          "subject_role": "COMPANY",
          "origin": "PROVIDER_REQUEST",
          "description": "Show that the business exists and operates: photos of the storefront and interior, a website, social profiles or recent invoices.",
          "status": "SATISFIED",
          "accepted_document_types": null,
          "satisfied_by": {
            "onboarding_document_ids": [
              "ab1f2e55-3588-4c33-841a-e152f770e8a8",
              "58ddade2-39c6-47ca-873e-b9ba8ff1ff54"
            ],
            "biometric_verification_id": null,
            "answer": "The bakery has operated at the registered address since 2019. Attached: the storefront and the counter during opening hours."
          },
          "waived_at": null,
          "created_at": "2026-10-14T15:20:00.000Z",
          "updated_at": "2026-10-14T16:42:31.000Z"
        }
        ```

        The text is optional, but a package with neither text nor an accepted attachment answers `400`. Once closed, a new attachment answers `409` until the provider refuses the package.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Check>
  With both requirements `SATISFIED`, Rinne delivers the supplement: the affiliation moves to `PENDING`, then back to `PROCESSING` while the provider analyzes it.
</Check>

## Edge cases

<AccordionGroup>
  <Accordion title="The provider reverses its refusal">
    When the provider reverses a rejection at Rinne's request, the same affiliation goes from `REJECTED` to `ACTIVE`, and `affiliation.status-changed` reports it.
  </Accordion>

  <Accordion title="Merchant data was corrected">
    After `FIX_COMPANY_DATA`, correcting a merchant also runs its [KYC checks](/concepts/kyc) again, as any update of its identification data does. Then create the new affiliation.
  </Accordion>

  <Accordion title="A final refusal">
    Rinne does not block a new affiliation after `action` `NONE`, but the provider refuses it again. Treat `NONE` as the end of onboarding with that provider for this merchant.
  </Accordion>

  <Accordion title="A document refused by one provider">
    The refusal is per provider. The document is never sent to the provider that refused it again, while every other provider keeps using it.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.