Skip to main content
Affiliations represent the connection between a merchant and a payment provider. Before processing transactions, merchants must have an active affiliation with a provider that supports their desired payment methods.

​
What is an affiliation?

An affiliation is a merchant account with a payment provider (such as Celcoin, Rinne, or Cappta) that enables transaction processing. Each affiliation:
  • Links a merchant to a specific provider
  • Defines allowed payment methods (PIX, credit card, etc.)
  • Defines allowed capture methods (e-commerce, POS, etc.)
  • Stores provider-specific merchant credentials
  • Tracks activation status and onboarding progress

​
Entity relationships

​
Affiliation lifecycle

The following diagram shows the complete affiliation status flow:

​
1. Creation

What a provider needs from the merchant before it can decide is collected by onboarding. The creation response says where the affiliation starts:
  • WAITING_DOCUMENTS, with an onboarding_url, when something is still pending: an identity document, a biometric verification, the articles of incorporation. Supply it through the API or send the onboarding link; Rinne submits the affiliation when the last item arrives, unless Rinne’s review of a previous rejection is still open, which holds it at PENDING until the review lands.
  • PENDING_APPROVAL, or PROCESSING at providers without a document stage, when everything the provider needs is already on file: Rinne submits it within the same call and onboarding_url is null.
  • PENDING when it is held until a previous attempt for the same document, or Rinne’s review of a previous rejection, finishes.
What each provider requires decides which one applies.

​
2. Provider approval

The provider reviews the merchant information and either:
  • Approves: Status changes to ACTIVE
  • Asks for more: Rinne reviews the request and turns it into new requirements; a provider that takes supplements moves the affiliation to WAITING_DOCUMENTS
  • Rejects: Status changes to REJECTED, and Rinne’s review adds rejection_reasons saying what to fix. See When the provider asks for more
You’ll receive webhook notifications for status changes.

​
3. Activation

Once approved, the affiliation becomes ACTIVE and you can:
  • Process transactions using this provider
  • Receive payments to the affiliated bank account
  • Access provider-specific features

​
4. Blocks and closures

After activation, the provider keeps monitoring the merchant’s registration (CPF or CNPJ) with the RFB (Receita Federal do Brasil) and acts on its own when the registration status changes. You receive an affiliation.status-changed webhook for each move, with the provider’s reason in provider_status_message:
  • Reversible irregularity, such as a pending tax return or a suspended registration: the affiliation moves to BLOCKED. Transactions stop, but nothing is deleted or moved. Once the merchant regularizes the registration with the RFB, the provider reactivates the affiliation to ACTIVE on its own; there is no document to send and nothing to request.
  • Irreversible irregularity, such as a cancelled CPF, a deceased holder or a deactivated CNPJ: the affiliation moves to BLOCKED while the provider winds the account down, then to CLOSED. The provider deletes the account’s PIX keys and cancels pending boletos as part of closure.
CLOSED is terminal. Onboarding the merchant again requires a new affiliation, and the provider will not accept one for a document that is still irregular.
The provider can also move an affiliation between BLOCKED and ACTIVE for compliance reasons unrelated to registration monitoring. Treat provider_status_message as the source of truth for why a given change happened.

​
Affiliation status

​
Payment and capture methods

​
Payment methods

Specify which payment types the merchant can accept:
  • PIX: Instant payments via Brazil’s PIX system
  • CREDIT_CARD: Credit card payments
  • DEBIT_CARD: Debit card payments
  • BOLEPIX: Hybrid boleto + PIX payments

​
Capture methods

Specify how payments are captured:
  • ECOMMERCE: Online transactions
  • EMV: Chip card (POS terminal)
  • MAGSTRIPE: Magnetic stripe (POS terminal)
  • CONTACTLESS_ICC: Contactless payments (NFC)
The provider must support your selected payment and capture methods. Check provider capabilities before creating affiliations.

​
Anticipation configuration

Affiliations support anticipation configuration to control how and when merchants receive their funds from credit card transactions.
Anticipation settings only affect credit card transactions. Other payment methods like PIX have their own settlement rules.

