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.
• 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 /v1/merchants/{merchantId}/transactions/{transactionId}/refunds

Refund a transaction for a specific merchant

cURL

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

200

{
  "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,
  "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,
  "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",
    "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": {
    "expiry_month": "12",
    "expiry_year": "2028",
    "last_digits": "1111",
    "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": {},
  "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": "[e-mail]",
    "pix_key": "[e-mail]",
    "document_number": "81146431023",
    "phone": "[phone]",
    "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"
}

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

200

application/json

Transaction refunded successfully

Transaction data returned by the API

id · 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, 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

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

acquirer_response_code · string | null

Acquirer response code

Example:

"00"

pix_data · object

PIX-specific data (present if payment_method is PIX)

Show child attributes

bolepix_data · object

Bolepix-specific data (present if payment_method is BOLEPIX)

Show child attributes

card_data · object

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

Show child attributes

soft_descriptor · string | null

Soft descriptor shown on cardholder statement

Example:

"MYSTORE"

serial_number · string | null

Terminal serial number

Example:

"12345678"

nsu · string | null

Network Sequential Number

Example:

"000123"

metadata · object

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

Available options: PROVIDER, ACQUIRER, ANTIFRAUD, INTERNAL_ERROR, NO_ACQUIRER, ACQUIRER_TIMEOUT, CHALLENGE_NOT_ALLOWED

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

Consumer information

Show child attributes

updated_at · string<date-time> | null

Transaction last update timestamp

Example:

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