> ## 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. # Affiliations > Connect merchants to payment providers for transaction processing 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 ```mermaid theme={null} graph LR M[Merchant] -->|has many| A[Affiliations] A -->|connects to| P[Provider
Celcoin, Rinne, Cappta] A -->|enables| T[Transactions] A -->|linked to| ABA[Affiliation
Bank Account] A -->|linked to| SBA[Settlement
Bank Account] A -->|creates| PK[PIX Keys] style M fill:#7B89FF,color:#fff style A fill:#5B68EB,color:#fff style P fill:#4A56D9,color:#fff style T fill:#7B89FF,color:#fff style ABA fill:#5B68EB,color:#fff style SBA fill:#5B68EB,color:#fff style PK fill:#7B89FF,color:#fff ``` ## Affiliation lifecycle The following diagram shows the complete affiliation status flow: ```mermaid theme={null} stateDiagram-v2 [*] --> PENDING: Create affiliation PENDING --> PENDING_APPROVAL: Submit to provider PENDING_APPROVAL --> ACTIVE: Provider approves PENDING_APPROVAL --> WAITING_DOCUMENTS: Documents required PENDING_APPROVAL --> REJECTED: Provider rejects PENDING_APPROVAL --> INVALID_SETTLEMENT_BANK_ACCOUNT: Settlement bank invalid WAITING_DOCUMENTS --> PROCESSING_DOCUMENTS: Submit documents PROCESSING_DOCUMENTS --> ACTIVE: Documents approved PROCESSING_DOCUMENTS --> REJECTED: Documents rejected ACTIVE --> BLOCKED: Provider blocks BLOCKED --> ACTIVE: Provider unblocks PENDING_APPROVAL --> FAILED: Technical error INVALID_SETTLEMENT_BANK_ACCOUNT --> ACTIVE: Settlement validated; status reconciled REJECTED --> [*] FAILED --> [*] ``` ### 1. Creation When you create an affiliation, it starts with status `PENDING_APPROVAL`: ```bash theme={null} curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/affiliations \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "provider": "CELCOIN", "allowed_capture_methods": ["ECOMMERCE"], "allowed_payment_methods": ["PIX"], "anticipation_type": "AUTOMATIC", "anticipation_days": 1 }' ``` ### 2. Provider approval The provider reviews the merchant information and either: * **Approves**: Status changes to `ACTIVE` * **Requests documents**: Status changes to `WAITING_DOCUMENTS` * **Rejects**: Status changes to `REJECTED` 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 ## Affiliation status | Status | Description | | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PENDING` | Initial creation, awaiting submission | | `PENDING_APPROVAL` | Submitted to provider, awaiting review | | `WAITING_DOCUMENTS` | Provider requires additional documentation | | `PROCESSING_DOCUMENTS` | Provider is reviewing submitted documents | | `ACTIVE` | Approved and ready for transactions | | `BLOCKED` | Temporarily blocked by provider | | `REJECTED` | Provider rejected the affiliation | | `INVALID_SETTLEMENT_BANK_ACCOUNT` | Provider rejected or could not validate the settlement bank account—not terminal. Submit a replacement via [settlement bank account update](#updating-the-settlement-bank-account); when async validation succeeds, affiliation status is reconciled (often back to `ACTIVE`) | | `FAILED` | Technical failure during creation | ## 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: | Type | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | | `AUTOMATIC` | Credit card funds are automatically settled on a recurring schedule based on `anticipation_days`. This is the default behavior. | | `SPOT` | Credit card funds are settled on-demand or at specific intervals defined by your agreement. | ### 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 ```bash theme={null} curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/affiliations \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "provider": "CELCOIN", "allowed_capture_methods": ["ECOMMERCE"], "allowed_payment_methods": ["CREDIT_CARD", "DEBIT_CARD"], "anticipation_type": "AUTOMATIC", "anticipation_days": 1 }' ``` ### 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. New anticipation type for the affiliation. One of: `AUTOMATIC`, `SPOT`. 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): ```bash cURL (merchant-scoped) theme={null} curl -X PATCH "https://api-sandbox.rinne.com.br/core/v1/merchants/b4ece1d3-0a8a-5097-9dbb-58880c4f3894/affiliations/a3dbd0c2-9f79-4f86-8caa-47779b3f2794" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "anticipation_type": "SPOT", "anticipation_days": 30 }' ``` **Organization (own company) affiliation**: ```bash cURL (organization-scoped) theme={null} curl -X PATCH "https://api-sandbox.rinne.com.br/core/v1/affiliations/a3dbd0c2-9f79-4f86-8caa-47779b3f2794" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "anticipation_type": "AUTOMATIC", "anticipation_days": 1 }' ``` #### Success response (200 OK) Returns the updated affiliation with the new `anticipation_type` and `anticipation_days`: ```json 200 OK theme={null} { "id": "a3dbd0c2-9f79-4f86-8caa-47779b3f2794", "provider": "CAPPTA", "merchant_id": "12345678", "status": "ACTIVE", "enabled": true, "company_id": "b4ece1d3-0a8a-5097-9dbb-58880c4f3894", "organization_id": "c5fdf2e4-1b9b-6108-aece-69991d5e4905", "allowed_capture_methods": ["ECOMMERCE"], "allowed_payment_methods": ["CREDIT_CARD", "DEBIT_CARD"], "anticipation_type": "SPOT", "anticipation_days": 30, "bank_account": null, "settlement_bank_accounts": [ { "id": "e7afa4c6-3d1d-8320-cbec-81113f7b6127", "branch_number": "1234", "account_number": "567890", "account_type": "CHECKING", "account_holder_name": "My Store LTDA", "account_holder_document_number": "12345678000190", "ispb": "00000000", "status": "ACTIVE", "created_at": "2026-03-01T10:00:00Z", "updated_at": "2026-04-15T14:30:00Z" } ], "onboarding_documents": [], "created_at": "2026-03-01T10:00:00Z", "updated_at": "2026-05-18T14:30:00Z" } ``` 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`): ```json 400 Bad Request theme={null} { "error": { "code": "INVALID_STATE_ERROR", "message": "Provider CELCOIN does not support anticipation config updates", "status": 400 } } ``` **Affiliation is not active or not enabled**: ```json 400 Bad Request theme={null} { "error": { "code": "INVALID_STATE_ERROR", "message": "Affiliation must be active and enabled", "status": 400 } } ``` **`AUTOMATIC` requested with `anticipation_days` other than `1`**: ```json 400 Bad Request theme={null} { "error": { "code": "VALIDATION_ERROR", "message": "Only D+1 automatic anticipation is supported for Cappta affiliations", "status": 400 } } ``` ## Company snapshot When an affiliation is created, Rinne captures an immutable point-in-time snapshot of the company data, including contact information. This snapshot preserves the company's state at the moment of affiliation creation, 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 existed when the affiliation was created. 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: ```bash theme={null} curl "https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/affiliations/AFFILIATION_ID?include_company_snapshot=true" \ -H "x-api-key: YOUR_API_KEY" ``` The response will include the `company_snapshot` field with the preserved company data: ```json theme={null} { "id": "affiliation-123", "provider": "CELCOIN", "status": "ACTIVE", "company_snapshot": { "id": "company-456", "full_name": "My Store LTDA", "document_number": "12345678000190", "document_type": "CNPJ", "contact": { "first_name": "John", "last_name": "Doe", "email": "john@example.com", "phone": "+5511999999999" }, ... }, ... } ``` ## 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. Each onboarding document includes: * **file\_type**: Type of document (e.g., CNH\_FRONT, SELFIE, CONTRATO\_SOCIAL) * **file\_name**: Generated filename in storage * **content\_type**: MIME type of the document (e.g., application/pdf, image/jpeg) * **file\_size\_bytes**: Size of the file in bytes * **created\_at**: When the document was uploaded The `onboarding_documents` array is included in affiliation responses, providing metadata about all uploaded documents. To download a specific document, use the dedicated endpoint which returns a signed download URL that expires after 1 hour. ## Multiple affiliations Merchants can have multiple affiliations with different providers: ```bash theme={null} # Affiliation 1: Celcoin for PIX { "provider": "CELCOIN", "allowed_payment_methods": ["PIX"] } # Affiliation 2: Cappta for cards { "provider": "CAPPTA", "allowed_payment_methods": ["CREDIT_CARD", "DEBIT_CARD"], "settlement_bank_account": { "ispb": "00000000", "branch_number": "1234", "account_number": "567890", "account_type": "CHECKING" } } ``` However, each merchant can only have **one affiliation per provider**. ## 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](/concepts/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 ### 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: | Status | Meaning | | -------------------- | ------------------------------------------------------- | | `ACTIVE` | Account in use for card receivables settlement | | `PENDING_VALIDATION` | Submitted to the provider; async validation in progress | | `VALIDATION_FAILED` | Provider rejected the account during async validation | | `FAILED` | Unrecoverable error (for example provider client error) | | `DISABLED` | Superseded when a newer account becomes `ACTIVE` | 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 ISPB code of the bank (exactly 8 digits). Identifies the bank institution. Branch number (digits only, no separators). Account number (digits only, no separators). Type of bank account. One of: `CHECKING`, `SAVINGS`, `SALARY`, `PAYMENT`. #### Request examples **Merchant context** (organization acting on a merchant): ```bash cURL (merchant-scoped) theme={null} curl -X POST "https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/affiliations/AFFILIATION_ID/settlement-bank-account" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ispb": "00000000", "branch_number": "1234", "account_number": "567890", "account_type": "CHECKING" }' ``` **Organization (own company) affiliation**: ```bash cURL (organization-scoped) theme={null} curl -X POST "https://api-sandbox.rinne.com.br/core/v1/affiliations/AFFILIATION_ID/settlement-bank-account" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ispb": "00000000", "branch_number": "1234", "account_number": "567890", "account_type": "CHECKING" }' ``` #### Success response (201 Created) The response returns the full affiliation object. The `settlement_bank_accounts` array now includes the new entry in `PENDING_VALIDATION`: ```json 201 Created theme={null} { "id": "a3dbd0c2-9f79-4f86-8caa-47779b3f2794", "provider": "CAPPTA", "merchant_id": "12345678", "status": "ACTIVE", "enabled": true, "company_id": "b4ece1d3-0a8a-5097-9dbb-58880c4g3894", "organization_id": "c5fdf2e4-1b9b-6108-aece-69991d5h4905", "allowed_capture_methods": ["ECOMMERCE"], "allowed_payment_methods": ["CREDIT_CARD", "DEBIT_CARD"], "anticipation_type": "AUTOMATIC", "anticipation_days": 1, "bank_account": null, "settlement_bank_accounts": [ { "id": "d6geg3f5-2c0c-7219-bfdf-70002e6i5016", "branch_number": "0001", "account_number": "999888", "account_type": "CHECKING", "account_holder_name": "My Store LTDA", "account_holder_document_number": "12345678000190", "ispb": "16501555", "status": "DISABLED", "created_at": "2026-03-01T10:00:00Z", "updated_at": "2026-04-15T14:30:00Z" }, { "id": "e7hfh4g6-3d1d-8320-cgeg-81113f7j6127", "branch_number": "1234", "account_number": "567890", "account_type": "CHECKING", "account_holder_name": "My Store LTDA", "account_holder_document_number": "12345678000190", "ispb": "00000000", "status": "PENDING_VALIDATION", "created_at": "2026-04-15T14:30:00Z", "updated_at": "2026-04-15T14:30:00Z" } ], "onboarding_documents": [], "created_at": "2026-03-01T10:00:00Z", "updated_at": "2026-04-15T14:30:00Z" } ``` #### Error response (400 — provider does not support operation) Providers that do not support external settlement bank accounts (such as Celcoin) return a validation error: ```json 400 Validation Error theme={null} { "error": "VALIDATION_ERROR", "message": "Provider does not support settlement bank account updates", "status_code": 400 } ``` #### 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 all `PENDING_VALIDATION` accounts and reconciles status: * **`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. **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. * When the new account reaches `ACTIVE`, the affiliation status is also reconciled — recovering from `INVALID_SETTLEMENT_BANK_ACCOUNT` back to `ACTIVE`. ## Sandbox testing behavior When testing affiliations in the sandbox environment, you can control the affiliation flow by using specific phone number patterns for the merchant contact: | Phone ending | Behavior | | ------------ | --------------------------------------------------------------------------------------------- | | **1** | Complete flow - affiliation will be approved/active after collecting and processing documents | | **2** | Early rejection - a rejected webhook will arrive before requesting documents | | **3** | Late rejection - affiliation will be rejected after collecting and processing documents | ### Example ```bash theme={null} # This merchant will have affiliations approved after document processing curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contact": { "phone": "+5511999999991" # Ends with 1 - will be approved } }' # This merchant will have affiliations rejected before documents curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contact": { "phone": "+5511999999992" # Ends with 2 - early rejection } }' ``` This behavior only applies to the sandbox environment and is designed to help you test different affiliation scenarios. ## Checking affiliation status List all affiliations for a merchant: ```bash theme={null} curl https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/affiliations \ -H "x-api-key: YOUR_API_KEY" ``` Filter by status or provider: ```bash theme={null} curl "https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/affiliations?status=ACTIVE&provider=CELCOIN" \ -H "x-api-key: YOUR_API_KEY" ``` ## Next steps Process payments through affiliations Provider keys for receiving PIX payments