​
Anticipation type

The anticipation_type field determines the settlement strategy:

​
Anticipation days

The anticipation_days field specifies the number of days for the credit card anticipation cycle:
  • Minimum value: 1 day
  • Default value: 1 day (if not specified)
Anticipation configuration affects when merchants receive their settled funds from credit card sales. Work with your account manager to determine the best configuration for your business needs.

​
Example with anticipation settings

​
Updating the anticipation configuration

After an affiliation exists, you can change its anticipation type and/or days without recreating it. The update is synchronous — by the time the request returns, the change has been applied at the provider and persisted on the affiliation.
This operation is supported today only for affiliations created with the CAPPTA provider. Affiliations with other providers return a 400.
Permissions
  • Organization (company) affiliation: affiliation.edit
  • Merchant-scoped affiliation: merchant.affiliation.edit
Preconditions
  • Affiliation status must be ACTIVE and enabled must be true.
  • When anticipation_type is AUTOMATIC, anticipation_days must be 1 — only D+1 automatic anticipation is supported by the provider. SPOT accepts any anticipation_days >= 1.

​
Request fields

Both fields are optional, and at least one must be provided. Any field you omit keeps its current value.
​
string
New anticipation type for the affiliation. One of: AUTOMATIC, SPOT.
​
integer
New number of days for the anticipation cycle. Must be at least 1. When anticipation_type is AUTOMATIC, this must be 1.

​
Request examples

Merchant context (organization acting on a merchant):
cURL (merchant-scoped)
Organization (own company) affiliation:
cURL (organization-scoped)

​
Success response (200 OK)

Returns the updated affiliation with the new anticipation_type and anticipation_days:
200 OK
If the requested anticipation_type and anticipation_days already match the affiliation’s current values, the call is a no-op — the response still returns 200 with the affiliation unchanged.

​
Error responses

Provider does not support anticipation updates (any provider other than CAPPTA):
400 Bad Request
Affiliation is not active or not enabled:
400 Bad Request
AUTOMATIC requested with anticipation_days other than 1:
400 Bad Request

​
Company snapshot

When an affiliation is created, Rinne captures a snapshot of the company data, including contact information. While an affiliation that was never submitted to its provider waits in WAITING_DOCUMENTS, the snapshot follows the company: a change to the company or its contact reaches it within minutes. When the affiliation is submitted, the snapshot is taken one last time and then stays fixed, so it preserves the company data the provider received, which is useful for:
  • Compliance and audit trails
  • Historical record keeping
  • Tracking changes to company information over time
The company_snapshot field contains a complete copy of the company data (excluding sensitive information like API keys and internal configurations) as it was when the affiliation was submitted. Before the first submission, it holds the company data as of its last refresh, which follows the company only while the affiliation waits in WAITING_DOCUMENTS: an affiliation held in PENDING, or cancelled before it was submitted, keeps the data it last took.
The company snapshot is stored automatically but is not included in API responses by default to reduce payload size. Use the include_company_snapshot=true query parameter to retrieve it when needed.

​
Retrieving company snapshots

To include the company snapshot in affiliation responses, add the include_company_snapshot=true query parameter:
The response will include the company_snapshot field with the preserved company data:

​
Onboarding documents

During the affiliation onboarding process, payment providers may require specific documents for compliance and KYC (Know Your Customer) verification. These documents are uploaded to secure storage and tracked as part of the affiliation.
The documents a merchant supplies for onboarding are onboarding documents: uploaded once per person or merchant and reused by every affiliation that needs them. This section covers the onboarding_documents array of the affiliation response.
Each entry is one document the affiliation sent to its provider, and includes:
  • id: This send of the document to the provider, not the document’s own id
  • onboarding_document_id: The document sent, as GET /v1/onboarding-documents lists it; affiliations that sent the same document share it
  • type: The document’s type in Rinne’s vocabulary (e.g., CNH_DIGITAL, SELFIE, ARTICLES_OF_INCORPORATION)
  • file_type: The document’s type as the provider received it (e.g., CNH_FRONT, SELFIE, CONTRATO_SOCIAL)
  • file_name: Generated filename in storage; empty for a shared document
  • content_type: MIME type of the document (e.g., application/pdf, image/jpeg); null for a shared document
  • file_size_bytes: Size of the file in bytes; null for a shared document
  • created_at: When the document was stored
