Refund Flow

Return Policy Overview

Rule	Description
Return Window	20 days from product receipt
7-Day Right of Withdrawal	Full reversal including IOF tax refund
Settlement	Partner transfers merchandise value back to the fund

Refund Scenarios

Scenario	Customer Action	Financial Outcome
Full Return (no payments)	Returns entire order, no installments paid	Loan cancelled. Partner returns merchandise value. Fund absorbs IOF and interest.
Full Return (payments made)	Returns entire order after paying installments	Loan cancelled. Customer receives refund of all payments via PIX.
Partial Return (no payments)	Returns some items, no installments paid	Loan remains active. Return value applied as down payment. Installments recalculated.
Partial Return (balance > return)	Returns items worth less than outstanding balance	Return value applied as down payment. Remaining installments recalculated.
Partial Return (balance < return)	Returns items worth more than outstanding balance	Loan liquidated. Excess amount refunded to customer via PIX.
Return after 20 days	Attempts return outside policy window	Return denied. Loan unchanged.
Non-returnable items	Attempts to return restricted items	Return denied. Loan unchanged.
7-Day Withdrawal	Full return within 7 days of receipt	Full reversal. Customer pays nothing.

Refund Status Lifecycle

  POST /application/{id}/refund
                │
                ▼
        ┌───────────────┐
        │    PENDING     │◄──────────────────────────┐
        │                │                           │
        │  Refund is     │                  Partner resubmits
        │  being         │                  corrected data
        │  processed     │                           │
        └──┬─────┬────┬──┘                           │
           │     │    │                              │
           │     │    └──────────────┐               │
           │     │                   │               │
           ▼     ▼                   ▼               │
  ┌────────────────┐ ┌──────────┐ ┌───────────────────┐
  │LIMIT_RESTORED  │ │  FAILED  │ │ ACTION_REQUIRED   │
  │                │ │          │ │                   │
  │ Customer limit │ │ Refund   │ │ Issue detected.   │
  │ restored.      │ │ could    │ │ Partner calls     │
  │ PIX transfer   │ │ not be   │ │ PUT /refund/{id}  ├───┘
  │ in progress.   │ │ processed│ │ with new pix_key  │
  └───────┬────────┘ └──────────┘ │ (see reason)      │
          │                       └───────────────────┘
          ▼
  ┌──────────┐
  │COMPLETED │
  │          │
  │ Refund   │
  │ fully    │
  │ processed│
  └──────────┘

What happens when a refund reaches LIMIT_RESTORED?

When the refund is validated and the loan recalculation is applied, the customer's BNPL credit limit is restored before the PIX transfer is initiated. This means:

The customer can already use their restored credit limit for new purchases
The PIX refund transfer (if applicable) is still being processed
The refund will transition to COMPLETED once the PIX transfer is confirmed

What happens when a refund is COMPLETED?

COMPLETED is the final state after LIMIT_RESTORED, meaning the PIX transfer has been confirmed. The financial outcome depends on whether the customer has already paid installments:

Situation	What happens
No payments made	Return value is applied as a down payment. Remaining installments are recalculated with a lower amount. No PIX transfer occurs.
Payments made, return value ≤ remaining balance	Return value offsets the outstanding balance. Installments are recalculated. No PIX transfer occurs.
Payments made, return value > remaining balance	Loan is liquidated. The excess amount (overflow) is refunded to the customer via PIX. This is the only scenario that requires a valid `pix_key`.
Full return, payments made	Loan is cancelled. Customer receives a refund of all payments via PIX.

Note: The pix_key field is always required in the request, but a PIX transfer to the customer only occurs when there is an overflow (return value exceeds the remaining balance) or when the customer has already made payments that need to be returned.

When does ACTION_REQUIRED happen?

When the refund requires a PIX transfer to the customer but the provided PIX key is invalid, the status transitions to ACTION_REQUIRED. The partner must collect a corrected PIX key from the customer and resubmit.

Possible reason values:

Reason	Description
`INVALID_PIX_KEY`	The PIX key provided is invalid or malformed
`PIX_KEY_NOT_FOUND`	The PIX key does not exist in the Central Bank registry
`PIX_KEY_TYPE_MISMATCH`	The PIX key type does not match the account holder
`ACCOUNT_CLOSED`	The destination account associated with the PIX key is closed

Request a Refund

POST /application/{application_id}/refund

{
  "amount": 1000,
  "reason": "Customer returned all products",
  "refund_type": "FULL",
  "reason_code": "PRODUCT_RETURN",
  "pix_key": "111.111.111-11",
  "pix_key_type": "CPF",
  "partner_reference_id": "partner-refund-001"
}

