Refund Report
Refunds
The Transactional Refund Report provides a detailed record of individual refund transactions processed through the EBANX platform. This report is used for refund reconciliation, customer support queries, and operational monitoring. Each refund is shown as a separate line item with complete information about both the refund itself and its associated payment transaction.
| Field | Format | Description | Example | Edge Cases |
|---|---|---|---|---|
| REFUND_ID | Integer (numeric string without formatting) | Unique numeric identifier for the refund transaction | 7412563211, 3001 | Always populated and unique; never null; used as primary identifier |
| CODE | String (merchant-defined, optional) | Merchant-provided unique identifier for the refund transaction | REF-2023-001, REF-002 | Can be null if merchant doesn't provide it; not enforced as unique |
| REQUESTED_DATE | DateTime string (YYYY-MM-DD HH:MM:SS) | Date and time when the refund was initially requested | 2023-10-24 10:30:15 | Never null; always populated at refund creation; timezone may vary |
| CONFIRMED_DATE | DateTime string (YYYY-MM-DD HH:MM:SS) | Date and time when the refund was confirmed and processed | 2023-10-24 14:22:30 | Null for non-confirmed refunds; may be backdated for manual confirmations |
| CANCELED | Date string (YYYY-MM-DD) or null | Date when the refund was cancelled | 2023-10-25, null | Null for non-cancelled refunds; mutually exclusive with confirmed_date |
| STATUS | String enumeration (CO, CA, PE, OP) | Current status of the refund transaction | CO (Confirmed), CA (Cancelled) | Always populated; reflects current refund state; follows strict state machine rules |
| DESCRIPTION | String (line breaks and special characters cleaned for CSV) | Text description or reason for the refund | Customer requested refund | Can be empty; special characters removed for CSV compatibility |
| REFUND_CURRENCY | 3-letter ISO 4217 currency code | Currency code for the refund amount | USD, BRL, EUR | Always populated; matches original payment currency in most cases |
| REFUND_AMOUNT | Decimal number with 2 decimal places | The monetary amount being refunded in external currency | 150.75, 50.00 | No decimal places for zero-decimal currencies (COP); may be partial refund |
| PAYMENT_CODE | String (merchant-defined) | Merchant-provided unique identifier for the original payment | INV-2023-001 | Can be null if merchant didn't provide it for the payment |
| ORDER_NUMBER | String (optional, non-unique) | Order reference number for the original payment | ORDER-12345 | Can be null; multiple refunds can share same order_number |
| HASH | Hexadecimal string (48 characters) | Unique EBANX payment hash identifier for the original payment | 54154bb...44a4ac | Always populated; multiple refunds can share same hash for partial refunds |
| CUSTOMER_NAME | String (UTF-8 encoded, variable length) | Full name of the customer who made the original payment | Maria Silva Santos, ********** | May be masked with asterisks if data masking is enabled |
| CUSTOMER_DOCUMENT | String (document format varies by country) | Customer's government-issued document number (CPF, CNPJ, etc.) | ***.444.***-** (BR CPF, masked) | Format varies by country (CPF, CNPJ, DNI, RUT, etc.); may be masked for privacy |
| PMT CONFIRM DATE | DateTime (ISO 8601, UTC) | Confirmation date of the original payment | 2024-09-15T14:45:30Z | Refunding unconfirmed payments, date changes, processing rule violations |
| PMT TYPE | String (enum, 20 chars) | Payment method used in the original transaction | creditcard | Payment type changes, deprecated types, refund method restrictions |
| PMT CURRENCY | 3-letter ISO 4217 currency code | External/original currency code of the payment amount | USD, EUR, BRL, GBP | May differ from CURRENCY_LOCAL for cross-border transactions; determines AMOUNT field currency |
| AMOUNT ORDER | Decimal number with 2 decimal places (or 0 for zero-decimal currencies) | Payment amount in external/original currency (gross amount before fees) | 12.34, 150.75, 1000 (for COP) | For zero-decimal currencies (CLP, COP, JPY), no decimal places; rounding may occur during currency conversion |
| PMT LOCAL CURRENCY | 3-letter ISO 4217 currency code | Local currency code of the payment's processing country | BRL, MXN, ARS, COP, CLP | Can be null for some payment types; matches country's primary currency |
| AMOUNT LOCAL | Decimal (12,4) | Payment amount in the external currency as requested by customer | 250.0000 | Zero amounts, negative amounts, extremely large amounts, precision loss in conversions |
Example Refund Calculation
Scenario: Brazilian cross-border merchant processing partial refund with comprehensive fee structure
Base Transaction Data
Refund Date: October 25, 2024
Merchant: EBANX Demo Merchant
Original Payment: Credit Card (Visa) - USD 100.00
Refund Amount: USD 50.00 (partial refund)
Customer: Maria Silva Santos
Country: Brazil (BR)
Refund ID: 7412563211
Original Payment Context
Payment Hash: 54154bb33b47474eb64ef36193644cce4e4c44c4e444a4ac
Payment Code: INV-2024-001
Payment Confirmed: October 24, 2024 14:22:30
Payment Amount: USD 100.00
Payment Amount Local: BRL 543.10
Refund Transaction Amounts
Refund Amount (amount_ext): USD 50.00
Refund Currency: USD
Local Currency: BRL
Exchange Rate: 5.4310
Refund Amount Local: BRL 271.55 (50.00 × 5.4310)
Refund Cost Calculation
Set Cost (amount to be deducted from merchant): BRL 271.55
This represents the gross amount being refunded to the customer
Refund Fee Calculations
Fee Breakdown:
Base Refund Fee: BRL 2.00 (fixed fee per refund)
Fee Application Logic:
Only applied to first refund per payment
If this is the second refund for the same payment, fee = BRL 0.00
Credit Card Deposit Fee (if applicable):
Applied when refund occurs after cancellation window (90 days)
In this case: Not applicable (refund within 90 days)
Total Refund Fee: BRL 2.00
Additional Fees (Colombia-specific, if applicable)
For Colombian merchants, additional fees may apply:
Retefuente Merchant Fee: BRL 2.00 × 2.5% = BRL 0.05 (if applicable)
ReteICA Fee: BRL 2.00 × 0.966% = BRL 0.02 (if applicable)
IVA Fee: BRL 2.00 × 19% = BRL 0.38 (if applicable)
ReteIVA Fee: BRL 0.38 × 15% = BRL 0.06 (if applicable)
Note: For Brazilian merchants in this example, these fees do not apply.
Return MDR (Merchant Discount Rate)
Return MDR: BRL 0.50 (calculated based on merchant configuration)
Still need help?
We hope this article was helpful. If you still have questions, you can explore the following options:
- Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
- Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.