The onboarding_documents array is included in affiliation responses. To download a specific document, use Get onboarding document with download URL, which accepts either id or onboarding_document_id and returns a signed download URL that expires after 1 hour. A shared document has no file to download, so the endpoint returns 404 for it:

​
Multiple affiliations

Merchants can have multiple affiliations with different providers:
However, each merchant can only have one affiliation per provider.
You can omit provider when you create a transaction. If only one affiliation can process the payment method, Rinne uses it. If several can, Rinne applies the configured routing defaults or returns 400 with provider REQUIRED. See Provider selection.

​
Bank accounts

Affiliations use two distinct types of bank accounts depending on the provider and payment method:
Cashouts use different resources: external bank accounts and external PIX key destinations under the Cashouts APIs (/bank-accounts, /pix-keys), documented in Cashouts. Those are not the same as affiliation BaaS accounts below or card settlement bank accounts in this section.

​
Affiliation bank accounts

Affiliation bank accounts are BaaS (Banking as a Service) provider accounts created and managed by Rinne. They are used for PIX and bolepix payment methods through providers like Celcoin.
  • Created automatically by Rinne during the affiliation process
  • Used for receiving PIX and bolepix payments
  • Managed internally — merchants don’t need to provide these
Each affiliation bank account has an operational_status that reflects whether the bank account is restricted: When operational_status changes, Rinne sends an affiliation-bank-account.operational-status-changed webhook with a full bank account snapshot in entity. See Webhooks for the payload and handler examples.
Affiliation bank accounts can be subject to court-ordered fund blocks. See Banking → Judicial blockages for how to list block and release movements, and subscribe to judicial-blockage.created for real-time notifications of each movement.

​
Settlement bank accounts

Settlement bank accounts are external bank accounts that organizations provide during a merchant’s affiliation creation for card payment methods. They are used to settle card receivables (credit and debit card transactions) through card providers like Cappta.
  • Provided in the settlement_bank_account object on affiliation creation (required for RINNE and CAPPTA when card methods apply; see the API reference for your provider)
  • Returned as settlement_bank_accounts: an array of accounts, each with its own id, status, and timestamps—an affiliation can have more than one record over time (for example a previous account marked DISABLED after a successful change)
  • Sent to the card provider for validation (ownership and account verification)
  • Account holder document must match the merchant’s document

​
Settlement bank account status

Each entry in settlement_bank_accounts includes a status that reflects provider validation: While a new account is PENDING_VALIDATION, any existing ACTIVE settlement bank account continues to receive settlements until the new account is validated and promoted. If the replacement account fails validation (VALIDATION_FAILED or FAILED), the affiliation status remains unchanged — it stays ACTIVE because the previous settlement account is still valid and in use. The affiliation only transitions to INVALID_SETTLEMENT_BANK_ACCOUNT when there is no valid active settlement account (for example during initial onboarding or after the sole active account is invalidated by the provider).
Only one PENDING_VALIDATION settlement bank account is allowed per affiliation at a time. Submit another update only after the pending request completes (success or failure) or your integration handles the terminal outcome.
On create, use the singular field settlement_bank_account in the request body. List and get affiliation responses expose settlement_bank_accounts (array).

​
Updating the settlement bank account

After an affiliation exists, you can request a new settlement bank account without recreating the affiliation. The API creates a new row in PENDING_VALIDATION and calls the provider to start async validation. Permissions
  • Organization (company) affiliation: affiliation.edit
  • Merchant-scoped affiliation: merchant.affiliation.edit

​
Request fields

​
string
required
ISPB code of the bank (exactly 8 digits). Identifies the bank institution.
​
string
required
Branch number (digits only, no separators).
​
string
required
Account number (digits only, no separators).
​
string
required
Type of bank account. One of: CHECKING, SAVINGS, SALARY, PAYMENT.

