Refund a transaction for a specific merchant

curl --request POST \
  --url https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/transactions/{transactionId}/refunds \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "refund_reason": "CUSTOMER_REQUEST",
  "refund_amount": 1000,
  "description": "Refund due to customer dissatisfaction",
  "metadata": {
    "custom_field": "value",
    "refund_source": "customer_request"
  }
}
'

import requests

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

payload = {
    "refund_reason": "CUSTOMER_REQUEST",
    "refund_amount": 1000,
    "description": "Refund due to customer dissatisfaction",
    "metadata": {
        "custom_field": "value",
        "refund_source": "customer_request"
    }
}
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({
    refund_reason: 'CUSTOMER_REQUEST',
    refund_amount: 1000,
    description: 'Refund due to customer dissatisfaction',
    metadata: {custom_field: 'value', refund_source: 'customer_request'}
  })
};

fetch('https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/transactions/{transactionId}/refunds', 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}/transactions/{transactionId}/refunds",
  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([
    'refund_reason' => 'CUSTOMER_REQUEST',
    'refund_amount' => 1000,
    'description' => 'Refund due to customer dissatisfaction',
    'metadata' => [
        'custom_field' => 'value',
        'refund_source' => 'customer_request'
    ]
  ]),
  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}/transactions/{transactionId}/refunds"

	payload := strings.NewReader("{\n  \"refund_reason\": \"CUSTOMER_REQUEST\",\n  \"refund_amount\": 1000,\n  \"description\": \"Refund due to customer dissatisfaction\",\n  \"metadata\": {\n    \"custom_field\": \"value\",\n    \"refund_source\": \"customer_request\"\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}/transactions/{transactionId}/refunds")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"refund_reason\": \"CUSTOMER_REQUEST\",\n  \"refund_amount\": 1000,\n  \"description\": \"Refund due to customer dissatisfaction\",\n  \"metadata\": {\n    \"custom_field\": \"value\",\n    \"refund_source\": \"customer_request\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"refund_reason\": \"CUSTOMER_REQUEST\",\n  \"refund_amount\": 1000,\n  \"description\": \"Refund due to customer dissatisfaction\",\n  \"metadata\": {\n    \"custom_field\": \"value\",\n    \"refund_source\": \"customer_request\"\n  }\n}"

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

