Rinne API Documentation

Transactions represent payment operations processed through the Rinne platform. Each transaction is linked to a merchant, processed through a provider affiliation, and can support various payment methods.

Transaction basics

A transaction requires:

An active provider affiliation
Transaction amount (in cents)
Payment method (PIX, credit card, etc.)
Capture method (e-commerce, POS, etc.)
Unique request ID for idempotency

Entity relationships

Creating transactions

PIX transaction

Immediate PIX payment

curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/transactions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "CELCOIN",
    "request_id": "unique-request-123",
    "amount": 10000,
    "currency": "BRL",
    "capture_method": "ECOMMERCE",
    "payment_method": "PIX",
    "pix_data": {
      "description": "Payment for order #123",
      "expiration_in_seconds": 3600
    },
    "consumer": {
      "full_name": "João Silva",
      "email": "[email protected]",
      "document_type": "CPF",
      "document_number": "81146431023"
    }
  }'

The response includes a QR code for the customer to scan:

{
    "id": "tx_123456789",
    "status": "WAITING_PAYMENT",
    "amount": 10000,
    "pix_data": {
        "qr_code": "00020126580014br.gov.bcb.pix...",
        "expires_at": "2025-01-21T11:00:00Z"
    }
}

PIX with due date

For invoice payments, you can create PIX transactions with a due date and pricing modifiers:

curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/transactions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "CELCOIN",
    "request_id": "invoice-456",
    "amount": 100000,
    "currency": "BRL",
    "capture_method": "ECOMMERCE",
    "payment_method": "PIX",
    "pix_data": {
      "description": "Invoice payment",
      "due_date": "2025-12-31",
      "expiration_in_days_after_due_date": 30,
      "interest": {
        "percentage": 2.0,
        "modality": "PERCENTAGE_PER_MONTH"
      },
      "fine": {
        "percentage": 5.0,
        "modality": "PERCENTAGE"
      },
      "discount": {
        "modality": "PERCENTAGE_UNTIL_DATE",
        "discount_dates_config": [
          {
            "until_date": "2025-12-15",
            "percentage": 10.0
          }
        ]
      }
    },
    "consumer": {
      "full_name": "Maria Santos",
      "email": "[email protected]",
      "document_type": "CPF",
      "document_number": "12345678901"
    }
  }'

Due date features:

due_date: Expected payment date (YYYY-MM-DD format)
expiration_in_days_after_due_date: Days after due date before expiration (1-365, default: 30)
interest: Applied when paid after due date
fine: One-time charge when paid after due date
discount: Reduces amount when paid early
abatement: Permanent amount reduction

When using due_date, consumer information (full_name, document_number, document_type) is required.

BolePix transaction

BolePix is a hybrid payment method that generates both a boleto (bank slip) and a PIX QR code. Customers can pay using either method.

curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/transactions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "CELCOIN",
    "request_id": "bolepix-order-123",
    "amount": 50000,
    "currency": "BRL",
    "capture_method": "ECOMMERCE",
    "payment_method": "BOLEPIX",
    "bolepix_data": {
      "due_date": "2025-12-31",
      "expiration_in_days_after_due_date": 30,
      "discount": {
        "amount": 5000,
        "modality": "FIXED",
        "until_date": "2025-12-25"
      },
      "fine_percentage": 2.0,
      "monthly_interest_percentage": 1.0
    },
    "consumer": {
      "full_name": "Maria Silva",
      "email": "[email protected]",
      "document_type": "CPF",
      "document_number": "81146431023",
      "address": {
        "country": "076",
        "state": "SP",
        "city": "São Paulo",
        "zipcode": "01310100",
        "street": "Av Paulista",
        "street_number": "1000"
      }
    }
  }'

The response includes both boleto and PIX payment data:

