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. Sending provider is optional. See Provider selection.
Transaction amount (in cents)
Payment method (PIX, credit card, etc.)
Capture method (e-commerce, POS, etc.)
Unique request ID for idempotency

Entity relationships

Provider selection

provider is optional when you create a transaction. If you omit it, Rinne picks the provider from the merchant’s affiliations. You can then move traffic between providers, or add a new one, without changing or redeploying your integration.

Omit provider

Rinne picks a provider the merchant can use for this payment_method and capture_method. Use this by default.

Send provider

Rinne uses that provider’s affiliation and ignores routing defaults. Use this to pin a transaction to a specific provider.

This applies to both creation endpoints: POST /v1/transactions and POST /v1/merchants/{merchantId}/transactions. The transaction response always includes the provider that processed it.

How Rinne picks the provider

When a request omits provider, Rinne resolves it as follows:

Find eligible affiliations

Rinne considers the merchant’s ACTIVE affiliations that allow the requested payment_method and capture_method. For PIX and BOLEPIX, the affiliation also needs a bank account.

Use the only match

If exactly one affiliation is eligible, Rinne uses it. Most merchants have one affiliation per payment method and need no configuration.

Apply routing defaults

If several affiliations are eligible, Rinne applies the routing defaults configured for the merchant, then its organization, then Rinne-wide. A default for the exact capture method comes before one that covers any capture method.

Take the first eligible provider

Each default lists providers in order of preference, most preferred first. Rinne selects the first listed provider the merchant has an eligible affiliation with. It skips providers the merchant can’t use.

Rinne configures routing defaults for you. Contact Rinne to set or change the default provider for your organization or a merchant.

Routing defaults are not failover. If the selected provider refuses the transaction or fails, Rinne doesn’t retry it on the next provider in the list.

Errors when provider is omitted

400: provider is required

The merchant can process this payment and capture method on more than one provider, and no routing default selects one. Rinne never guesses. Send provider explicitly, or ask Rinne to configure a default.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "provider is required: this company can process CREDIT_CARD with capture method ECOMMERCE on more than one provider",
    "status": 400,
    "details": {
      "issues": [
        {
          "field": "provider",
          "type": "REQUIRED",
          "message": "provider is required: this company can process CREDIT_CARD with capture method ECOMMERCE on more than one provider"
        }
      ]
    }
  }
}

400: no affiliation can process the payment method

The merchant has active affiliations, but none of them allows the requested payment_method and capture_method. The issue is reported on payment_method.

404: affiliation not found

The merchant has no active affiliation. Create one and wait for it to become ACTIVE. See Affiliations.

Rinne resolves the affiliation before it reads a stored card. A request whose provider has no active affiliation and whose card_data.card_id is invalid returns the affiliation 404, not the card 400.

Creating transactions

PIX transaction

PIX guidelines

Installments: Must be 1 for PIX (defaults to 1 if not sent).
When pix_data.due_date is provided: consumer is required with full_name, document_number, and document_type. Use expiration_in_days_after_due_date; do not send expiration_in_seconds.
When pix_data.due_date is not provided: Use expiration_in_seconds; do not send expiration_in_days_after_due_date.

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: 1,500,000,000 cents (R$ 15,000,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 today or later)
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

Use Card transactions, Wallet transactions, and 3D Secure authentication for production-ready implementation details.