{
  "id": "tx_123456789",
  "provider": "CELCOIN",
  "affiliation_id": "a3dbd0c2-9f79-4f86-8caa-47779b3f2793",
  "request_id": "request-123",
  "mcc": "5411",
  "amount": 10050,
  "currency": "BRL",
  "pricing": {
    "fee": {
      "percentage": 2.5,
      "flat": 50,
      "minimum_price": 100
    },
    "cost": {
      "percentage": 2.5,
      "flat": 50,
      "minimum_price": 100
    }
  },
  "status": "APPROVED",
  "capture_method": "EMV",
  "installments": 1,
  "payment_method": "PIX",
  "automatic_anticipation": false,
  "origin": "INTERNAL",
  "company_id": "a3dbd0c2-9f79-4f86-8caa-47779b3f2793",
  "created_at": "2023-12-01T10:00:00.000Z",
  "fee_policy_id": "fee_policy_123",
  "cost_policy_id": "cost_policy_123",
  "approved_amount": 10050,
  "refunded_amount": 0,
  "three_d_secure_session_id": "550e8400-e29b-41d4-a716-446655440000",
  "acquirer_response_code": "00",
  "pix_data": {
    "pix_key_id": "pix_key_123",
    "description": "Payment for order #123",
    "qr_code": "00020126580014br.gov.bcb.pix0136a3dbd0c2-9f79-4f86-8caa-47779b3f2793520400005303986540510.005802BR5913Test Company6008São Paulo62070503***6304E2CA",
    "expires_at": "2023-12-02T10:00:00.000Z",
    "identification": "order_123",
    "expiration_in_seconds": 86400,
    "end_to_end_id": "E12345678202312101234567890123456",
    "pix_payment_id": "27bff30a-3470-4e8e-a4f5-a16cf25be0e3",
    "due_date": "2025-12-31",
    "expiration_in_days_after_due_date": 30,
    "interest": {
      "modality": "PERCENTAGE_PER_MONTH",
      "amount": 1000,
      "percentage": 10.5
    },
    "fine": {
      "modality": "PERCENTAGE",
      "amount": 2000,
      "percentage": 2.5
    },
    "discount": {
      "modality": "PERCENTAGE_UNTIL_DATE",
      "amount": 2,
      "percentage": 50,
      "discount_dates_config": [
        {
          "until_date": "2025-12-15",
          "percentage": 10
        },
        {
          "until_date": "2025-12-20",
          "percentage": 5
        }
      ]
    },
    "abatement": {
      "modality": "FIXED",
      "amount": 5000,
      "percentage": 5
    }
  },
  "bolepix_data": {
    "pix_key_id": "pix_key_123",
    "external_request_id": "ext-req-123",
    "due_date": "2025-12-31",
    "expiration_in_days_after_due_date": 30,
    "boleto_transaction_id": "boleto-123",
    "bank_issuer": "Banco do Brasil",
    "bank_code": "001",
    "bank_branch": "1234",
    "bank_account_number": "12345-6",
    "bar_code": "00190000090299993600000000000000185830000010000",
    "bank_line": "00190.00009 02999.936001 00000.000001 8 58300000010000",
    "bank_assignor": "Company Name",
    "pix_transaction_id": "pix-123",
    "pix_identification": "txid123456789",
    "pix_emv": "00020126580014br.gov.bcb.pix...",
    "paid_via": "PIX",
    "paid_amount": 50000,
    "paid_at": "2025-12-20T10:00:00.000Z",
    "discount": {
      "amount": 5000,
      "percentage": 10,
      "modality": "FIXED",
      "until_date": "2025-12-25"
    },
    "fine_percentage": 2,
    "monthly_interest_percentage": 1
  },
  "card_data": {
    "last_digits": "1111",
    "expiry_month": "12",
    "expiry_year": "2028",
    "brand": "VISA",
    "device_id": "device-123",
    "cardholder_name": "John Doe",
    "country": "BR",
    "wallet_type": "APPLE_PAY",
    "display_name": "Visa •••• 1111",
    "authentication_type": "3DS"
  },
  "soft_descriptor": "MYSTORE",
  "serial_number": "12345678",
  "nsu": "000123",
  "metadata": "<unknown>",
  "latest_refund_at": "2023-12-01T10:00:00.000Z",
  "status_reason": "PROVIDER",
  "approved_at": "2023-12-01T10:00:00.000Z",
  "company_full_name": "Test Company",
  "company_name": "Test Company",
  "organization_id": "tx_organization_123456",
  "consumer": {
    "document_type": "CPF",
    "full_name": "João Silva",
    "email": "[email protected]",
    "pix_key": "[email protected]",
    "document_number": "81146431023",
    "phone": "+5511999999999",
    "birth_date": "15-08-1990",
    "address": {
      "street": "Rua das Flores",
      "neighborhood": "Centro",
      "zipcode": "12345678",
      "country": "076",
      "state": "SP",
      "city": "São Paulo",
      "street_number": "123",
      "complement": "Apt 101"
    }
  },
  "updated_at": "2023-12-01T10:00:00.000Z"
}

{
  "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": "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": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred",
    "status": 500,
    "path": "/companies",
    "timestamp": "2023-12-01T10:00:00.000Z",
    "requestId": "req_123456789"
  }
}

Transactions

Refund a transaction for a specific merchant

Requires the merchant.transaction.refund permission.

Refunds a transaction for a merchant that belongs to the authenticated organization.

Important Notes:

Only APPROVED or PARTIALLY_REFUNDED transactions can be refunded
BOLEPIX transactions do not support refunds
Refund amount cannot exceed the approved amount minus already refunded amount
refund_amount is optional. When omitted, it resolves to the transaction’s original approved amount. Because the resolved amount must still satisfy the exceeds-approved guard, omission only succeeds on a transaction with no prior COMPLETED, PENDING, PROCESSING, or TIMEOUT refunds; FAILED and CANCELLED priors are ignored. To refund only the remainder of a partially refunded transaction, send refund_amount explicitly.
Partial refunds are supported for providers that allow them (transaction status becomes PARTIALLY_REFUNDED); providers that only accept full cancellations (e.g. Cappta) reject partial refund requests with a 400 — omit refund_amount or submit the full approved amount instead.
Card refunds on providers that cannot refund post-settlement (e.g. Cappta) are rejected with a 400 once the pre-settlement cancellation window has closed. The cutoff depends on payment method and anticipation: DEBIT_CARD and anticipated CREDIT_CARD settle on the next business day after approval, while non-anticipated CREDIT_CARD settles ~29 calendar days later (then the next business day), so its refund window stays open much longer. The window closes at 23:59 (America/Sao_Paulo) the night before that settlement day. The error message is “This transaction can no longer be refunded because settlement is already in progress.” Refunds across a weekend/holiday remain allowed until that boundary.
Full refunds change status to REFUNDED
Transaction may return with PENDING_REFUND status if the provider call fails for a transient reason (e.g., timeout, insufficient balance). The refund will be retried indefinitely by background jobs until manually cancelled.

