Refunds with /refunds

A refund reverses all or part of a sale you already sent to Brinta. You don't resend the buyer, the seller or the taxes. Point to the original sale and say how much to reverse, and Brinta recalculates the taxes on that amount.

1. Total refund

curl -X POST https://api.brinta.com/refunds/ \
  -H "Authorization: Bearer $BRINTA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-idempotency-key: 0c7d1f40-7b2a-4c55-8f0e-3a3e9b7d2c19" \
  -d '{
    "original_transaction_id": "5a6177d1-76ef-49b1-a90a-7ed60ec7d875",
    "transaction_external_id": "REF-10045",
    "type": "refund",
    "status": "pending"
  }'

Every line of the original sale is refunded at its full amount, with its taxes.

2. Partial refund, by line

Reference each line by the items[].id Brinta returned when you created the sale. You can read it back with Get a sale.

{
  "original_transaction_id": "5a6177d1-76ef-49b1-a90a-7ed60ec7d875",
  "transaction_external_id": "REF-10045-1",
  "type": "refund",
  "status": "pending",
  "items": [
    { "original_item_id": "033cdb01-e9b9-4fa1-b4cd-750e8906d38d", "amount": 500 }
  ]
}

• amount is the net amount to refund, excluding taxes.
• To state the amount including taxes, send final_amount instead. Send one or the other on each line, not both.
• Lines you don't list are not refunded.
• If the original sale has a single line, you can leave out original_item_id.

Referencing the sale by your own ID

Use original_transaction_external_id (the sale's transaction_external_id) instead of original_transaction_id. Send exactly one of the two.

Request fields

The following are copied from the original sale: buyer, seller, country, currency, exchange rate, and payment method. Don't send them.

How taxes are reversed

1. Each refund line inherits the taxes Brinta calculated on the original line.
2. They are recalculated on the refunded amount. For a percentage tax, that means refund amount × rate.
3. Amounts come back as positive numbers. The type refund is what tells you they reverse the sale.

Example: a line of 1,000 with 19% VAT, partially refunded for 500, returns VAT of 95.

Limits

• Brinta keeps a running total per line. If the refunds against a line add up to more than the original, the request fails, for example:
  Item with id= "033cdb01-..." refund accumulated amount(1200) exceeds item's amount (1000).
• The same check applies to final_amount.

Response

POST /refunds/ returns 201 Created:

{
  "id": "510e8400-e29b-41d4-a716-446655440012",
  "original_transaction_id": "5a6177d1-76ef-49b1-a90a-7ed60ec7d875",
  "transaction_external_id": "REF-10045-1",
  "status": "pending",
  "type": "refund",
  "currency": "CLP",
  "amount": 500,
  "final_amount": 595,
  "items": [
    {
      "id": "333e8400-e29b-41d4-a716-446655440000",
      "original_item_id": "033cdb01-e9b9-4fa1-b4cd-750e8906d38d",
      "amount": 500,
      "final_amount": 595,
      "taxes": [
        { "name": "IVA a Servicios Digitales", "type": "VAT", "rate": 0.19, "rate_type": "percentage",
          "taxable_amount": 500, "amount": 95, "level": "country", "location": "CL",
          "paid_by": "self", "adds_to_final_amount": true }
      ]
    }
  ]
}

Lifecycle

pending ──► invoiced   (credit note issued: affects taxes)
   │
   ├──────► voided     (original invoice cancelled: affects taxes)
   ├──────► refunded   (money movement only: no tax effect)
   └──────► rejected   (discarded)

Move a refund forward with PUT /refunds/{id}:

{ "status": "invoiced", "invoice_number": "NC-0001-00000123", "invoice_date": "2026-07-15" }

To have Brinta issue the credit note from the refund, call POST /invoices with {"refund_id": "<refund id>", "document_type": "credit note"}. Then mark the refund invoiced.

Reading a refund. GET /refunds/{id} returns it. An unknown ID returns 400 No match for the refund transaction id provided.

Common mistakes