Rinne API Documentation

Create a new affiliation for a specific merchant

curl --request POST \
  --url https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/affiliations \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "provider": "CELCOIN",
  "allowed_capture_methods": [
    "ECOMMERCE"
  ],
  "allowed_payment_methods": [
    "PIX"
  ]
}
'

import requests

url = "https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/affiliations"

payload = {
    "provider": "CELCOIN",
    "allowed_capture_methods": ["ECOMMERCE"],
    "allowed_payment_methods": ["PIX"]
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    provider: 'CELCOIN',
    allowed_capture_methods: ['ECOMMERCE'],
    allowed_payment_methods: ['PIX']
  })
};

fetch('https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/affiliations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/affiliations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'provider' => 'CELCOIN',
    'allowed_capture_methods' => [
        'ECOMMERCE'
    ],
    'allowed_payment_methods' => [
        'PIX'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/affiliations"

	payload := strings.NewReader("{\n  \"provider\": \"CELCOIN\",\n  \"allowed_capture_methods\": [\n    \"ECOMMERCE\"\n  ],\n  \"allowed_payment_methods\": [\n    \"PIX\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/affiliations")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"provider\": \"CELCOIN\",\n  \"allowed_capture_methods\": [\n    \"ECOMMERCE\"\n  ],\n  \"allowed_payment_methods\": [\n    \"PIX\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/affiliations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"provider\": \"CELCOIN\",\n  \"allowed_capture_methods\": [\n    \"ECOMMERCE\"\n  ],\n  \"allowed_payment_methods\": [\n    \"PIX\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "123e4567-e89b-12d3-a456-426614174002",
  "provider": "CELCOIN",
  "merchant_id": "12345678",
  "status": "ACTIVE",
  "enabled": true,
  "company_id": "a3dbd0c2-9f79-4f86-8caa-47779b3f2793",
  "onboarding_url": "https://provider.com/onboard/12345",
  "onboarding_url_expires_at": "2026-11-06T12:00:00.000Z",
  "cancellation_reason": null,
  "rejection_reviewed_at": null,
  "allowed_capture_methods": [
    "ECOMMERCE"
  ],
  "allowed_payment_methods": [
    "PIX"
  ],
  "organization_id": "a3dbd0c2-9f79-4f86-8caa-47779b3f2793",
  "gateway_mode": false,
  "onboarding_documents": [
    {
      "id": "c5fdf2e4-1b9b-6108-aece-69991d5h4905",
      "file_type": "CNH_FRONT",
      "file_name": "CNH_FRONT_a1b2c3d4.pdf",
      "created_at": "2023-06-15T14:30:00.000Z",
      "content_type": "application/pdf",
      "file_size_bytes": 125430
    }
  ],
  "created_at": "2023-01-01T12:00:00.000Z",
  "updated_at": "2023-01-01T12:00:00.000Z",
  "provider_id": "prov_123456",
  "soft_descriptor": "MYSTORE",
  "mcc": "5411",
  "cost_policy_id": "123e4567-e89b-12d3-a456-426614174003",
  "provider_status_code": "200",
  "provider_status_message": "Merchant activated successfully",
  "provider_metadata": {},
  "bank_account": {
    "id": "a2da4238-bdc2-47f9-b866-246cc87212d5",
    "bank_code": "001",
    "branch_number": "1234",
    "account_number": "567890",
    "account_holder_name": "John Doe",
    "account_holder_document_number": "81146431023",
    "ispb": "00000000",
    "operational_status": "REGULAR",
    "operational_status_occurred_at": "2025-06-26T17:07:31.495Z",
    "created_at": "2025-06-26T17:07:31.495Z",
    "updated_at": "2025-06-26T17:07:31.495Z"
  },
  "settlement_bank_accounts": [
    {
      "id": "b3eb5349-cec3-48fa-c977-357dd98323e6",
      "branch_number": "1234",
      "account_number": "567890",
      "account_type": "CHECKING",
      "account_holder_name": "John Doe",
      "account_holder_document_number": "81146431023",
      "ispb": "00000000",
      "status": "ACTIVE",
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    }
  ],
  "anticipation_type": "AUTOMATIC",
  "anticipation_days": 1,
  "company_snapshot": {}
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation error",
    "status": 400,
    "details": {
      "issues": [
        {
          "field": "email",
          "type": "REQUIRED",
          "message": "Field 'email' is required",
          "value": "invalid_value",
          "constraints": {
            "min": 18,
            "max": 120
          }
        }
      ]
    },
    "path": "/companies",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Authentication required to access this resource",
    "status": 401,
    "details": {
      "reason": "Invalid API key"
    },
    "path": "/companies/me",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "AUTHORIZATION_ERROR",
    "message": "You need 'admin' permissions to access this resource",
    "status": 403,
    "path": "/companies",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Company with ID '123' not found",
    "status": 404,
    "path": "/companies/me",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "CONFLICT_ERROR",
    "message": "The provider already has an account linked to this company's e-mail address.",
    "status": 409
  }
}

