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 (like Celcoin) 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"]
  }'

​
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

StatusDescription
PENDINGInitial creation, awaiting submission
PENDING_APPROVALSubmitted to provider, awaiting review
WAITING_DOCUMENTSProvider requires additional documentation
PROCESSING_DOCUMENTSProvider is reviewing submitted documents
ACTIVEApproved and ready for transactions
BLOCKEDTemporarily blocked by provider
REJECTEDProvider rejected the affiliation
FAILEDTechnical 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.

​
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: Another provider for cards
{
  "provider": "RINNE",
  "allowed_payment_methods": ["CREDIT_CARD", "DEBIT_CARD"]
}
However, each merchant can only have one affiliation per provider.

​
Bank accounts

When an affiliation is activated, it’s linked to a bank account where funds will be settled. The bank account is created during merchant setup or can be added later. Requirements:
  • Account holder document must match merchant document
  • Account must be active and verified
  • Only one primary bank account per merchant

​
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 endingBehavior
1Complete flow - affiliation will be approved/active after collecting and processing documents
2Early rejection - a rejected webhook will arrive before requesting documents
3Late 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"

​
Next steps

Transactions

Process payments through affiliations

PIX Keys

Create PIX keys for receiving payments