Response:

{
  "refund_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "PROCESSING",
  "refunded_at": "2026-01-21T14:00:00Z",
  "partner_reference_id": "partner-refund-001"
}

Partial Refund Example

POST /application/{application_id}/refund

{
  "amount": 400,
  "reason": "Customer returned 1 of 3 items",
  "refund_type": "PARTIAL",
  "reason_code": "PRODUCT_RETURN",
  "pix_key": "[email protected]",
  "pix_key_type": "EMAIL",
  "partner_reference_id": "partner-refund-001"
}

Response:

{
  "refund_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "PROCESSING",
  "refunded_at": "2026-01-21T14:00:00Z",
  "partner_reference_id": "partner-refund-001"
}

Check Refund Status

GET /application/{application_id}/refund/{refund_id}

Completed refund:

{
  "application_id": "7ffd813a-1e88-4a4a-a892-758ca310e607",
  "person_id": "8ffd813a-1e88-4a4a-a892-758ca310e607",
  "refund_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "COMPLETED",
  "reason": null,
  "refund_type": "FULL",
  "offset_amount": 1000.00,
  "refund_amount": 220.00,
  "refunded_at": "2026-01-21T14:00:00Z",
  "completed_at": "2026-01-22T10:00:00Z",
  "partner_reference_id": "partner-refund-001"
}

Action required (invalid PIX key):

{
  "application_id": "7ffd813a-1e88-4a4a-a892-758ca310e607",
  "person_id": "8ffd813a-1e88-4a4a-a892-758ca310e607",
  "refund_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "ACTION_REQUIRED",
  "reason": "INVALID_PIX_KEY",
  "refund_type": "FULL",
  "offset_amount": 1000.00,
  "refund_amount": 0,
  "refunded_at": "2026-01-21T14:00:00Z",
  "completed_at": null,
  "partner_reference_id": "partner-refund-001"
}

Update Refund

When a refund is in ACTION_REQUIRED status, use this endpoint to provide corrected data. The refund will automatically transition back to PENDING and be retried.

PUT /application/{application_id}/refund/{refund_id}

{
  "pix_key": "222.222.222-22",
  "pix_key_type": "CPF"
}

Response:

{
  "application_id": "7ffd813a-1e88-4a4a-a892-758ca310e607",
  "person_id": "8ffd813a-1e88-4a4a-a892-758ca310e607",
  "refund_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "status": "PENDING",
  "reason": null,
  "refund_type": "FULL",
  "offset_amount": 500,
  "refund_amount": 0,
  "refunded_at": "2026-01-22T09:00:00Z",
  "completed_at": null,
  "partner_reference_id": "partner-refund-001"
}

Note: This endpoint only accepts refunds in ACTION_REQUIRED status. Calling it on a refund in any other status will return a 409 Conflict error.

Refund Status Webhook

The system sends a webhook notification (POST /webhooks/refund-status) whenever a refund transitions between states. This is especially useful when the original refund request timed out or returned an error.

{
  "person_id": "8ffd813a-1e88-4a4a-a892-758ca310e607",
  "webhook_type": "refund.status_change",
  "application_id": "7ffd813a-1e88-4a4a-a892-758ca310e607",
  "refund_id": "6ffd813a-1e88-4a4a-a892-758ca310e607",
  "partner_reference_id": "partner-refund-001",
  "previous_status": "PENDING",
  "new_status": "ACTION_REQUIRED",
  "event_datetime": "2026-01-22T11:00:00Z",
  "data": {
    "refund_amount": 0,
    "refund_type": "FULL",
    "offset_amount": 1000,
    "reason": "INVALID_PIX_KEY"
  }
}

When you receive ACTION_REQUIRED, collect a new PIX key from the customer and update the refund using PUT /application/{application_id}/refund/{refund_id}.

Refund Calculation Logic

For partial returns, the return value is applied as a down payment:

New Outstanding Balance = Current Balance - Return Value
New Installment = New Outstanding Balance / Remaining Installments

Example:

Original loan: R$1,100 (10 installments of R$110)
Payments made: 3 installments (R$330)
Outstanding balance: R$770
Item returned: R$300

Result:

New balance: R$770 - R$300 = R$470
Remaining installments: 7
New installment: R$470 / 7 = R$67.14

Note

For returns within 7 days of receipt, the IOF tax is also refunded by QiTech, resulting in a complete transaction reversal.