Rinne API Documentation

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

When you create an affiliation, it starts with status PENDING_APPROVAL:

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; 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

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
  }'

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:

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:

{
  "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": "[email protected]",
      "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:

# 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:

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

string

required

ISPB code of the bank (exactly 8 digits). Identifies the bank institution.

branch_number

string

required

Branch number (digits only, no separators).

account_number

string

required

Account number (digits only, no separators).

account_type

string

required

Type of bank account. One of: CHECKING, SAVINGS, SALARY, PAYMENT.

Request examples

Merchant context (organization acting on a merchant):

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:

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:

{
  "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:

{
  "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:

The account starts in PENDING_VALIDATION. Your existing ACTIVE settlement account continues receiving settlements normally.
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.
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.
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

# 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:

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:

curl "https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/affiliations?status=ACTIVE&provider=CELCOIN" \
  -H "x-api-key: YOUR_API_KEY"

Getting started

Core concepts

Guides

Affiliations

What is an affiliation?

Entity relationships

Affiliation lifecycle

1. Creation

2. Provider approval

3. Activation

Affiliation status

Payment and capture methods

Payment methods

Capture methods

Anticipation configuration

Anticipation type

Anticipation days

Example with anticipation settings

Company snapshot

Retrieving company snapshots

Onboarding documents

Multiple affiliations

Bank accounts

Affiliation bank accounts

Settlement bank accounts

Settlement bank account status

Updating the settlement bank account

Request fields

Request examples

Success response (201 Created)

Error response (400 — provider does not support operation)

Tracking the validation lifecycle

Sandbox testing behavior

Example

Checking affiliation status

Next steps

Transactions

PIX Keys

Getting started

Core concepts

Guides

Documentation Index

​What is an affiliation?

​Entity relationships

​Affiliation lifecycle

​1. Creation

​2. Provider approval

​3. Activation

​Affiliation status

​Payment and capture methods

​Payment methods

​Capture methods

​Anticipation configuration

​Anticipation type

​Anticipation days

​Example with anticipation settings

​Company snapshot

​Retrieving company snapshots

​Onboarding documents

​Multiple affiliations

​Bank accounts

​Affiliation bank accounts

​Settlement bank accounts

​Settlement bank account status

​Updating the settlement bank account

​Request fields

​Request examples

​Success response (201 Created)

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

​Tracking the validation lifecycle

​Sandbox testing behavior

​Example

​Checking affiliation status

​Next steps

Transactions

PIX Keys

What is an affiliation?

Entity relationships

Affiliation lifecycle

1. Creation

2. Provider approval

3. Activation

Affiliation status

Payment and capture methods

Payment methods

Capture methods

Anticipation configuration

Anticipation type

Anticipation days

Example with anticipation settings

Company snapshot

Retrieving company snapshots

Onboarding documents

Multiple affiliations

Bank accounts

Affiliation bank accounts

Settlement bank accounts

Settlement bank account status

Updating the settlement bank account

Request fields

Request examples

Success response (201 Created)

Error response (400 — provider does not support operation)

Tracking the validation lifecycle

Sandbox testing behavior

Example

Checking affiliation status

Next steps