{
    "id": "tx_123456789",
    "status": "WAITING_PAYMENT",
    "amount": 50000,
    "bolepix_data": {
        "due_date": "2025-12-31",
        "bar_code": "00190000090299993600000000000000185830000050000",
        "bank_line": "00190.00009 02999.936001 00000.000001 8 58300000050000",
        "pix_emv": "00020126580014br.gov.bcb.pix..."
    }
}

BolePix requirements

Minimum amount: 500 cents (R$ 5.00)
Maximum amount: 25,000,000 cents (R$ 250,000.00)
Installments: Must be 1 (no installment support)
Consumer: Required with full_name, document_type, document_number, and full address including street_number

BolePix-specific fields

due_date: Payment due date in YYYY-MM-DD format (required, must be after today)
expiration_in_days_after_due_date: Days after due date before expiration (0-59, default: 0)
discount: Optional discount configuration
- amount: Fixed discount amount in cents (for FIXED modality)
- percentage: Discount percentage (for PERCENTAGE modality)
- modality: FIXED or PERCENTAGE
- until_date: Date until which discount applies (must be before or equal to due_date)
fine_percentage: Fine percentage applied after due date (0.01-100%)
monthly_interest_percentage: Monthly interest divided by 30 and applied per day after due date (0.01-100%)

The minimum amount after discount is applied must be at least 500 cents (R$ 5.00).

Card transaction

Card payment functionality is currently being implemented. The card_data field will be available once the full implementation is live.

For credit and debit card transactions, you’ll need to provide card data including either the card number or a network token (for tokenized payments like Apple Pay or Google Pay):

curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/transactions \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "RINNE",
    "request_id": "unique-request-456",
    "amount": 25000,
    "currency": "BRL",
    "capture_method": "ECOMMERCE",
    "installments": 3,
    "payment_method": "CREDIT_CARD",
    "card_data": {
      "network_token": "4111111111111111",
      "cryptogram": "1234567890123456",
      "expiry_month": "12",
      "expiry_year": "2025",
      "authentication_type": "3DS",
      "wallet_type": "APPLE_PAY",
      "display_name": "Visa •••• 1111"
    },
    "consumer": {
      "full_name": "Maria Santos",
      "email": "[email protected]",
      "document_type": "CPF",
      "document_number": "12345678901"
    }
  }'

Card data requirements

The card_data field is required for CREDIT_CARD and DEBIT_CARD payment methods and has the following validation rules:

Either number (card PAN) or network_token must be provided (mutually exclusive)
expiry_month: Two-digit month (01-12)
expiry_year: Four-digit year (YYYY)
cryptogram: Required for 3DS authentication
authentication_type: Currently only 3DS is supported (defaults to 3DS)

Tokenized payments

For digital wallet payments (Apple Pay, Google Pay), use the network_token field instead of the card number:

Set wallet_type to APPLE_PAY or GOOGLE_PAY
Provide the network_token from the wallet provider
Include the cryptogram for secure authentication
Optionally include display_name for user-friendly card identification

Use RinneJS to easily integrate Apple Pay and Google Pay buttons in your web application. The SDK handles wallet authentication and provides encrypted card data ready for transaction processing.

Transaction status

Transactions move through different statuses during their lifecycle:

Status	Description
`PROCESSING`	Transaction is being processed
`WAITING_PAYMENT`	Awaiting customer payment (PIX)
`AUTHORIZED`	Payment authorized but not captured
`APPROVED`	Payment successfully processed
`REFUSED`	Payment declined by provider/acquirer
`EXPIRED`	Payment window expired
`PENDING_REFUND`	Refund is being processed
`REFUNDED`	Fully refunded
`PARTIALLY_REFUNDED`	Partially refunded
`CHARGEDBACK`	Disputed and reversed

Amounts in cents

All monetary values in the API are represented in cents (integer values):

10000 = R$ 100.00
1050 = R$ 10.50
99 = R$ 0.99

Always use integers for amounts. Never use decimal values or floating-point numbers.

Request ID for idempotency

