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.

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/refund \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "refund_amount": 5000,
    "refund_reason": "CUSTOMER_REQUEST",
    "description": "Customer requested refund"
  }'

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 pending at a time per transaction

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

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",
      "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)
reason: Reason for the refund
description: Optional additional description (nullable)
created_at / updated_at: Timestamps

Refund status handling

When a refund fails, the transaction status is automatically adjusted:

If the failed refund was the only refund attempt, the transaction returns to APPROVED

This ensures that transaction status accurately reflects the actual refund state, even when refund operations fail.

Refund status tracking

Rinne automatically monitors pending refunds and updates their status:

Status is automatically updated based on the provider’s response
If a refund is not found at the provider, it’s marked as FAILED

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.

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

Transactions

Transaction basics

Entity relationships

Creating transactions

PIX transaction

Immediate PIX payment

PIX with due date

Card transaction

Card data requirements

Tokenized payments

Transaction status

Amounts in cents

Request ID for idempotency

Transaction pricing

Refunds

Refund rules

Refund reasons

Refund information in transaction response

Refund status handling

Refund status tracking

Retrieving transactions

Get a specific transaction

List transactions for a specific merchant

List transactions for all merchants (organization)

Filtering and sorting

Transaction metadata

Next steps

RinneJS SDK

PIX Payments

Webhooks

API Reference

Getting started

Core concepts

Guides

​Transaction basics

​Entity relationships

​Creating transactions

​PIX transaction

​Immediate PIX payment

​PIX with due date

​Card transaction

​Card data requirements

​Tokenized payments

​Transaction status

​Amounts in cents

​Request ID for idempotency

​Transaction pricing

​Refunds

​Refund rules

​Refund reasons

​Refund information in transaction response

​Refund status handling

​Refund status tracking

​Retrieving transactions

​Get a specific transaction

​List transactions for a specific merchant

​List transactions for all merchants (organization)

​Filtering and sorting

​Transaction metadata

​Next steps

RinneJS SDK

PIX Payments

Webhooks

API Reference

Transaction basics

Entity relationships

Creating transactions

PIX transaction

Immediate PIX payment

PIX with due date

Card transaction

Card data requirements

Tokenized payments

Transaction status

Amounts in cents

Request ID for idempotency

Transaction pricing

Refunds

Refund rules

Refund reasons

Refund information in transaction response

Refund status handling

Refund status tracking

Retrieving transactions

Get a specific transaction

List transactions for a specific merchant

List transactions for all merchants (organization)

Filtering and sorting

Transaction metadata

Next steps