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
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": "joao@example.com",
"document_type": "CPF",
"document_number": "81146431023"
}
}'
{
"id": "tx_123456789",
"status": "WAITING_PAYMENT",
"amount": 10000,
"pix_data": {
"qr_code": "00020126580014br.gov.bcb.pix...",
"expires_at": "2025-01-21T11:00:00Z"
}
}
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 |
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.001050 = R$ 10.5099 = 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
- Partial refunds change status to
PARTIALLY_REFUNDED
- Full refunds change status to
REFUNDED
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 |
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"
}
]
}
- 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
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"
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 methodamount_from / amount_to: Filter by amount rangecreated_at_from / created_at_to: Filter by date rangeprovider: Filter by providersort: Sort by fields (e.g., -created_at,amount)
Store custom data with transactions using the metadata field:
{
"metadata": {
"order_id": "order-123",
"customer_id": "cust-456",
"store_location": "SP-001"
}
}
Next steps