The request_id field ensures idempotent transaction creation. If you retry a request with the same request_id, you’ll receive the existing transaction instead of creating a duplicate.

# First request - creates transaction
POST /v1/transactions
{ "request_id": "order-123", "amount": 10000, ... }
# Response: 201 Created

# Retry with same request_id - returns existing transaction
POST /v1/transactions
{ "request_id": "order-123", "amount": 10000, ... }
# Response: 200 OK (same transaction)

Transaction pricing

Each transaction has associated fees and costs:

{
    "pricing": {
        "fee": {
            "percentage": 3.5,
            "flat": 0,
            "minimum_price": 0
        },
        "cost": {
            "percentage": 0.5,
            "flat": 0,
            "minimum_price": 0
        }
    }
}

Fee: Amount charged to the merchant (your revenue)
Cost: Amount paid to the provider (your cost)

Pricing is calculated using fee and cost policies configured for the merchant.

Refunds

You can refund approved transactions partially or fully:

curl -X POST https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/transactions/TRANSACTION_ID/refunds \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "refund_amount": 5000,
    "refund_reason": "CUSTOMER_REQUEST",
    "description": "Customer requested refund",
    "metadata": {
      "refund_source": "customer_request",
      "ticket_id": "support-123"
    }
  }'

Refund rules

Only APPROVED or PARTIALLY_REFUNDED transactions can be refunded
Refund amount cannot exceed: approved_amount - refunded_amount
When a refund is initiated, the transaction status changes to PENDING_REFUND
Partial refunds change status to PARTIALLY_REFUNDED
Full refunds change status to REFUNDED
Balance is checked before processing refunds to ensure sufficient funds
Only one refund can be in progress at a time per transaction (PENDING, PROCESSING, or TIMEOUT status)

Refund reasons

Reason	Description
`CUSTOMER_REQUEST`	Customer requested refund
`FRAUD`	Fraudulent transaction
`BANKING_ERROR`	Banking system error
`PIX_WITHDRAWAL_OR_CHANGE_ERROR`	PIX withdrawal or change error

Async refund processing

Refunds are processed asynchronously to improve reliability. When you initiate a refund:

A refund record is created with PENDING status
The transaction status changes to PENDING_REFUND
The system attempts to process the refund with the provider
On success, the refund status updates to COMPLETED
On timeout, the refund status updates to TIMEOUT for automatic retry
On other errors, the refund remains PENDING for automatic retry

If the provider call fails due to a transient error (timeout, insufficient balance, etc.), the refund will be automatically retried by background jobs until it succeeds or is manually cancelled.

Cancelling a pending refund

You can cancel a refund that is in PENDING status:

curl -X PATCH https://api-sandbox.rinne.com.br/core/v1/transactions/TRANSACTION_ID/refunds/cancel \
  -H "x-api-key: YOUR_API_KEY"

When a refund is cancelled:

The refund status changes to CANCELLED
The transaction status reverts based on remaining refunds:
- APPROVED if no other completed refunds exist
- PARTIALLY_REFUNDED if other completed refunds exist

Only refunds with PENDING status can be cancelled. Refunds that are PROCESSING, COMPLETED, FAILED, or TIMEOUT cannot be cancelled.

Refund information in transaction response

When you retrieve a transaction with full details, the response includes a refunds array with complete refund information:

{
    "id": "tx_123456789",
    "status": "PARTIALLY_REFUNDED",
    "amount": 10000,
    "refunded_amount": 5000,
    "refunds": [
        {
            "id": "ref_123456789",
            "transaction_id": "tx_123456789",
            "request_id": "req_refund_123",
            "amount": 5000,
            "status": "COMPLETED",
            "reason": "CUSTOMER_REQUEST",
            "description": "Customer requested partial refund",
            "provider_refund_identification": "D13935893202307271346SPpDyb4f123",
            "metadata": {
                "refund_source": "customer_request",
                "ticket_id": "support-123"
            },
            "created_at": "2023-12-01T10:00:00.000Z",
            "updated_at": "2023-12-01T10:00:00.000Z"
        }
    ]
}