​
Request examples

Merchant context (organization acting on a merchant):
Organization (own company) affiliation:

​
Success response (201 Created)

The response returns the full affiliation object. The settlement_bank_accounts array now includes the new entry in PENDING_VALIDATION:

​
Error response (400 — provider does not support operation)

Providers that do not support external settlement bank accounts (such as Celcoin) return a validation error:

​
Tracking the validation lifecycle

Once the settlement bank account is created:
  1. The account starts in PENDING_VALIDATION. Your existing ACTIVE settlement account continues receiving settlements normally.
  2. A scheduled background job polls the provider every ~5 minutes. It checks PENDING_VALIDATION accounts and reconciles their status. Accounts whose affiliation is REJECTED, FAILED, or CLOSED are skipped (see the note below). Possible outcomes:
    • ACTIVE: Provider validated successfully — the new account takes over, and the previous ACTIVE account becomes DISABLED.
    • VALIDATION_FAILED: Provider rejected the account (for example invalid bank details).
    • FAILED: Unrecoverable error on the provider side.
    • DISABLED: Provider deactivated the account.
  3. If validation fails and there is no other valid settlement account, the affiliation may transition to INVALID_SETTLEMENT_BANK_ACCOUNT. You can submit a replacement via the same endpoint and the process repeats.
  4. When the replacement account is validated and becomes ACTIVE, the affiliation status is reconciled from the provider — an affiliation in INVALID_SETTLEMENT_BANK_ACCOUNT returns to ACTIVE instead of remaining stuck.
Polling pauses for inactive affiliations. If the affiliation is REJECTED, FAILED, or CLOSED, Rinne stops checking its PENDING_VALIDATION settlement bank account with the provider. The account keeps the PENDING_VALIDATION status and does not move to a final status. REJECTED is not terminal. If the affiliation returns to ACTIVE, the next polling run checks the account again and promotes it to ACTIVE once the provider validates it.
How to monitor:
  • Subscribe to the affiliation.status-changed webhook — watch for new_status === 'INVALID_SETTLEMENT_BANK_ACCOUNT' to know when the provider rejected the bank account.
  • Poll GET /v1/affiliations/{id} (or the merchant-scoped equivalent) and check settlement_bank_accounts[].status until the pending entry resolves. Stop polling if the affiliation’s status is REJECTED, FAILED, or CLOSED: the entry stays PENDING_VALIDATION and resolves only if a REJECTED affiliation returns to ACTIVE, which the affiliation.status-changed webhook reports.
  • When the new account reaches ACTIVE, the affiliation status is also reconciled — recovering from INVALID_SETTLEMENT_BANK_ACCOUNT back to ACTIVE.

​
Sandbox testing behavior

In the sandbox, the last digit of the merchant contact’s phone decides whether an affiliation is approved or rejected, and the contact’s CPF decides the biometric verification. The digits, the outcomes and a full test run are in Test onboarding in the sandbox.

​
Checking affiliation status

List all affiliations for a merchant:
Filter by status or provider:

​
Across all merchants, with counts by status

GET /v1/merchants/affiliations lists the affiliations of every merchant in your organization, with the same filters plus company_id and document_number (the merchant’s CPF or CNPJ). It requires the merchant.affiliation.list permission. Beside data and pagination, the response carries counts.status: how many affiliations each status holds across all pages, so a dashboard can show how many affiliations are waiting for documents or were rejected without paging through them. They count affiliations, not merchants: a merchant with two rejected attempts counts twice under REJECTED.
200 OK
Each item in data has the shape every affiliation response has; this one is the affiliation from the onboarding link’s create example. The counts apply every filter of the request except status: here pagination.total is the 12 CELCOIN affiliations in WAITING_DOCUMENTS that data pages through, and counts.status.REJECTED is how many status=REJECTED&provider=CELCOIN would list. Every status is present, and a status no affiliation holds counts 0. The merchant-scoped list above returns no counts.

​
Next steps

Transactions

Process payments through affiliations

Affiliation PIX keys

Provider keys for receiving PIX payments