For credit and debit card transactions, you’ll need to provide card data with one of three credentials: the card number, a network token (for tokenized payments like Apple Pay or Google Pay), or a card_id that references a card stored on file. The card number and network token are accepted only in encrypted form — these values must come from the rinne-js secure components, which encrypt them so raw card data never touches your systems and you avoid PCI scope issues. For example, a tokenized wallet transaction:

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": "CAPPTA",
    "request_id": "unique-request-456",
    "amount": 25000,
    "currency": "BRL",
    "capture_method": "ECOMMERCE",
    "installments": 3,
    "payment_method": "CREDIT_CARD",
    "soft_descriptor": "ORDER-456",
    "card_data": {
      "network_token": "ev:encrypted:network_token",
      "cryptogram": "ev:encrypted:cryptogram",
      "expiry_month": "12",
      "expiry_year": "2025",
      "cardholder_name": "Maria Santos",
      "last_digits": "1111",
      "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:

Exactly one of number (card PAN), network_token, or card_id (a card stored on file) must be provided — they are mutually exclusive
number, cvv, network_token, and cryptogram must arrive encrypted from rinne-js; plaintext values are rejected with 400 VALIDATION_ERROR
With card_id, the stored card supplies the number, expiry, last_digits, brand, and cardholder_name; sending any of those alongside card_id is rejected with 400 VALIDATION_ERROR
With number or network_token, send these fields inline:
- expiry_month: Two-digit month (01-12)
- expiry_year: Four-digit year (YYYY)
- cardholder_name: Name of the cardholder as it appears on the card
- last_digits: Last 4 digits of the card number (exactly 4 digits)
cryptogram: Required for authenticated/tokenized 3DS flows (directly or injected from three_d_secure_session_id)
authentication_type: Currently only 3DS is supported

Card statement descriptor

Card transactions accept an optional soft_descriptor at the top level of the request, next to amount rather than inside card_data, as in the example above. It carries your text, such as an order number, which Rinne prints on the cardholder’s statement after the merchant’s name. Rinne folds accented letters to their base letter, uppercases the text, removes spaces and unsupported characters, and keeps the first 9 characters. When you omit the field, or the kept characters hold no letter or digit, the line ends at the merchant’s name. See Card statement descriptor for how Rinne composes the full line.

3DS challenge strategy flags

Card transaction creation supports two optional flags:

require_3ds: Forces immediate AWAITING_3DS status and defers provider authorization until /authenticate is called with an authenticated 3DS session.
refuse_on_challenge: Refuses challenge-triggered paths immediately (REFUSED) instead of moving to AWAITING_3DS.

These flags let you tune 3DS policy without changing your entire checkout architecture:

Use require_3ds to enforce 3DS while staying in a pure transaction-first flow (no separate session-first policy path required).
Use refuse_on_challenge to fail fast when you intentionally do not support challenge handling for a merchant or transaction segment.

When refuse_on_challenge blocks a challenge-triggered path, the transaction uses:

status: REFUSED
status_reason: CHALLENGE_NOT_ALLOWED

When refuse_on_challenge is enabled, non-challenge transactions still follow normal provider processing.

require_3ds and refuse_on_challenge cannot both be true in the same transaction request.

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 rinne-js 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)
`AWAITING_3DS`	Paused until your integration runs 3DS authentication and calls `/authenticate`
`AUTHORIZED`	Payment authorized but not captured
`APPROVED`	Payment successfully processed
`REFUSED`	Payment declined by provider/acquirer for a business reason
`FAILED`	Provider HTTP call errored (4xx/5xx, timeout, network error)
`EXPIRED`	Payment window expired
`PENDING_REFUND`	Refund is being processed
`REFUNDED`	Fully refunded
`PARTIALLY_REFUNDED`	Partially refunded
`CHARGEDBACK`	Disputed and reversed
`PENDING_CANCELLATION`	Cancellation in progress (BOLEPIX only)
`CANCELLED`	Transaction cancelled before payment (BOLEPIX only)

REFUSED vs FAILED: REFUSED means the provider explicitly declined the transaction for a business reason (e.g., insufficient funds, invalid card). FAILED means the HTTP call to the provider errored (4xx/5xx, timeout, network failure). Both are terminal states.

For REFUSED outcomes, status_reason can include values such as PROVIDER, ACQUIRER, ANTIFRAUD, NO_ACQUIRER, ACQUIRER_TIMEOUT, and CHALLENGE_NOT_ALLOWED.

Cancelling BOLEPIX transactions

You can cancel BOLEPIX transactions that are in WAITING_PAYMENT status before the customer pays:

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

Or for a specific merchant’s transaction:

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

Cancellation behavior

When you cancel a BOLEPIX transaction:

The transaction status changes to PENDING_CANCELLATION
A cancellation request is sent to the provider
If successful, the status changes to CANCELLED
If the provider times out, the status remains PENDING_CANCELLATION