Each refund includes:

id: Unique refund identifier
amount: Refund amount in cents
status: Refund status (PENDING, PROCESSING, COMPLETED, FAILED, TIMEOUT, CANCELLED)
reason: Reason for the refund
description: Optional additional description (nullable)
provider_refund_identification: Provider-specific identifier for the refund, such as E2E ID for PIX or ARN for cards (nullable)
metadata: Optional custom key-value pairs for tracking and integration (nullable)
created_at / updated_at: Timestamps

Refund status lifecycle

Status	Description
`PENDING`	Refund created, awaiting processing or retry
`PROCESSING`	Refund is being processed by the provider
`COMPLETED`	Refund successfully processed
`FAILED`	Refund failed permanently
`TIMEOUT`	Provider request timed out, will be retried
`CANCELLED`	Refund was manually cancelled

Automatic refund processing

Rinne automatically monitors and processes refunds through background jobs:

Pending refunds: Processed every 30 minutes. PENDING refunds older than 2 minutes are retried with the provider.
Timeout refunds: Checked every 5 minutes. TIMEOUT refunds are queried at the provider to sync their status. If not found, they revert to PENDING for reprocessing.

This ensures refund statuses stay synchronized with payment providers without manual intervention.

Retrieving transactions

Get a specific transaction

You can retrieve a transaction by ID without specifying the merchant ID:

curl "https://api-sandbox.rinne.com.br/core/v1/merchants/transactions/TRANSACTION_ID" \
  -H "x-api-key: YOUR_API_KEY"

This endpoint returns full transaction details including ledger entries, refunds, and settlement information. The transaction must belong to a merchant within your authenticated organization.

List transactions for a specific merchant

curl "https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/transactions?status=APPROVED&page=1&limit=20" \
  -H "x-api-key: YOUR_API_KEY"

List transactions for all merchants (organization)

curl "https://api-sandbox.rinne.com.br/core/v1/merchants/transactions?created_at_from=2025-01-01T00:00:00Z&created_at_to=2025-01-31T23:59:59Z" \
  -H "x-api-key: YOUR_ORG_API_KEY"

Filtering and sorting

Transactions support extensive filtering:

status: Filter by transaction status (array)
payment_method: Filter by payment method
amount_from / amount_to: Filter by amount range
created_at_from / created_at_to: Filter by date range
provider: Filter by provider
sort: Sort by fields (e.g., -created_at,amount)

Transaction metadata

Store custom data with transactions using the metadata field:

{
    "metadata": {
        "order_id": "order-123",
        "customer_id": "cust-456",
        "store_location": "SP-001"
    }
}

Metadata is returned with the transaction and can be used for reconciliation and reporting.

Transaction receipts

Generate PDF receipts for completed PIX transactions, including both original payments and refunds.

Receipt eligibility

Receipts are available for transactions that meet these requirements:

Status: APPROVED, REFUNDED, or PARTIALLY_REFUNDED
Payment method: PIX only (currently supported)
Payer information: Transaction must have payer data
End-to-end ID: Transaction must have a valid PIX end-to-end identifier

Receipt types

PAYMENT: Receipt for the original transaction payment
REFUND: Receipt for each completed refund with a provider identification

Generating receipts

curl "https://api-sandbox.rinne.com.br/core/v1/transactions/TRANSACTION_ID/receipt" \
  -H "x-api-key: YOUR_API_KEY"

Or for a specific merchant’s transaction:

curl "https://api-sandbox.rinne.com.br/core/v1/merchants/MERCHANT_ID/transactions/TRANSACTION_ID/receipt" \
  -H "x-api-key: YOUR_API_KEY"

Receipt response

The response includes a list of receipts (payment and any refunds):