{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred",
    "status": 500,
    "path": "/companies",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

POST

merchants

{merchantId}

affiliations

Create a new affiliation for a specific merchant

curl --request POST \
  --url https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/affiliations \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "provider": "CELCOIN",
  "allowed_capture_methods": [
    "ECOMMERCE"
  ],
  "allowed_payment_methods": [
    "PIX"
  ]
}
'

import requests

url = "https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/affiliations"

payload = {
    "provider": "CELCOIN",
    "allowed_capture_methods": ["ECOMMERCE"],
    "allowed_payment_methods": ["PIX"]
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    provider: 'CELCOIN',
    allowed_capture_methods: ['ECOMMERCE'],
    allowed_payment_methods: ['PIX']
  })
};

fetch('https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/affiliations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/affiliations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'provider' => 'CELCOIN',
    'allowed_capture_methods' => [
        'ECOMMERCE'
    ],
    'allowed_payment_methods' => [
        'PIX'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/affiliations"

	payload := strings.NewReader("{\n  \"provider\": \"CELCOIN\",\n  \"allowed_capture_methods\": [\n    \"ECOMMERCE\"\n  ],\n  \"allowed_payment_methods\": [\n    \"PIX\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/affiliations")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"provider\": \"CELCOIN\",\n  \"allowed_capture_methods\": [\n    \"ECOMMERCE\"\n  ],\n  \"allowed_payment_methods\": [\n    \"PIX\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/affiliations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"provider\": \"CELCOIN\",\n  \"allowed_capture_methods\": [\n    \"ECOMMERCE\"\n  ],\n  \"allowed_payment_methods\": [\n    \"PIX\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "id": "123e4567-e89b-12d3-a456-426614174002",
  "provider": "CELCOIN",
  "merchant_id": "12345678",
  "status": "ACTIVE",
  "enabled": true,
  "company_id": "a3dbd0c2-9f79-4f86-8caa-47779b3f2793",
  "onboarding_url": "https://provider.com/onboard/12345",
  "onboarding_url_expires_at": "2026-11-06T12:00:00.000Z",
  "cancellation_reason": null,
  "rejection_reviewed_at": null,
  "allowed_capture_methods": [
    "ECOMMERCE"
  ],
  "allowed_payment_methods": [
    "PIX"
  ],
  "organization_id": "a3dbd0c2-9f79-4f86-8caa-47779b3f2793",
  "gateway_mode": false,
  "onboarding_documents": [
    {
      "id": "c5fdf2e4-1b9b-6108-aece-69991d5h4905",
      "file_type": "CNH_FRONT",
      "file_name": "CNH_FRONT_a1b2c3d4.pdf",
      "created_at": "2023-06-15T14:30:00.000Z",
      "content_type": "application/pdf",
      "file_size_bytes": 125430
    }
  ],
  "created_at": "2023-01-01T12:00:00.000Z",
  "updated_at": "2023-01-01T12:00:00.000Z",
  "provider_id": "prov_123456",
  "soft_descriptor": "MYSTORE",
  "mcc": "5411",
  "cost_policy_id": "123e4567-e89b-12d3-a456-426614174003",
  "provider_status_code": "200",
  "provider_status_message": "Merchant activated successfully",
  "provider_metadata": {},
  "bank_account": {
    "id": "a2da4238-bdc2-47f9-b866-246cc87212d5",
    "bank_code": "001",
    "branch_number": "1234",
    "account_number": "567890",
    "account_holder_name": "John Doe",
    "account_holder_document_number": "81146431023",
    "ispb": "00000000",
    "operational_status": "REGULAR",
    "operational_status_occurred_at": "2025-06-26T17:07:31.495Z",
    "created_at": "2025-06-26T17:07:31.495Z",
    "updated_at": "2025-06-26T17:07:31.495Z"
  },
  "settlement_bank_accounts": [
    {
      "id": "b3eb5349-cec3-48fa-c977-357dd98323e6",
      "branch_number": "1234",
      "account_number": "567890",
      "account_type": "CHECKING",
      "account_holder_name": "John Doe",
      "account_holder_document_number": "81146431023",
      "ispb": "00000000",
      "status": "ACTIVE",
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z"
    }
  ],
  "anticipation_type": "AUTOMATIC",
  "anticipation_days": 1,
  "company_snapshot": {}
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation error",
    "status": 400,
    "details": {
      "issues": [
        {
          "field": "email",
          "type": "REQUIRED",
          "message": "Field 'email' is required",
          "value": "invalid_value",
          "constraints": {
            "min": 18,
            "max": 120
          }
        }
      ]
    },
    "path": "/companies",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Authentication required to access this resource",
    "status": 401,
    "details": {
      "reason": "Invalid API key"
    },
    "path": "/companies/me",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "AUTHORIZATION_ERROR",
    "message": "You need 'admin' permissions to access this resource",
    "status": 403,
    "path": "/companies",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Company with ID '123' not found",
    "status": 404,
    "path": "/companies/me",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

{
  "error": {
    "code": "CONFLICT_ERROR",
    "message": "The provider already has an account linked to this company's e-mail address.",
    "status": 409
  }
}

{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred",
    "status": 500,
    "path": "/companies",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

Authorizations

x-api-key

string

header

required

Company API key for authentication

Path Parameters

merchantId

string

required

The merchant ID

Body

application/json

Schema for creating a new affiliation

provider

enum<string>

required

Payment provider name (accepts lowercase and uppercase, returns uppercase)

Available options:

CELCOIN,

RINNE,

CAPPTA

Example:

"CELCOIN"

allowed_capture_methods

enum<string>[]

required

Allowed capture methods (at least one required)

Minimum array length: 1

Available options:

EMV,

MAGSTRIPE,

ECOMMERCE,

CONTACTLESS_ICC

Example:

["EMV", "CONTACTLESS_ICC", "ECOMMERCE"]

allowed_payment_methods

enum<string>[]

required

Allowed payment methods (at least one required)

Minimum array length: 1

Available options:

CREDIT_CARD,

DEBIT_CARD,

PIX,

BOLEPIX

Example:

["CREDIT_CARD", "DEBIT_CARD", "PIX"]

settlement_bank_account

object

External bank account for fund settlements. Required for RINNE and CAPPTA providers. Not required for CELCOIN (managed internally).

Show child attributes

anticipation_type

enum<string>

default:AUTOMATIC

Anticipation type for the affiliation. Defaults to AUTOMATIC if not provided.

Available options:

AUTOMATIC,

SPOT

Example:

"AUTOMATIC"

anticipation_days

integer

default:1

Number of days for automatic anticipation. Must be at least 1. Defaults to 1 if not provided.

Required range: x >= 1

Example:

1

Response

Affiliation created successfully

Transformed affiliation data returned by the API

string

required

Example:

"123e4567-e89b-12d3-a456-426614174002"

provider

enum<string>

required

Payment provider name

Available options:

CELCOIN,

RINNE,

CAPPTA

Example:

"CELCOIN"

merchant_id

string

required

Merchant ID in provider

Example:

"12345678"

status

enum<string>

required

Current affiliation status. WAITING_DOCUMENTS means the company has something to complete before the provider can decide; CANCELLED means the attempt was cancelled while waiting (cancellation_reason says why) and is over, so a new affiliation can be created.

Available options:

PENDING,

ACTIVE,

PROCESSING,

BLOCKED,

PENDING_APPROVAL,

WAITING_DOCUMENTS,

PROCESSING_DOCUMENTS,

REJECTED,

FAILED,

INVALID_SETTLEMENT_BANK_ACCOUNT,

CLOSED,

CANCELLED

Example:

"ACTIVE"

enabled

boolean

required

Whether the affiliation is enabled

Example:

true

company_id

string

required

Associated company ID

Example:

"a3dbd0c2-9f79-4f86-8caa-47779b3f2793"

onboarding_url

string | null

required

Link where the company completes what the provider asked for. Returned only while status is WAITING_DOCUMENTS; null in every other status, including after a cancellation.

Example:

"https://provider.com/onboard/12345"

onboarding_url_expires_at

string<date-time> | null

required

When onboarding_url stops working. Null while no expiry applies to the link, and in every status other than WAITING_DOCUMENTS. Always null until the onboarding flow is released.

Example:

"2026-11-06T12:00:00.000Z"

cancellation_reason

enum<string> | null

required

Why the affiliation is CANCELLED, null in every other status. REQUESTED when the company cancelled it; EXPIRED when the deadline to complete the requirements passed.

Available options:

REQUESTED,

EXPIRED,

null

Example:

null

rejection_reviewed_at

string<date-time> | null

required

When the provider's rejection of this attempt was reviewed and translated into the actions the company has to take. Null until then, and on an attempt that was never rejected. Always null until the onboarding flow is released.

Example:

null

allowed_capture_methods

enum<string>[]

required

Allowed capture methods

Available options:

EMV,

MAGSTRIPE,

ECOMMERCE,

CONTACTLESS_ICC

Example:

["ECOMMERCE"]

allowed_payment_methods

enum<string>[]

required

Allowed payment methods

Available options:

CREDIT_CARD,

DEBIT_CARD,

PIX,

BOLEPIX

Example:

["PIX"]

organization_id

string

required

Associated organization ID

Example:

"a3dbd0c2-9f79-4f86-8caa-47779b3f2793"

gateway_mode

boolean

required

Whether this is a gateway-mode affiliation (Rinne acts as a pure capture gateway; no settlement, splits, or ledger entries)

Example:

false

onboarding_documents

object[]

required

List of onboarding documents associated with this affiliation

Show child attributes

created_at

string<date-time>

required

Creation timestamp in ISO 8601 format

Example:

"2023-01-01T12:00:00.000Z"

updated_at

string<date-time>

required

Last update timestamp in ISO 8601 format

Example:

"2023-01-01T12:00:00.000Z"

provider_id

string | null

ID in provider system

Example:

"prov_123456"

soft_descriptor

string | null

Soft descriptor for transactions

Example:

"MYSTORE"

mcc

string

Merchant Category Code

Example:

"5411"

cost_policy_id

string | null

Associated cost policy ID

Example:

"123e4567-e89b-12d3-a456-426614174003"

provider_status_code

string | null

Provider-specific status code

Example:

"200"

provider_status_message

string | null

Provider-specific status message. An onboarding status change that carries no reason keeps the previous text, so it may predate status, except a move into ACTIVE, which clears it; a block, closure or reactivation of the account behind the affiliation replaces it, with an empty string when it carries none.

Example:

"Merchant activated successfully"

provider_metadata

object | null

Provider-specific metadata

Example:

{}

bank_account

object | null

Associated bank account information (created by provider)

Show child attributes

settlement_bank_accounts

object[]

Settlement bank accounts for this affiliation.

Show child attributes

anticipation_type

enum<string>

Anticipation type for the affiliation

Available options:

AUTOMATIC,

SPOT

Example:

"AUTOMATIC"

anticipation_days

integer

Number of days for anticipation

Required range: x >= 1

Example:

1

company_snapshot

object | null

Point-in-time snapshot of company data (with contact) at affiliation creation. Only included when include_company_snapshot=true query parameter is set.

Introduction

Merchants

Pricing

Tap-on-Phone

Webhooks

Organization Management

User Management

System

Create a new affiliation for a specific merchant

Authorizations

Path Parameters

Body

Response