POST

merchants

{merchantId}

transactions

{transactionId}

refunds

Refund a transaction for a specific merchant

curl --request POST \
  --url https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/transactions/{transactionId}/refunds \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "refund_reason": "CUSTOMER_REQUEST",
  "refund_amount": 1000,
  "description": "Refund due to customer dissatisfaction",
  "metadata": {
    "custom_field": "value",
    "refund_source": "customer_request"
  }
}
'

import requests

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

payload = {
    "refund_reason": "CUSTOMER_REQUEST",
    "refund_amount": 1000,
    "description": "Refund due to customer dissatisfaction",
    "metadata": {
        "custom_field": "value",
        "refund_source": "customer_request"
    }
}
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({
    refund_reason: 'CUSTOMER_REQUEST',
    refund_amount: 1000,
    description: 'Refund due to customer dissatisfaction',
    metadata: {custom_field: 'value', refund_source: 'customer_request'}
  })
};

fetch('https://api-sandbox.rinne.com.br/core/v1/merchants/{merchantId}/transactions/{transactionId}/refunds', 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}/transactions/{transactionId}/refunds",
  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([
    'refund_reason' => 'CUSTOMER_REQUEST',
    'refund_amount' => 1000,
    'description' => 'Refund due to customer dissatisfaction',
    'metadata' => [
        'custom_field' => 'value',
        'refund_source' => 'customer_request'
    ]
  ]),
  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}/transactions/{transactionId}/refunds"

	payload := strings.NewReader("{\n  \"refund_reason\": \"CUSTOMER_REQUEST\",\n  \"refund_amount\": 1000,\n  \"description\": \"Refund due to customer dissatisfaction\",\n  \"metadata\": {\n    \"custom_field\": \"value\",\n    \"refund_source\": \"customer_request\"\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}/transactions/{transactionId}/refunds")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"refund_reason\": \"CUSTOMER_REQUEST\",\n  \"refund_amount\": 1000,\n  \"description\": \"Refund due to customer dissatisfaction\",\n  \"metadata\": {\n    \"custom_field\": \"value\",\n    \"refund_source\": \"customer_request\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"refund_reason\": \"CUSTOMER_REQUEST\",\n  \"refund_amount\": 1000,\n  \"description\": \"Refund due to customer dissatisfaction\",\n  \"metadata\": {\n    \"custom_field\": \"value\",\n    \"refund_source\": \"customer_request\"\n  }\n}"

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

