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, "anticipation_days": 1, "origin": "INTERNAL", "company_id": "a3dbd0c2-9f79-4f86-8caa-47779b3f2793", "company_document_type": "CNPJ", "company_document_number": "12345678000195", "pix_payer": { "account_holder_name": "Maria Silva", "account_holder_document_number": "12345678901", "ispb": "18236120" }, "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" }

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:

A refund the transaction’s state refuses is answered 400 with code REFUND_NOT_ALLOWED and the rule in details.reason: PAYMENT_METHOD_NOT_SUPPORTED (BOLEPIX, or a payment method the transaction’s provider cannot refund), REFUND_IN_PROGRESS, ALREADY_REFUNDED (fully refunded, or a card transaction with a completed refund: card refunds are accepted once per transaction), TRANSACTION_NOT_APPROVED (only APPROVED or PARTIALLY_REFUNDED transactions with an approved amount can be refunded), PAYMENT_DATA_MISSING (no Pix end-to-end id, or no acquirer id on a card payment), PROVIDER_UNAVAILABLE, SETTLEMENT_IN_PROGRESS and REFUND_WINDOW_EXPIRED (a Pix approved more than 90 days ago). These are the values of the transaction’s refundability.blocked_reason, so reading the transaction first tells whether a refund will be accepted. They are checked before the amount.
An amount the transaction refuses is answered 400 with code VALIDATION_ERROR on field amount: more than the approved amount minus prior refunds that are not FAILED or CANCELLED, a partial refund on a provider that only accepts full cancellations, or a partial card refund on the day of the sale.
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 refused with REFUND_NOT_ALLOWED and reason SETTLEMENT_IN_PROGRESS once the pre-settlement cancellation window has closed. The cutoff depends on payment method and anticipation: DEBIT_CARD settles on the next business day after approval; anticipated CREDIT_CARD settles at approval plus the transaction’s anticipation_days (D+N), rolled to the next business day when that day is not one and never later than the standard schedule (a transaction created before anticipation_days existed, whose value the backfill has not stored yet, keeps the next-business-day window until it does); 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, and the transaction’s refundability.refundable_until carries that instant while the window is open (it is null once it has closed). 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 is retried by background jobs until it completes, is cancelled, or its refund window closes (the card pre-settlement window, the Pix 90-day return window); then it is marked FAILED unless the provider already took it, with the reason in last_attempt_error_message.

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

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

anticipation_days

integer

required

Automatic-anticipation horizon in days (D+N), copied from the affiliation at creation and immutable after. 0 when automatic_anticipation is false. Available to fee and cost policy rule conditions as transaction.anticipation_days. A transaction created before this field existed reports the affiliation's current horizon when automatic_anticipation is true and 0 otherwise, until a one-time backfill stores its value; its card refund window is the next-business-day one until then.

Required range: x >= 0

Example:

1

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"

company_document_type

enum<string>

required

Document type of the company that owns this transaction (the receiver).

Available options:

CPF,

CNPJ

Example:

"CNPJ"

company_document_number

string

required

Document number of the company that owns this transaction (the receiver), without formatting: CPF (11 digits) or CNPJ (14 characters, alphanumeric CNPJ supported).

Example:

"12345678000195"

pix_payer

object | null

required

The account holder who actually paid a PIX transaction, as reported by the payment provider when the payment is received. May differ from consumer, which is what the integrator sent at creation. null until the payment is received, and for every other payment method. A PIX received on a Pix key without a charge carries it from creation.

Show child attributes

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