{
    "receipts": [
        {
            "type": "PAYMENT",
            "transaction_id": "tx_123456789",
            "refund_id": null,
            "amount": 10000,
            "currency": "BRL",
            "identification": "E12345678202501211034567890",
            "created_at": "2025-01-21T10:00:00.000Z",
            "payer": {
                "name": "John Doe",
                "document": "***.456.789-**",
                "bank_name": "BCO SANTANDER (BRASIL) S.A.",
                "ispb": "90400888",
                "branch": "0001",
                "account": "12345678"
            },
            "receiver": {
                "name": "Company Name Ltda",
                "document": "12.345.678/0001-90",
                "bank_name": "BCO DO BRASIL S.A.",
                "ispb": "00000000",
                "branch": "1234",
                "account": "00012345"
            },
            "pdf_file_base64": "JVBERi0xLjQK..."
        },
        {
            "type": "REFUND",
            "transaction_id": "tx_123456789",
            "refund_id": "ref_987654321",
            "amount": 5000,
            "currency": "BRL",
            "identification": "D13935893202601271529YV9B1m6o2Ih",
            "created_at": "2025-01-22T14:30:00.000Z",
            "payer": {
                "name": "Company Name Ltda",
                "document": "12.345.678/0001-90",
                "bank_name": "BCO DO BRASIL S.A.",
                "ispb": "00000000",
                "branch": "1234",
                "account": "00012345"
            },
            "receiver": {
                "name": "John Doe",
                "document": "***.456.789-**",
                "bank_name": "BCO SANTANDER (BRASIL) S.A.",
                "ispb": "90400888",
                "branch": "0001",
                "account": "12345678"
            },
            "pdf_file_base64": "JVBERi0xLjQK..."
        }
    ]
}

Payer/receiver direction

Payment receipts: Payer is the customer, receiver is the merchant
Refund receipts: Payer is the merchant, receiver is the customer (reversed)

CPF documents are masked for privacy (e.g., ***.456.789-**), while CNPJ documents are shown in full.

Next steps

RinneJS SDK

Accept Apple Pay & Google Pay on the web

PIX Payments

Learn how to process PIX transactions

Webhooks

Receive transaction status updates

API Reference

Explore transaction endpoints

Getting started

Core concepts

Guides

​Transaction basics

​Entity relationships

​Creating transactions

​PIX transaction

​Immediate PIX payment

​PIX with due date

​BolePix transaction

​BolePix requirements

​BolePix-specific fields

​Card transaction

​Card data requirements

​Tokenized payments

​Transaction status

​Amounts in cents

​Request ID for idempotency

​Transaction pricing

​Refunds

​Refund rules

​Refund reasons

​Async refund processing

​Cancelling a pending refund

​Refund information in transaction response

​Refund status lifecycle

​Automatic refund processing

​Retrieving transactions

​Get a specific transaction

​List transactions for a specific merchant

​List transactions for all merchants (organization)

​Filtering and sorting

​Transaction metadata

​Transaction receipts

​Receipt eligibility

​Receipt types

​Generating receipts

​Receipt response

​Payer/receiver direction

​Next steps

RinneJS SDK

PIX Payments

Webhooks

API Reference

Transaction basics

Entity relationships

Creating transactions

PIX transaction

Immediate PIX payment

PIX with due date

BolePix transaction

BolePix requirements

BolePix-specific fields

Card transaction

Card data requirements

Tokenized payments

Transaction status

Amounts in cents

Request ID for idempotency

Transaction pricing

Refunds

Refund rules

Refund reasons

Async refund processing

Cancelling a pending refund

Refund information in transaction response

Refund status lifecycle

Automatic refund processing

Retrieving transactions

Get a specific transaction

List transactions for a specific merchant

List transactions for all merchants (organization)

Filtering and sorting

Transaction metadata

Transaction receipts

Receipt eligibility

Receipt types

Generating receipts

Receipt response

Payer/receiver direction

Next steps