{
  "id": "tx_123456789",
  "provider": "CELCOIN",
  "affiliation_id": "a3dbd0c2-9f79-4f86-8caa-47779b3f2793",
  "request_id": "request-123",
  "mcc": "5411",
  "amount": 10050,
  "currency": "BRL",
  "pricing": {
    "fee": {
      "percentage": 2.5,
      "flat": 50,
      "minimum_price": 100
    },
    "cost": {
      "percentage": 2.5,
      "flat": 50,
      "minimum_price": 100
    }
  },
  "status": "APPROVED",
  "capture_method": "EMV",
  "installments": 1,
  "payment_method": "PIX",
  "automatic_anticipation": false,
  "origin": "INTERNAL",
  "company_id": "a3dbd0c2-9f79-4f86-8caa-47779b3f2793",
  "created_at": "2023-12-01T10:00:00.000Z",
  "fee_policy_id": "fee_policy_123",
  "cost_policy_id": "cost_policy_123",
  "approved_amount": 10050,
  "refunded_amount": 0,
  "three_d_secure_session_id": "550e8400-e29b-41d4-a716-446655440000",
  "acquirer_response_code": "00",
  "pix_data": {
    "pix_key_id": "pix_key_123",
    "description": "Payment for order #123",
    "qr_code": "00020126580014br.gov.bcb.pix0136a3dbd0c2-9f79-4f86-8caa-47779b3f2793520400005303986540510.005802BR5913Test Company6008São Paulo62070503***6304E2CA",
    "expires_at": "2023-12-02T10:00:00.000Z",
    "identification": "order_123",
    "expiration_in_seconds": 86400,
    "end_to_end_id": "E12345678202312101234567890123456",
    "pix_payment_id": "27bff30a-3470-4e8e-a4f5-a16cf25be0e3",
    "due_date": "2025-12-31",
    "expiration_in_days_after_due_date": 30,
    "interest": {
      "modality": "PERCENTAGE_PER_MONTH",
      "amount": 1000,
      "percentage": 10.5
    },
    "fine": {
      "modality": "PERCENTAGE",
      "amount": 2000,
      "percentage": 2.5
    },
    "discount": {
      "modality": "PERCENTAGE_UNTIL_DATE",
      "amount": 2,
      "percentage": 50,
      "discount_dates_config": [
        {
          "until_date": "2025-12-15",
          "percentage": 10
        },
        {
          "until_date": "2025-12-20",
          "percentage": 5
        }
      ]
    },
    "abatement": {
      "modality": "FIXED",
      "amount": 5000,
      "percentage": 5
    }
  },
  "bolepix_data": {
    "pix_key_id": "pix_key_123",
    "external_request_id": "ext-req-123",
    "due_date": "2025-12-31",
    "expiration_in_days_after_due_date": 30,
    "boleto_transaction_id": "boleto-123",
    "bank_issuer": "Banco do Brasil",
    "bank_code": "001",
    "bank_branch": "1234",
    "bank_account_number": "12345-6",
    "bar_code": "00190000090299993600000000000000185830000010000",
    "bank_line": "00190.00009 02999.936001 00000.000001 8 58300000010000",
    "bank_assignor": "Company Name",
    "pix_transaction_id": "pix-123",
    "pix_identification": "txid123456789",
    "pix_emv": "00020126580014br.gov.bcb.pix...",
    "paid_via": "PIX",
    "paid_amount": 50000,
    "paid_at": "2025-12-20T10:00:00.000Z",
    "discount": {
      "amount": 5000,
      "percentage": 10,
      "modality": "FIXED",
      "until_date": "2025-12-25"
    },
    "fine_percentage": 2,
    "monthly_interest_percentage": 1
  },
  "card_data": {
    "last_digits": "1111",
    "expiry_month": "12",
    "expiry_year": "2028",
    "brand": "VISA",
    "device_id": "device-123",
    "cardholder_name": "John Doe",
    "country": "BR",
    "wallet_type": "APPLE_PAY",
    "display_name": "Visa •••• 1111",
    "authentication_type": "3DS"
  },
  "soft_descriptor": "MYSTORE",
  "serial_number": "12345678",
  "nsu": "000123",
  "metadata": "<unknown>",
  "latest_refund_at": "2023-12-01T10:00:00.000Z",
  "status_reason": "PROVIDER",
  "approved_at": "2023-12-01T10:00:00.000Z",
  "company_full_name": "Test Company",
  "company_name": "Test Company",
  "organization_id": "tx_organization_123456",
  "consumer": {
    "document_type": "CPF",
    "full_name": "João Silva",
    "email": "[email protected]",
    "pix_key": "[email protected]",
    "document_number": "81146431023",
    "phone": "+5511999999999",
    "birth_date": "15-08-1990",
    "address": {
      "street": "Rua das Flores",
      "neighborhood": "Centro",
      "zipcode": "12345678",
      "country": "076",
      "state": "SP",
      "city": "São Paulo",
      "street_number": "123",
      "complement": "Apt 101"
    }
  },
  "updated_at": "2023-12-01T10:00:00.000Z"
}

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

transactionId

string

required

Transaction ID to refund

Body

application/json

refund_reason

enum<string>

required

Reason for the refund.

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

Available options:

BANKING_ERROR,

FRAUD,

CUSTOMER_REQUEST,

PIX_WITHDRAWAL_OR_CHANGE_ERROR

Example:

"CUSTOMER_REQUEST"

refund_amount

integer

Refund amount in cents. Optional — when omitted, the API treats the request as a refund of the transaction's original approved amount.

Required range: x >= 1

Example:

1000

description

string

Additional description for the refund

Example:

"Refund due to customer dissatisfaction"

metadata

object

Optional metadata object for storing custom key-value pairs

Example:

{
  "custom_field": "value",
  "refund_source": "customer_request"
}

Response

Transaction refunded successfully

Transaction data returned by the API

string

required

Transaction unique identifier

Example:

"tx_123456789"

provider

enum<string>

required

Payment provider

Available options:

CELCOIN,

RINNE,

CAPPTA

Example:

"CELCOIN"

affiliation_id

string

required

Affiliation ID for this transaction

Example:

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

request_id

string

required

Unique request ID for this transaction used for idempotency

Example:

"request-123"

