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

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
`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
BOLETO: Bank slip payments
MONEY: Cash 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.

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

Multiple affiliations

Bank accounts

Sandbox testing behavior

Example

Checking affiliation status

Next steps

Transactions

PIX Keys

Getting started

Core concepts

Guides

​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

​Multiple affiliations

​Bank accounts

​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

Multiple affiliations

Bank accounts

Sandbox testing behavior

Example

Checking affiliation status

Next steps