Non-terminal cancellation: The cancellation may be non-terminal. If the provider times out, the transaction remains in PENDING_CANCELLATION. Final reconciliation to CANCELLED is performed asynchronously when the provider sends the bolepix.cancelled webhook. Poll the transaction or subscribe to the transaction.status-changed webhook rather than assuming immediate finality.

Cancellation requirements

Payment method: Only BOLEPIX transactions can be cancelled
Status: Transaction must be in WAITING_PAYMENT status
Permissions: Requires transaction.cancel or merchant.transaction.cancel permission

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.

Minimum amount validation

Transaction amounts must be greater than the calculated fee. When creating a transaction, the system validates that the amount covers the fee based on the merchant’s fee policy. If the amount is insufficient, the API returns a validation error:

{
    "error": {
        "code": "VALIDATION_ERROR",
        "message": "Validation error",
        "status": 400,
        "details": {
            "issues": [
                {
                    "field": "amount",
                    "type": "OUT_OF_RANGE",
                    "value": 100,
                    "constraints": {
                        "minimumAmount": 351,
                        "calculatedFee": 350
                    }
                }
            ]
        }
    }
}

The constraints object provides:

minimumAmount: The minimum amount required for the transaction (calculated fee + 1 cent)
calculatedFee: The total fee that would be charged for this transaction

To avoid this error, ensure your transaction amount is strictly greater than the calculated fee. You can use the fee policy details to estimate fees before creating transactions.

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)

Automatic anticipation

Each transaction includes an automatic_anticipation boolean field, set at creation time based on the affiliation’s anticipation_type. When the affiliation uses AUTOMATIC anticipation, this field is true; otherwise it is false. The value is immutable after creation. This field can be used as a condition in pricing rules to apply different fee rates depending on whether a transaction is automatically anticipated.

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 PIX, credit card, and debit card transactions partially or fully through the same endpoint. The request body is identical regardless of payment method:

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"
    }
  }'

Supported payment methods

Payment method	Refund support
`PIX`	Full and partial; multiple refunds allowed up to the remaining refundable amount
`CREDIT_CARD` / `DEBIT_CARD`	One successful refund per transaction. Full any day; partial only from D+1 onward (see warnings below)
`BOLEPIX`	Not supported

Refund rules

BOLEPIX transactions do not support refunds.
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 the transaction status to PARTIALLY_REFUNDED; full refunds change it to REFUNDED.
Only one refund can be in progress at a time per transaction (PENDING, PROCESSING, or TIMEOUT status).
Card transactions accept only one successful refund. Once a CREDIT_CARD or DEBIT_CARD transaction has any COMPLETED refund, it is treated as terminally refunded and any further refund request is rejected synchronously with HTTP 400. PIX transactions are not subject to this rule.
Balance is checked before processing refunds to ensure sufficient funds.

Card transactions accept only one successful refund. Once a CREDIT_CARD or DEBIT_CARD transaction has a refund in COMPLETED status, any additional refund request — partial or full — is rejected synchronously with HTTP 400. Plan the refund amount up front: if you need to refund a card transaction in pieces, the first successful refund must cover the full remaining amount you intend to return.Prior refunds in FAILED or CANCELLED status do not count toward this rule, so you can submit a new refund after a failed attempt.

Same-day partial refunds are not allowed for card transactions. When the refund request lands on the same calendar day as the transaction’s approved_at (D0), only a refund for the full remaining refundable amount is accepted. Partial refunds are allowed only from the next calendar day (D+1) onward.Same-day partial requests fail synchronously with HTTP 400. On D0 you can still issue a full refund, and on D+1 (or later) any partial amount up to the remaining refundable balance is accepted. See Refunding card transactions for an example.

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

The refund response always includes the current refund status. How that status is determined depends on the payment method.

PIX refunds

PIX refunds are processed asynchronously to improve reliability:

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 and is queried again later.
On other transient errors, the refund stays PENDING for automatic retry.

For PIX, transient provider errors (timeout, insufficient balance, etc.) cause the refund to be automatically retried until it succeeds or is manually cancelled.

Card refunds

Card refunds resolve as far as possible on the same API call:

A definitive provider response (success or rejection) returns synchronously with the refund already in its terminal state — COMPLETED for a successful cancel, FAILED for a definitive rejection (for example, an acquirer business decline). FAILED card refunds are terminal and not retried; submit a new refund request to try again.
An uncertain outcome (acquirer 5xx or network timeout) triggers an inline status query against the acquirer. If that query resolves the outcome, you still get COMPLETED or FAILED on the same call. Otherwise the refund moves to TIMEOUT and is reconciled asynchronously.
A PENDING_REFUND response on a card transaction means the request reached us but did not produce a definitive answer; we will retry the (idempotent) cancel.

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

This list covers your merchants’ transactions. Transactions your organization creates for itself are listed by GET /v1/transactions.

List transactions for a specific merchant

To list one merchant’s transactions, pass the merchant’s ID as company_id on the organization-wide list:

curl "https://api-sandbox.rinne.com.br/core/v1/merchants/transactions?company_id=ae0b1a57-fba6-40d7-94e9-09a155f9f1a0&status=APPROVED&page=1&limit=20" \
  -H "x-api-key: YOUR_ORG_API_KEY"

Every transaction in data has company_id set to the merchant you asked for. company_id only matches merchants in your organization. If it holds any other ID, such as a merchant in another organization or your organization’s own ID, the request returns 200 with an empty page:

{
    "data": [],
    "pagination": {
        "page": 1,
        "limit": 20,
        "total": 0,
        "totalPages": 0,
        "hasNext": false,
        "hasPrev": false
    }
}

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
company_id: Filter by merchant ID (organization-wide list only)
sort: Sort by fields (e.g., -created_at,amount)

For every filter each list accepts, see Get transactions for all merchants and Get transactions.

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

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

​Transaction basics

​Entity relationships

​Provider selection

Omit provider

Send provider

​How Rinne picks the provider

​Errors when provider is omitted

​Creating transactions

​PIX transaction

​PIX guidelines

​Immediate PIX payment

​PIX with due date

​BolePix transaction

​BolePix requirements

​BolePix-specific fields

​Card transaction

​Card data requirements

​Card statement descriptor

​3DS challenge strategy flags

​Tokenized payments

​Transaction status

​Cancelling BOLEPIX transactions

​Cancellation behavior

​Cancellation requirements

​Amounts in cents

​Minimum amount validation

​Request ID for idempotency

​Automatic anticipation

​Transaction pricing

​Refunds

​Supported payment methods

​Refund rules

​Refund reasons

​Refund processing semantics

​PIX refunds

​Card refunds

​Cancelling a pending refund

​Refund information in transaction response

​Refund status lifecycle

​Automatic refund processing

​Retrieving transactions

​Get a specific transaction

​List transactions for all merchants (organization)

​List transactions for a specific merchant

​Filtering and sorting

​Transaction metadata

​Transaction receipts

​Receipt eligibility

​Receipt types

​Generating receipts

​Receipt response

​Payer/receiver direction

​Next steps

rinne-js SDK

PIX Payments

Webhooks

API Reference

Transaction basics

Entity relationships

Provider selection

How Rinne picks the provider

Errors when provider is omitted

Creating transactions

PIX transaction

PIX guidelines

Immediate PIX payment

PIX with due date

BolePix transaction

BolePix requirements

BolePix-specific fields

Card transaction

Card data requirements

Card statement descriptor

3DS challenge strategy flags

Tokenized payments

Transaction status

Cancelling BOLEPIX transactions

Cancellation behavior

Cancellation requirements

Amounts in cents

Minimum amount validation

Request ID for idempotency

Automatic anticipation

Transaction pricing

Refunds

Supported payment methods

Refund rules

Refund reasons

Refund processing semantics

PIX refunds

Card refunds

Cancelling a pending refund

Refund information in transaction response

Refund status lifecycle

Automatic refund processing

Retrieving transactions

Get a specific transaction

List transactions for all merchants (organization)

List transactions for a specific merchant

Filtering and sorting

Transaction metadata

Transaction receipts

Receipt eligibility

Receipt types

Generating receipts

Receipt response

Payer/receiver direction

Next steps