mcc

string

required

Merchant Category Code

Example:

"5411"

amount

integer

required

Transaction amount in cents

Example:

10050

currency

enum<string>

required

Transaction currency

Available options:

BRL

Example:

"BRL"

pricing

object

required

Transaction pricing information

Show child attributes

status

enum<string>

required

Transaction status

Available options:

PROCESSING,

AUTHORIZED,

APPROVED,

REFUNDED,

PARTIALLY_REFUNDED,

PENDING_REFUND,

CHARGEDBACK,

WAITING_PAYMENT,

AWAITING_3DS,

RISK_ANALYSIS,

REFUSED,

FAILED,

EXPIRED,

PENDING_CANCELLATION,

CANCELLED

Example:

"APPROVED"

capture_method

enum<string>

required

Transaction capture method

Available options:

EMV,

MAGSTRIPE,

ECOMMERCE,

CONTACTLESS_ICC

Example:

"EMV"

installments

integer | null

required

Number of installments

Example:

1

payment_method

enum<string>

required

Payment method

Available options:

CREDIT_CARD,

DEBIT_CARD,

PIX,

BOLEPIX

Example:

"PIX"

automatic_anticipation

boolean

required

Whether this transaction was automatically anticipated at creation time. Set to true when the affiliation's anticipation_type is AUTOMATIC; false otherwise.

Example:

false

origin

enum<string>

required

Where the transaction originated. INTERNAL: created through the Rinne API. EXTERNAL: originated outside the platform and registered from a provider event, such as an inbound Pix sent directly to a Pix key or a POS (card machine) transaction.

Available options:

INTERNAL,

EXTERNAL

Example:

"INTERNAL"

company_id

string

required

Company ID that owns this transaction

Example:

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

created_at

string<date-time>

required

Transaction creation timestamp

Example:

"2023-12-01T10:00:00.000Z"

fee_policy_id

string | null

Fee policy ID applied to this transaction

Example:

"fee_policy_123"

cost_policy_id

string | null

Cost policy ID applied to this transaction

Example:

"cost_policy_123"

approved_amount

integer | null

Approved amount in cents

Example:

10050

refunded_amount

integer | null

Total amount refunded in cents (sum of completed refunds)

Example:

0

three_d_secure_session_id

string<uuid> | null

ID of the 3DS session linked to this transaction, if any. Set when the transaction was created with a 3DS session (session-first flow) or authenticated via the /authenticate endpoint (transaction-first flow).

Example:

"550e8400-e29b-41d4-a716-446655440000"

acquirer_response_code

string | null

Acquirer response code

Example:

"00"

pix_data

object | null

PIX-specific data (present if payment_method is PIX)

Show child attributes

bolepix_data

object | null

Bolepix-specific data (present if payment_method is BOLEPIX)

Show child attributes

card_data

object | null

Card-specific data (present if payment_method is CREDIT_CARD or DEBIT_CARD)

Show child attributes

soft_descriptor

string | null

The soft_descriptor sent with the create request, as sent. Null when the request had none.

Example:

"MYSTORE"

serial_number

string | null

Terminal serial number

Example:

"12345678"

nsu

string | null

Network Sequential Number

Example:

"000123"

metadata

object | null

Additional metadata

latest_refund_at

string<date-time> | null

Latest refund timestamp (for the most recent completed refund)

Example:

"2023-12-01T10:00:00.000Z"

status_reason

enum<string> | null

Status reason details. REVERSED indicates a failed card transaction whose charge was later found at the acquirer and reversed by reconciliation.

Available options:

PROVIDER,

ACQUIRER,

ANTIFRAUD,

INTERNAL_ERROR,

NO_ACQUIRER,

ACQUIRER_TIMEOUT,

CHALLENGE_NOT_ALLOWED,

REVERSED

Example:

"PROVIDER"

approved_at

string | null

Transaction approval timestamp

Example:

"2023-12-01T10:00:00.000Z"

company_full_name

string

Company full name

Example:

"Test Company"

company_name

string | null

Company name

Example:

"Test Company"

organization_id

string | null

Organization transaction ID (for refunds/chargebacks)

Example:

"tx_organization_123456"

consumer

object | null

Consumer information

Show child attributes

updated_at

string<date-time> | null

Transaction last update timestamp

Example:

"2023-12-01T10:00:00.000Z"

Introduction

Merchants

Pricing

Tap-on-Phone

Webhooks

Organization Management

User Management

System

Refund a transaction for a specific merchant

Authorizations

Path Parameters

Body

Response