Settlement Report
Header - Settlement Information
This summary tab provides an overview of the settlement period, displaying aggregated totals for all transaction types. It includes the total payment amounts, fees charged, refunds processed, chargebacks incurred, and the net settlement amount to be transferred to the merchant's account. The summary reflects the final reconciliation of all financial activities within the settlement period according to the merchant's configured settlement schedule.
| Field | Format | Description | Example | Edge Cases |
|---|---|---|---|---|
| settlement_code | String (alphanumeric, 15-20 chars) | Unique identifier for the settlement. Generated using pattern: SET-{country_code}-{YYMMDD}-{sequence} | SET-BR-240915-001 | Code format variations by country, potential duplicates across environments |
| settlement_currency | String (3 chars, uppercase) | ISO 4217 currency code representing the settlement's primary monetary unit. Retrieved from merchant's country configuration. | BRL | Currency changes due to regulatory requirements, unsupported currencies for new markets |
| merchant_id | Integer (bigint, positive) | Internal unique identifier linking the settlement to the specific merchant account. Auto-generated sequential ID | 84521 | Merchant ID conflicts during data migrations, deleted merchants with orphaned settlements |
| merchant_name | String (varchar 255, UTF-8) | Business name of the merchant as registered in the system. Retrieved from merchant profile. | EBANX LTDA | Name changes not reflected in historical settlements, special characters causing encoding issues |
| generate_date | DateTime (ISO 8601, UTC) | Timestamp when the settlement report was created and finalized. System timestamp captured when settlement moves to confirmed status. | 2024-09-15T14:30:25Z | System clock drift affecting timestamps, settlements generated during maintenance windows |
| settlement_date | Date (YYYY-MM-DD) | Business date when the settlement period was closed and amounts were calculated. Set based on business calendar, typically end of settlement cycle. | 2024-09-15 | Weekend settlements processed on Monday, holiday adjustments, manual settlement date overrides |
| transfer_date | Date (YYYY-MM-DD) | Actual date when funds were transferred to the merchant's bank account. Set by banking system upon successful transfer completion. | 2024-09-17 | Bank holidays causing multi-day delays, failed transfers requiring new dates, weekend processing limitations |
| receive_period_from | Date (YYYY-MM-DD) | Start date of the transaction period included in this settlement. Earliest transaction date included in settlement. | 2024-09-01 | Overlapping periods during settlement corrections, backdated transactions, timezone boundary issues |
| receive_period_to | Date (YYYY-MM-DD) | End date of the transaction period included in this settlement. Latest transaction date included in settlement. | 2024-09-15 | Future-dated transactions, cutoff time variations, partial day exclusions |
| gross_total | Decimal (12,4) | Total amount of all successful payments processed before any deductions. Sum of all confirmed payment amounts in settlement currency. | 125000.0000 | Negative gross due to refund-heavy periods, currency conversion timing differences |
| net_total | Decimal (12,4) | Final amount transferred to merchant after all fees, adjustments, and deductions: gross_total - all_fees - chargeback_cost - refund_cost + chargeback_reversals_cost + refund_reversal_cost | 113308.2200 | Negative net amounts requiring merchant payment, precision loss in complex calculations |
| chargeback_cost | Decimal (12,4) | Total amount deducted from settlement due to chargebacks. Sum of chargeback amounts in settlement currency. | 3200.0000 | Chargebacks exceeding original payment amounts, partial chargebacks |
| chargeback_reversals_cost | Decimal (12,4) | Amount recovered and added back to settlement from successful chargeback disputes. Sum of reversed chargeback amounts where merchant successfully disputed. | 800.0000 | Partial reversals not matching original amounts, reversal timing mismatches |
| refund_cost | Decimal (12,4) | Total amount refunded to customers, deducted from merchant settlement. Sum of all refund amounts processed in settlement period. | 2150.0000 | Refunds exceeding original payment amounts, partial refunds |
| refund_reversal_cost | Decimal (12,4) | Amount recovered from cancelled or reversed refunds, added back to settlement. Sum of refund reversal amounts where refunds were cancelled or disputed successfully. | 125.0000 | Refund reversals without original refund records, timing mismatches |
| refund_fee | Decimal (12,4) | Processing fees charged for handling customer refunds. Sum of refund processing fees based on merchant fee structure. | 115.0000 | Fee-free refund periods, fee structure changes mid-period |
| boleto_fixed_fee | Decimal (12,4) | Fixed fees charged for boleto payment processing: Count of boleto payments × fixed fee rate | 450.0000 | Fee structure changes mid-settlement, boleto payment type misclassification |
| boleto_variable_fee | Decimal (12,4) | Percentage-based fees charged for boleto payment processing: Sum of (boleto_payment_amount × percentage_rate) | 875.0000 | Percentage calculation precision issues, fee tier changes |
| cc_fixed_fee | Decimal (12,4) | Fixed fees charged for credit card payment processing: Count of credit card payments × fixed fee rate | 1247.0000 | Different rates by card brand, fee structure updates |
| cc_variable_fee | Decimal (12,4) | Percentage-based fees charged for credit card payment processing: Sum of (cc_payment_amount × percentage_rate) | 3125.0000 | Interchange rate variations, card brand differences |
| eft_fixed_fee | Decimal (12,4) | Fixed fees charged for electronic funds transfer payment processing: Count of EFT payments × fixed fee rate | 180.0000 | Bank-specific fee variations, fee structure changes |
| eft_variable_fee | Decimal (12,4) | Percentage-based fees charged for electronic funds transfer processing: Sum of (eft_payment_amount × percentage_rate) | 225.0000 | Bank fee pass-through variations, EFT amount tiers |
| dd_fixed_fee | Decimal (12,4) | Fixed fees charged for direct debit payment processing: Count of direct debit payments × fixed fee rate | 90.0000 | Bank mandate fees, failed debit attempt charges |
| dd_variable_fee | Decimal (12,4) | Percentage-based fees charged for direct debit payment processing: Sum of (dd_payment_amount × percentage_rate) | 112.5000 | Bank-specific percentage variations, debit amount tiers |
| anticipation_fee | Decimal (12,4) | Fees charged for early settlement requests: Percentage of anticipated amount × days advanced × daily rate | 187.5000 | Anticipation without fees during promotional periods, fee calculation errors |
| return_mdr | Decimal (12,4) | Merchant Discount Rate returns or adjustments. Sum of MDR adjustments based on volume tiers, promotional credits. | 245.7500 | Negative returns due to fee increases, timing mismatches with original charges |
| amount_others | Decimal (12,4) | Miscellaneous fees and adjustments not categorized in standard fee types. Sum of various uncategorized entries. | 75.0000 | Uncategorized large amounts, manual entry errors |
| e_wallet_fee | Decimal (12,4) | Processing fees for electronic wallet payment methods. Sum of e-wallet processing fees based on wallet type and merchant agreement. | 156.0000 | Different rates by wallet provider, promotional fee periods |
| payment_tax | Decimal (12,4) | Tax amounts related to payment processing, typically IOF or other regulatory taxes. Sum of applicable taxes based on payment types, amounts, and regulatory requirements. | 125.0000 | Tax rate changes mid-settlement, tax exemption status changes |
| nr_payout_transfers | Integer (positive) | Number of payout transfers processed for third-party payments. Count of distinct payout transfers executed. | 23 | Failed payouts counted incorrectly, payout retries double-counted |
| payout_transfer_cost | Decimal (12,4) | Total fees charged for processing payout transfers to third parties. Sum of payout transfer fees based on number of transfers and amounts. | 115.0000 | Failed payout fee handling, payout retry costs |
Example Settlement Calculation
Scenario: Brazilian cross-border merchant with comprehensive fee structure
Base Transaction Data:
Settlement Period: September 1-15, 2024
Merchant: EBANX LTDA (ID: 84521)
Currency: BRL
Total Payments: 1,247 transactions
Payment Method Breakdown:
Credit Card: 850 payments (BRL 95,000.00)
Boleto: 300 payments (BRL 25,000.00)
EFT: 60 payments (BRL 4,500.00)
Direct Debit: 30 payments (BRL 450.00)
E-wallet: 7 payments (BRL 50.00)
Fee Calculations:
CC Fixed: 850 × BRL 1.50 = BRL 1,275.00
CC Variable: BRL 95,000.00 × 3.2% = BRL 3,040.00
Boleto Fixed: 300 × BRL 1.50 = BRL 450.00
Boleto Variable: BRL 25,000.00 × 3.5% = BRL 875.00
EFT Fixed: 60 × BRL 3.00 = BRL 180.00
EFT Variable: BRL 4,500.00 × 5.0% = BRL 225.00
DD Fixed: 30 × BRL 3.00 = BRL 90.00
DD Variable: BRL 450.00 × 25.0% = BRL 112.50
E-wallet Fee: 7 × BRL 22.29 = BRL 156.03
Adjustments and Other Costs:
Chargeback Cost: BRL 3,200.00
Chargeback Reversals: BRL 800.00
Refund Cost: BRL 2,150.00
Refund Reversal: BRL 125.00
Refund Fee: BRL 115.00
Anticipation Fee: BRL 187.50
Return MDR: BRL 245.75
Amount Others: BRL 75.00
Payout Transfer Cost: BRL 115.00
Payment Tax: BRL 125.00
Final Settlement Calculation:
Gross Total: BRL 125,000.00
Total Processing Fees: BRL 6,403.53 (sum of all payment method fees)
Other Fees: BRL 863.25 (refund_fee + anticipation_fee + return_mdr + amount_others + payment_tax + payout_transfer_cost)
Total All Fees: BRL 7,266.78
Chargeback Cost: BRL -3,200.00
Chargeback Reversals: BRL +800.00
Refund Cost: BRL -2,150.00
Refund Reversal: BRL +125.00
Net Total: BRL 113,308.22 (125,000.00 - 7,266.78 - 3,200.00 - 2,150.00 + 800.00 + 125.00)
Payments
This tab contains all confirmed payment transactions that are included in the settlement. Each payment entry shows the original transaction amount, applicable processing fees, currency conversion rates, and the net amount credited to the merchant. Payments are processed through the gateway and settled according to the merchant's payment type configuration and settlement frequency.
| Field | Format | Description | Example | Edge Cases |
|---|---|---|---|---|
| Hash | String (alphanumeric, 50 chars) | Unique payment identifier used for external API references and payment tracking across systems. Auto-generated unique hash at payment creation, remains constant throughout payment lifecycle. | 455ac8c178653bd599b7d90a77d4ee67 | Hash collisions in high-volume periods, legacy hash vs invoice hash mismatches, special characters in older hashes |
| payment_code | String (varchar 120) | Internal merchant payment code provided by merchant during payment creation. Provided by merchant in payment request, stored as merchant_payment_code in database. | ORD-2024-09-15-001 | Duplicate codes from merchant, missing codes, special characters causing encoding issues, very long codes truncated |
| order_number | String (varchar 120, nullable) | Optional merchant order reference number for additional payment identification. Optional field provided by merchant, can be same as payment_code or different. | ORDER-12345-ABC | Missing order numbers, duplicate order numbers across payments, order number format inconsistencies |
| open_date | DateTime (ISO 8601, UTC) | Timestamp when payment was created and initiated by customer. System timestamp captured at payment creation request. | 2024-09-15T10:30:25Z | System clock drift, payments created during maintenance, timezone conversion issues, backdated payments |
| confirm_date | DateTime (ISO 8601, UTC) | Timestamp when payment was confirmed and funds were received. Set when payment status changes to confirmed, typically after fund receipt. | 2024-09-15T14:45:30Z | Delayed confirmations, manual confirmation overrides, confirmation without actual fund receipt, timezone mismatches |
| receive_date | Date (YYYY-MM-DD) | Date when funds were actually received and processed. Set by payment processor when funds are confirmed in bank account. | 2024-09-15 | Weekend processing delays, bank holiday impacts, receive date before confirm date, manual date adjustments |
| received_date_time | DateTime (ISO 8601, UTC) | Complete timestamp of fund receipt including time component. Detailed timestamp from banking system or payment processor. | 2024-09-15T16:20:15Z | Banking system timestamp delays, processor time differences, manual timestamp corrections |
| time | Time/Duration format | Processing time or duration related to payment completion. Calculated as difference between key payment milestones. | 00:04:15 | Negative processing times due to clock issues, extremely long processing times, missing time calculations |
| payment_type | String (enum, 20 chars) | Payment method code identifying the specific payment instrument used. Mapped from payment request based on customer selection and merchant configuration. | creditcard | Payment type misclassification, deprecated payment types, regional payment type variations |
| customer | JSON/String | Customer information associated with the payment. Customer data from payment request, includes name, email, and identification. | {"name": "João Silva", "email": "joao@example.com"} | Missing customer data, customer information updates, privacy compliance requirements, data encoding issues |
| currency | String (3 chars ISO 4217) | Currency code for the payment amount as requested by customer. Currency selected by customer or determined by merchant configuration. | USD | Unsupported currencies, currency changes during payment, deprecated currency codes |
| instalments | Integer (positive) | Number of payment installments for credit card payments. Specified by customer during payment creation, defaults to 1 for non-installment payments. | 12 | Zero installments, excessive installment numbers, installment availability by card type |
| country | String (2 chars ISO 3166) | Country code where payment was processed and originated. Determined by customer location, merchant configuration, or payment method requirements. | BR | Country misidentification, cross-border payment country assignment, deprecated country codes |
| amount | Decimal (12,4) | Payment amount in the external currency as requested by customer. Amount specified in payment request in customer's chosen currency. | 250.0000 | Zero amounts, negative amounts, extremely large amounts, precision loss in conversions |
| fx_rate | Decimal (10,6) | Foreign exchange rate applied to convert payment amount to local currency. Retrieved from FX rate provider at payment creation time. | 5.244500 | Missing FX rates, extreme rate fluctuations, rate provider outages, historical rate corrections |
| amount_gross | Decimal (12,4) | Gross payment amount before any fee deductions in settlement currency. Original amount converted to settlement currency using FX rate. | 1311.2500 | Currency conversion rounding, gross amount adjustments, fee calculation base mismatches |
| amount_net | Decimal (12,4) | Net payment amount after all fee deductions in settlement currency: amount_gross - fee_fixed - fee_percentual - fee_anticipation - other_fees | 1275.8750 | Negative net amounts, fee calculation errors, precision loss in complex fee structures |
| fee_percentual | Decimal (12,4) | Percentage-based processing fee charged on payment amount. (amount_gross × fee_percentage_rate) based on merchant agreement and payment type. | 32.7813 | Percentage calculation precision, fee tier changes, promotional rate periods |
| fee_anticipation | Decimal (12,4) | Fee charged for early settlement or payment acceleration services. Calculated based on anticipation period and merchant risk profile. | 2.6225 | Anticipation without fees, fee calculation errors, risk profile changes affecting rates |
| fee_fixed | Decimal (12,4) | Fixed processing fee charged per payment transaction. Fixed fee amount based on payment type and merchant agreement. | 1.5000 | Fee structure changes mid-processing, payment type misclassification, promotional fee periods |
| instalments_fee | Decimal (12,4) | Additional fees charged for installment payment processing. Fee per installment or percentage of total amount based on installment count. | 3.7500 | Installment fee calculation errors, fee structure variations by installment count |
| fee | Decimal (12,4) | Total processing fees charged for the payment: fee_fixed + fee_percentual + fee_anticipation + instalments_fee + other_fees | 40.6538 | Fee calculation mismatches, missing fee components, rounding differences in fee summation |
| payment_wht | Decimal (12,4) | Withholding tax amount deducted from payment for tax compliance. Calculated based on payment amount, tax rates, and withholding requirements. | 12.5000 | Tax rate changes, withholding exemptions, cross-border tax complications, regulatory updates |
Example Payment Calculation
Scenario: Brazilian cross-border credit card payment with installments
Payment Details:
Hash: 455ac8c178653bd599b7d90a77d4ee67
Payment Code: ORD-2024-09-15-001
Order Number: ORDER-12345-ABC
Payment Type: creditcard
Customer: {"name": "João Silva", "email": "joao@example.com"}
Country: BR (Brazil)
Currency: USD (US Dollar)
Installments: 12
Date Timeline:
Open Date: 2024-09-15T10:30:25Z
Confirm Date: 2024-09-15T14:45:30Z
Receive Date: 2024-09-15
Received Date Time: 2024-09-15T16:20:15Z
Processing Time: 00:05:50
Financial Calculation:
Amount (USD): 250.0000
FX Rate (USD to BRL): 5.244500
Amount Gross (BRL): 1,311.1250 (250.00 × 5.2445)
Fee Structure:
Fee Fixed: BRL 1.5000 (standard credit card fee)
Fee Percentual: BRL 32.7781 (2.5% of gross amount)
Fee Anticipation: BRL 2.6225 (early settlement fee)
Installments Fee: BRL 3.7500 (12 installments × BRL 0.3125)
Payment WHT: BRL 12.5000 (Brazilian withholding tax)
Total Fees: BRL 53.1506
Final Amounts:
Amount Net: BRL 1,257.9744 (1,311.1250 - 53.1506)
Refunds
This tab lists all refund transactions processed during the settlement period. Refunds occur when merchants return funds to customers for returned products or cancelled services. The merchant is debited the refund amount plus any applicable refund processing fees. Refunds are deducted from the settlement total and processed according to the original payment's currency and exchange rate at the time of refund.
| Field | Format | Description | Example | Edge Cases |
|---|---|---|---|---|
| refund_id | Integer (bigint, positive) | Unique internal identifier for the refund record in the system. Auto-generated sequential ID assigned during refund creation, remains constant | 22909551 | ID conflicts during migrations, orphaned refunds, test vs production ID mismatches |
| request_date | DateTime (ISO 8601, UTC) | Timestamp when the refund was initially requested. System timestamp captured at refund creation request. | 2024-09-15T11:15:30Z | Clock drift, requests during maintenance, timezone issues, backdated requests |
| confirm_date | DateTime (ISO 8601, UTC) | Timestamp when the refund was confirmed and approved for processing. Set when refund status changes to confirmed after validation. | 2024-09-15T15:20:45Z | Delayed confirmations, manual overrides, confirmation without fund availability |
| description | Text (varchar 255) | Reason or description for the refund. Free text provided during refund creation. | Customer requested cancellation due to shipping delay | Missing descriptions, long descriptions truncated, special characters in text |
| payment_hash | String (alphanumeric, 50 chars) | Unique identifier of the original payment being refunded. Retrieved from the associated payment record. | 455ac8c178653bd599b7d90a77d4ee67 | Hash mismatches, refunds for deleted payments, legacy vs invoice hash confusion |
| payment_merchant_payment_code | String (varchar 120) | Original payment's merchant code for cross-reference. Retrieved from the original payment's merchant_payment_code field. | ORD-2024-09-15-001 | Missing payment codes, code changes after refund, encoding issues |
| payment_order_number | String (varchar 120, nullable) | Original payment's order number for additional reference. Retrieved from the original payment's order_number field. | ORDER-12345-ABC | Missing or mismatched order numbers, customer confusion with multiple orders |
| payment_type | String (enum, 20 chars) | Payment method used in the original transaction. Retrieved from the original payment's payment_type field. | creditcard | Payment type changes, deprecated types, refund method restrictions |
| payment_customer | JSON/String | Customer information from the original payment. Customer data from original payment (name, email, etc.). | {"name": "João Silva", "email": "joao@example.com"} | Customer info updates, privacy compliance, missing data, encoding issues |
| payment_open_date | DateTime (ISO 8601, UTC) | Creation date of the original payment being refunded. Retrieved from the original payment's open_date field. | 2024-09-15T10:30:25Z | Date modifications affecting eligibility, timezone issues, very old payments |
| payment_confirm_date | DateTime (ISO 8601, UTC) | Confirmation date of the original payment. Retrieved from the original payment's confirm_date field | 2024-09-15T14:45:30Z | Refunding unconfirmed payments, date changes, processing rule violations |
| payment_receive_date | Date (YYYY-MM-DD) | Fund receipt date of the original payment. Retrieved from the original payment's receive_date field. | 2024-09-15 | Refunds before payment settlement, date corrections, fund availability issues |
| original_currency | String (3 chars ISO 4217) | Currency code of the refund amount as requested. From refund request or inherited from original payment. | USD | Mismatches with original payment, unsupported currencies, currency changes |
| original_amount | Decimal (12,4) | Refund amount in the original currency before conversions. Amount specified in the refund request. | 125 | Zero/negative amounts, amounts exceeding original payment, precision issues |
| settlement_currency | String (3 chars ISO 4217) | Currency used for settlement processing. Determined by merchant's settlement configuration. | BRL | Settlement currency changes, multi-currency accounts, regulatory restrictions |
| fx_rate | Decimal (10,6) | Foreign exchange rate applied to convert refund amount. Retrieved from FX provider at refund processing time. | 5.2445 | Missing rates, extreme fluctuations, provider outages, historical corrections |
| amount_gross | Decimal (12,4) | Gross refund amount in settlement currency before fees: original_amount × fx_rate | 655.625 | Conversion rounding issues, gross amount adjustments, timing differences |
| amount_net | Decimal (12,4) | Net refund amount in settlement currency after all fees: amount_gross - fee - return_mdr adjustments | 650 | Negative net amounts, fee calculation errors, precision loss |
| fee | Decimal (12,4) | Processing fee charged for handling the refund. Fixed fee or percentage based on merchant agreement. | 5 | Fee-free periods, fee structure changes, promotional waivers, calculation errors |
| return_mdr | Decimal (12,4) | Merchant Discount Rate return or adjustment for the refund. Percentage of refunded amount returned based on original MDR. | 0.625 | Negative returns, calculation timing differences, rate changes |
| refund_code | String (varchar 150, nullable) | Merchant-provided reference code for the refund request. Provided by merchant in refund request, optional field. | REF-2024-09-15-001 | Duplicate codes, missing codes, special characters, very long codes truncated |
| customer_name | String (varchar 150) | Full name of the customer receiving the refund. Retrieved from refund info or associated customer data. | João Silva Santos | Name changes, missing names, special characters, privacy compliance |
| CPF | String (11 digits) | Brazilian tax identification number (Cadastro de Pessoas Físicas). Brazilian tax ID from customer registration or refund info. | 12345678901 | Invalid formats, missing CPF for Brazilian customers, validation failures |
Example Refund Calculation
Scenario: Brazilian cross-border credit card refund with currency conversion
Refund Details:
Refund ID: 22909551
Refund Code: REF-2024-09-15-001
Description: Customer requested cancellation due to shipping delay
Customer Name: João Silva Santos
CPF: 12345678901
Original Payment Reference:
Payment Hash: 455ac8c178653bd599b7d90a77d4ee67
Payment Merchant Code: ORD-2024-09-15-001
Payment Order Number: ORDER-12345-ABC
Payment Type: creditcard
Payment Customer: {"name": "João Silva", "email": "joao@example.com"}
Date Timeline:
Request Date: 2024-09-15T11:15:30Z
Confirm Date: 2024-09-15T15:20:45Z
Payment Open Date: 2024-09-15T10:30:25Z
Payment Confirm Date: 2024-09-15T14:45:30Z
Payment Receive Date: 2024-09-15
Financial Calculation:
Original Currency: USD
Original Amount: 125.0000
Settlement Currency: BRL
FX Rate: 5.244500
Amount Gross: 655.5625 (125.00 × 5.2445)
Fee Structure:
Fee: BRL 5.0000 (refund processing fee)
Return MDR: BRL 0.6250 (2.5% MDR return on original payment)
Final Amounts:
Amount Net: BRL 649.9375 (655.5625 - 5.0000 - 0.6250)
Refund Reversal
This tab appears when the optional field is enabled and shows refund reversal transactions. A refund reversal occurs when a previously processed refund is reversed, typically due to insufficient funds in the customer's account or other payment processing issues. The merchant is credited back the refund amount minus any applicable reversal processing fees. These transactions are processed through the settlement system and added to the merchant's settlement balance.
| Field | Format | Description | Example | Edge Cases |
|---|---|---|---|---|
| refund_id | Integer (bigint, positive) | Unique internal identifier of the original refund being reversed. Retrieved from original refund record for lookup. | 22909551 | Mismatched IDs, reversals for deleted refunds, orphaned reversal records |
| refund_request_date | DateTime (ISO 8601, UTC) | Timestamp when the original refund was initially requested. Retrieved from original refund's request_date field. | 2024-09-15T11:15:30Z | Date modifications affecting eligibility, timezone issues, very old refunds |
| refund_reversal_date | DateTime (ISO 8601, UTC) | Timestamp when the refund reversal was created and processed. System timestamp captured at reversal creation. | 2024-09-17T09:45:15Z | Clock drift, reversals during maintenance, timezone issues, backdated reversals |
| description | Text (varchar 255) | Reason or justification for reversing the original refund. Free text provided during reversal creation. | Chargeback dispute won - refund no longer valid | Missing descriptions, long descriptions truncated, special characters |
| payment_hash | String (alphanumeric, 50 chars) | Unique identifier of the original payment. Retrieved from original refund's associated payment record. | 455ac8c178653bd599b7d90a77d4ee67 | Hash mismatches, reversals for payments with multiple refunds |
| payment_order_number | String (varchar 120, nullable) | Order number from the original payment transaction. Retrieved from original payment's order_number field. | ORDER-12345-ABC | Missing order numbers, order number changes after reversal |
| merchant_payment_code | String (varchar 120) | Merchant's original payment code for cross-reference. Retrieved from original payment's merchant_payment_code field. | ORD-2024-09-15-001 | Missing payment codes, code changes after reversal, encoding issues |
| merchant_refund_code | String (varchar 150, nullable) | Merchant's original refund code being reversed. Retrieved from original refund's merchant_refund_code field. | REF-2024-09-15-001 | Missing refund codes, duplicate codes, format inconsistencies |
| refund_reversal_original_currency | String (3 chars ISO 4217) | Currency code of the refund reversal amount. From original refund or specified during reversal creation. | USD | Mismatches with original refund, unsupported currencies, currency changes |
| refund_reversal_original_amount | Decimal (12,4) | Reversal amount in the original currency before conversion. Amount being reversed, typically matches original refund. | 125 | Zero amounts, negative amounts, partial reversals, precision issues |
| refund_reversal_settlement_fx_rate | Decimal (10,6) | FX rate applied to convert reversal amount to settlement currency. Retrieved from FX provider at reversal processing time. | 5.2445 | Missing rates, extreme fluctuations, provider outages, rate timing differences |
| refund_reversal_currency | String (3 chars ISO 4217) | Currency used for settlement processing of the reversal. Determined by merchant's settlement configuration. | BRL | Settlement currency changes, multi-currency accounts, regulatory restrictions |
| refund_reversal_amount | Decimal (12,4) | Final reversal amount in settlement currency after conversion: original_amount × settlement_fx_rate | 655.625 | Conversion rounding, settlement adjustments, timing differences, precision loss |
Example Refund Reversal Calculation
Scenario: Brazilian cross-border credit card refund reversal due to successful chargeback dispute
Refund Reversal Details:
Refund ID: 22909551
Refund Request Date: 2024-09-15T11:15:30Z
Refund Reversal Date: 2024-09-17T09:45:15Z
Description: Chargeback dispute won - refund no longer valid
Merchant Refund Code: REF-2024-09-15-001
Original Payment Reference:
Payment Hash: 455ac8c178653bd599b7d90a77d4ee67
Payment Order Number: ORDER-12345-ABC
Merchant Payment Code: ORD-2024-09-15-001
Financial Calculation:
Refund Reversal Original Currency: USD
Refund Reversal Original Amount: 125.0000
Refund Reversal Settlement Fx Rate: 5.244500
Refund Reversal Currency: BRL
Refund Reversal Amount: 655.5625
Settlement Impact:
Original refund deducted: BRL 655.5625
Reversal credits back: BRL 655.5625
Net effect: Merchant receives back the amount previously deducted for the refund.
Chargebacks
This tab displays all chargeback transactions where customers disputed payments through their card issuer or payment provider. Chargebacks result in the transaction amount being debited from the merchant's account, along with chargeback processing fees. The chargeback amount is calculated using the settlement's exchange rate and deducted from the total settlement amount according to the merchant's chargeback fee configuration.
| Field | Format | Description | Example | Edge Cases |
|---|---|---|---|---|
| chargeback_id | Integer (bigint, positive) | Unique internal identifier for the chargeback record. Auto-generated sequential ID upon chargeback creation. | 15847293 | ID conflicts in migrations, orphaned chargebacks, test vs. production ID mismatches |
| chargeback_date | Date (YYYY-MM-DD) | Date when the chargeback was initiated by the card issuer. Date provided by the card network when the chargeback is reported. | 2024-09-14 | Future-dated chargebacks, weekend/holiday processing delays |
| description | Text (varchar 255) | Detailed reason for the chargeback from the card issuer. Free text from the card network explaining the reason. | Unauthorized transaction | Missing/truncated descriptions, special characters in text |
| reason_code | String (varchar 10) | Standardized chargeback reason code from the card network. Standard code provided by the card network. | 4855 | Invalid codes, code changes during dispute, network-specific variations |
| acquirer | String (varchar 50) | Payment acquirer or processor that reported the chargeback. Acquirer name or code from the payment chain. | Stone Pagamentos | Missing acquirer info, acquirer name changes |
| nsu_doc | String (varchar 50, nullable) | Network Service Unit document or authorization code. NSU or auth code from the original transaction. | 123456789012 | Missing NSU numbers, format variations by acquirer, duplicate NSUs |
| payment_hash | String (alphanumeric, 50 chars) | Unique identifier of the original payment being charged back. Retrieved from the associated payment record. | 455ac8c178653bd599b7d90a77d4ee67 | Hash mismatches, chargebacks for deleted payments |
| payment_code | String (varchar 120) | Merchant's original payment code for cross-reference. Retrieved from the original payment's merchant_payment_code. | ORD-2024-09-14-001 | Missing codes, code changes after chargeback, encoding issues |
| payment_order_number | String (varchar 120, nullable) | Original payment's order number for additional reference. Retrieved from the original payment's order_number field. | ORDER-12345-ABC | Missing or mismatched order numbers, customer confusion |
| payment_type | String (enum, 20 chars) | Payment method used in the original transaction. Retrieved from the original payment's payment_type field. | creditcard | Rule changes based on payment type, deprecated types |
| payment_customer | JSON/String | Customer information from the original payment. Data from the original payment (name, email, etc.). | {"name": "Maria Silva", "email": "maria@example.com"} | Customer info updates, privacy compliance, missing data |
| payment_open_date | DateTime (ISO 8601, UTC) | Creation date of the original payment. Retrieved from the original payment's open_date field. | 2024-09-14T08:30:25Z | Date modifications affecting eligibility, very old payments |
| payment_confirm_date | DateTime (ISO 8601, UTC) | Confirmation date of the original payment. Retrieved from the original payment's confirm_date field. | 2024-09-14T12:45:30Z | Chargebacks on unconfirmed payments, date changes |
| payment_receive_date | Date (YYYY-MM-DD) | Fund receipt date of the original payment. Retrieved from the original payment's receive_date field. | 2024-09-14 | Chargebacks before settlement, date corrections |
| original_currency | String (3 chars ISO 4217) | Currency code of the chargeback amount. From chargeback notification or original payment. | USD | Mismatches with original payment, unsupported currencies |
| original_amount | Decimal (12,4) | Chargeback amount in the original currency. Amount specified in the chargeback notification. | 150.0000 | Zero/negative amounts, amounts exceeding original payment |
| settlement_currency | String (3 chars ISO 4217) | Currency used for settlement processing. Determined by merchant's settlement configuration. | BRL | Settlement currency changes, multi-currency accounts |
| fx_rate | Decimal (10,6) | FX rate used for currency conversion. When original_currency equals settlement_currency, this rate is not applied to amount_gross but is used to calculate local_amount_gross (conversion to merchant's local currency, typically BRL). | 5.244500 | Missing rates, extreme fluctuations, rate provider outages, same-currency settlements where rate is only used for local_amount_gross |
| amount_gross | Decimal (12,4) | Gross chargeback amount in settlement currency. When original_currency differs from settlement_currency: original_amount × fx_rate. When both currencies match, equals original_amount directly. | 786.6750 | Conversion rounding, gross amount adjustments, same-currency cases where fx_rate is not applied |
| amount_net | Decimal (12,4) | Net chargeback amount debited from merchant: amount_gross + fee | 811.6750 | Fee calculation errors, precision loss |
| fee | Decimal (12,4) | Processing fee charged for handling the chargeback. Fixed fee or percentage based on merchant agreement. | 25.0000 | Fee-free periods, fee structure changes, promotional waivers |
| local_amount_gross | Decimal (12,4) | Gross chargeback amount in merchant's local currency. Amount converted to merchant's local currency. | 786.6750 | Local currency differs from settlement currency, multiple conversions |
| time | DateTime (ISO 8601, UTC) | Timestamp when chargeback was processed in the system. Timestamp when the chargeback record is created. | 2024-09-14T16:20:15Z | Clock drift, processing delays, timezone issues |
| customer_name | String (varchar 150) | Full name of the customer from the original payment. Retrieved from the original payment's customer info. | Maria Silva Santos | Name changes, missing names, special characters |
| chargeback_create_date | DateTime (ISO 8601, UTC) | Timestamp when the chargeback record was created. Database timestamp when the record is inserted. | 2024-09-14T16:20:15Z | Creation date differs from chargeback date, processing delays |
Example Chargeback Calculation
Scenario: Brazilian cross-border credit card chargeback with currency conversion
Chargeback Details:
Chargeback ID: 15847293
Chargeback Date: 2024-09-14
Chargeback Create Date: 2024-09-14T16:20:15Z
Description: Unauthorized transaction - customer denies making purchase
Reason Code: 4855
Acquirer: Stone Pagamentos
NSU Doc: 123456789012
Customer Name: Maria Silva Santos
Original Payment Reference:
Payment Hash: 455ac8c178653bd599b7d90a77d4ee67
Payment Code: ORD-2024-09-14-001
Payment Order Number: ORDER-12345-ABC
Payment Type: creditcard
Payment Customer: {"name": "Maria Silva", "email": "maria@example.com"}
Date Timeline:
Payment Open Date: 2024-09-14T08:30:25Z
Payment Confirm Date: 2024-09-14T12:45:30Z
Payment Receive Date: 2024-09-14
Time: 2024-09-14T16:20:15Z
Financial Calculation:
Original Currency: USD
Original Amount: 150.0000
Settlement Currency: BRL
FX Rate: 5.244500
Amount Gross: 786.6750
Local Amount Gross: 786.6750
Fee: BRL 25.0000
Amount Net: BRL 811.6750
Settlement Impact:
Merchant settlement debited: BRL 811.6750
Chargebacks Reversals
This chargeback reversal occurs when a merchant successfully disputes a chargeback by providing evidence that the original transaction was legitimate and authorized by the customer. The merchant recovers most of the original transaction amount, but pays processing fees for the reversal handling. The reversal is processed through the settlement system and credited to the merchant's account according to their settlement schedule.
| Field | Format | Description | Example | Edge Cases |
|---|---|---|---|---|
| chargeback_id | Integer (bigint, positive) | Unique ID of the original chargeback being reversed. Retrieved from the original chargeback record. | 15847293 | Mismatched IDs, reversals for deleted chargebacks |
| open_date | Date (YYYY-MM-DD) | Date when the chargeback reversal process was initiated. Date when reversal request was created or dispute was won. | 2024-09-16 | Future-dated reversals, weekend/holiday processing delays |
| time | DateTime (ISO 8601, UTC) | Timestamp when chargeback reversal was processed. Timestamp captured when the reversal record is created/updated. | 2024-09-16T14:30:25Z | Clock drift, processing delays, timezone issues |
| confirm_date | Date (YYYY-MM-DD) | Date when the chargeback reversal was confirmed. Date when reversal status changes to confirmed. | 2024-09-16 | Delayed or manual confirmations, validation issues |
| receive_date | Date (YYYY-MM-DD) | Date when reversal funds were credited back to merchant. Date when reversal amount is credited to the merchant account. | 2024-09-17 | Receive date before confirmation, bank processing delays |
| merchant_payment_code | String (varchar 120) | Merchant's original payment code from the transaction. Retrieved from the original payment record. | ORD-2024-09-14-001 | Missing codes, code changes after reversal, encoding issues |
| order_number | String (varchar 120, nullable) | Order number from the original payment transaction. Retrieved from the original payment record. | ORDER-12345-ABC | Missing or changed order numbers, customer confusion |
| currency_ext | String (3 chars ISO 4217) | External currency code of the reversal amount. From original chargeback or specified during reversal. | USD | Mismatches with original chargeback, unsupported currencies |
| amount_ext | Decimal (12,4) | Reversal amount in the external currency. Amount being reversed, typically matches original chargeback. | 150.0000 | Zero/negative amounts, partial reversals, precision issues |
| payment_type_code | String (varchar 20) | Payment method code from the original transaction. Retrieved from the original payment record. | CC | Rule changes based on payment type, deprecated types |
| customer | JSON/String | Customer information from the original payment. Data from original payment (name, email, etc.). | {"name": "Maria Silva", "email": "maria@example.com"} | Customer info updates, privacy compliance, missing data |
| settlement_id | Integer (bigint, positive) | ID of the settlement where the reversal is processed. Settlement ID where the reversal amount will be credited. | 98765432 | Missing associations, settlement changes after reversal |
| hash | String (alphanumeric, 50 chars) | Unique payment hash from the original transaction. Retrieved from the original payment's hash field. | 455ac8c178653bd599b7d90a77d4ee67 | Hash mismatches, multiple chargebacks on a payment |
| reversal_open_date | Date (YYYY-MM-DD) | Date when the chargeback reversal was officially opened. Date when reversal process was formally initiated. | 2024-09-16 | Date mismatches with chargeback date, manual overrides |
| reversal_set_net | Decimal (12,4) | Net reversal amount in settlement currency: amount_ext × fx_rate, adjusted for fees | 786.6750 | Conversion rounding, settlement adjustments, precision loss |
| instalments | Integer (positive, nullable) | Number of installments from the original payment. Retrieved from the original payment record. | 3 | Missing installment info, installment-specific rules |
| payment_type | String (enum, 20 chars) | Payment method classification from the original transaction. Retrieved from the original payment record. | creditcard | Rule changes based on payment type, deprecated types |
| currency | String (3 chars ISO 4217) | Settlement currency used for the reversal. Determined by merchant's settlement configuration. | BRL | Settlement currency changes, multi-currency accounts |
| fx_rate | Decimal (10,6) | FX rate to convert reversal amount to settlement currency. Retrieved from FX provider at time of reversal. | 5.244500 | Missing rates, extreme fluctuations, rate provider outages |
| amount_gross | Decimal (12,4) | Gross reversal amount in settlement currency: amount_ext × fx_rate | 786.6750 | Conversion rounding, gross amount adjustments |
| fee | Decimal (12,4) | Processing fee for handling the chargeback reversal. Fixed fee or percentage based on merchant agreement. | 15.0000 | Fee-free periods, fee structure changes, promotional waivers |
| fee_anticipation | Decimal (12,4) | Early settlement fees applied to the reversal: Percentage of reversal amount × days advanced × daily rate | 5.0000 | Fee-free promotions, calculation errors, eligibility issues |
| fixed_fee | Decimal (12,4) | Fixed processing fee for the reversal. Fixed fee rate based on merchant agreement. | 10.0000 | Fee structure changes, reversal type misclassification, fee waivers |
Example Chargeback Reversal Calculation
Scenario: Brazilian cross-border credit card chargeback reversal due to successful merchant dispute
Chargeback Reversal Details:
Chargeback ID: 15847293 (original chargeback being reversed)
Open Date: 2024-09-16 (when reversal process was initiated)
Time: 2024-09-16T14:30:25Z (system processing timestamp)
Confirm Date: 2024-09-16 (when reversal was confirmed)
Receive Date: 2024-09-17 (when funds were credited to merchant)
Reversal Open Date: 2024-09-16 (official reversal opening)
Original Transaction Reference:
Merchant Payment Code: ORD-2024-09-14-001
Order Number: ORDER-12345-ABC
Hash: 455ac8c178653bd599b7d90a77d4ee67
Payment Type Code: CC
Payment Type: creditcard
Customer: {"name": "Maria Silva", "email": "maria@example.com"}
Instalments: 3
Settlement ID: 98765432
Financial Calculation:
Currency Ext: USD (external currency)
Amount Ext: 150.0000 (reversal amount in USD)
Currency: BRL (settlement currency)
FX Rate: 5.244500 (exchange rate at reversal time)
Amount Gross: 786.6750 (150.00 × 5.2445)
Fee Structure:
Fixed Fee: BRL 10.0000 (fixed reversal processing fee)
Fee: BRL 15.0000 (total processing fee)
Fee Anticipation: BRL 5.0000 (early settlement fee)
Reversal Set Net: BRL 756.6750 (786.6750 - 15.00 - 5.00 - 10.00)
Settlement Impact:
Original chargeback debited: BRL 811.6750 from merchant settlement
Reversal credits back: BRL 756.6750 to merchant settlement
Net merchant recovery: BRL 756.6750 (original amount minus processing fees)
Processing costs: BRL 30.0000 (total fees for reversal processing)
Payout transfers
This tab contains internal transfer transactions between merchant accounts or sub-accounts within the EBANX platform. These transfers allow merchants to move funds between different settlement accounts or business units. Transfer amounts are processed at the current exchange rate and may include transfer processing fees depending on the merchant's configuration.
| Field | Format | Description | Example | Edge Cases |
|---|---|---|---|---|
| request_date | DateTime (ISO 8601, UTC) | Date and time when the payout transfer was initially requested. System timestamp captured when the payout transfer request is created. | 2024-09-15T10:30:25Z | Future-dated requests, old pending requests, system clock drift, batch processing timing |
| confirm_date | DateTime (ISO 8601, UTC) | Date and time when the payout transfer was confirmed and approved. System timestamp captured when the transfer status changes to confirmed. | 2024-09-15T14:45:30Z | Confirmation without validation, delayed confirmations, manual overrides, confirmation before request |
| uid | String (alphanumeric, 32-50 chars) | Unique identifier for the payout transfer transaction. Auto-generated unique identifier (e.g., UUID) at creation. | 7a8b9c2d-4e5f-6789-abcd-ef0123456789 | UID conflicts during migration, duplicate UIDs across environments, orphaned transfers |
| external_reference | String (varchar 120, nullable) | External reference code provided by the merchant or system. Reference code provided by the merchant during transfer creation. | PAYOUT-2024-09-15-001 | Missing or duplicate references, format inconsistencies, special characters |
| amount | Decimal (12,4) | Payout transfer amount in the settlement currency. Amount specified during creation, converted to settlement currency if needed. | 1250.0000 | Zero or negative amounts, amounts exceeding balance, precision issues, very large amounts |
Example Payout Transfer Calculation
Scenario: Brazilian cross-border merchant requesting payout transfer to third-party recipient
Payout Transfer Details:
UID: 7a8b9c2d-4e5f-6789-abcd-ef0123456789
Request Date: 2024-09-15T10:30:25Z (when transfer was requested)
Confirm Date: 2024-09-15T14:45:30Z (when transfer was confirmed)
External Reference: PAYOUT-2024-09-15-001 (merchant's internal reference)
Amount: BRL 1,250.0000 (transfer amount in settlement currency)
Processing Timeline:
Request initiated: 2024-09-15T10:30:25Z
Validation completed: 2024-09-15T14:45:30Z
Processing time: 4 hours 15 minutes
Settlement impact: BRL 1,250.0000 debited from merchant settlement
Business Context:
This payout transfer represents a marketplace or split payment scenario where the merchant needs to transfer funds to a third-party recipient (such as a seller in a marketplace, affiliate partner, or service provider). The transfer is processed through the settlement system and debited from the merchant's available settlement balance.
Settlement Integration:
Transfer amount is included in settlement calculations as payout_transfers_cost
Reduces merchant's net settlement amount
Processed according to merchant's settlement schedule
Subject to payout transfer fees and processing costs
Cross-Border Considerations:
Currency conversion may be required if recipient currency differs from settlement currency
FX rates applied at confirmation time for accurate settlement processing
Regulatory compliance requirements for international transfers
Anti-money laundering (AML) and know-your-customer (KYC) validations
This comprehensive documentation provides complete understanding of all 5 payout transfer tab fields in Cross-Border Settlement Reports, including their formats, purposes, and the various edge cases that can affect payout transfer processing in EBANX's cross-border payment system. Each field plays a crucial role in tracking payout transfers, maintaining transaction integrity, and ensuring accurate settlement processing for international merchants operating in marketplace and split payment scenarios.
Payouts (exclusive for CO, because of Retefuent tax)
This tab displays payout transactions where funds are disbursed from the merchant's account to third parties or beneficiaries. Each payout entry shows the request date, paid date, unique identifier (UID), external reference, total amount, and applicable fees including the base debit fee and any tax credits (such as ISR credit for Colombian merchants with Retefuente) Payouts are debited from the settlement total and processed according to the merchant's payout configuration and settlement schedule.
| Field | Format | Description | Example | Edge Cases |
|---|---|---|---|---|
| request_date | DateTime (ISO 8601, UTC) | Date and time when the payout was initially requested. System timestamp captured when the payout request is created. | 2024-09-15T10:30:25Z | Future-dated requests, system clock drift |
| paid_date | DateTime (ISO 8601, UTC) | Date and time when the payout was successfully completed. System timestamp captured when payout status changes to paid. | 2024-09-15T16:45:30Z | Paid date without validation, delayed payments |
| uid | String (alphanumeric, 32-50 chars) | Unique identifier for the payout transaction. Auto-generated unique identifier. | 7a8b9c2d-4e5f-6789-abcd-ef0123456789 | UID conflicts, orphaned payouts |
| external_reference | String (varchar 120, nullable) | External reference code provided by the merchant for tracking. Reference code provided by the merchant. | PAYOUT-2024-09-15-001 | Missing references, duplicate references |
| total_amount | Decimal (12,4) | Total payout amount in local currency, including all fees. local_amount_total from payout data. | 1275.0000 | Zero amounts, negative amounts, precision issues |
| fee_credit_amount | Decimal (12,4) | Fee credit amount applied to the payout. The credit amount applied to reduce payout fees. | 25.0000 | Negative fee credits, missing fee credit records |
Example Payout Calculation:
Payout UID: 7a8b9c2d-4e5f-6789-abcd-ef0123456789
Request Date: 2024-09-15T10:30:25Z
Paid Date: 2024-09-15T16:45:30Z
External Reference: PAYOUT-2024-09-15-001
Total Amount: BRL 1,275.0000
Fee Credit Amount: BRL 25.0000
Net Cost to Merchant: BRL 1,250.0000
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.