# Request Refund

Requests a full refund of a paid Cash-In transaction (PIX Devolution via BACEN/SPI).

> ⚠️ Important: Only transactions with status PAID can be refunded. Partial refunds are not supported — the full original amount will be returned to the payer.

The refund is sent to the banking network synchronously. The 202 Accepted response includes the new endToEndId generated for the devolution (prefixed with D).

This endpoint requires the DigitalSignature header. See the Authentication Guide for details on how to compute it.

Endpoint: POST /cash-in/{id}/refund
Version: 2.0.0
Security: bearerAuth

## Header parameters:

  - `ApplicationToken` (string, required)
    Fixed GUID that uniquely identifies your integration. Provided during ConnectPSP onboarding.
    Example: "{{ApplicationToken}}"

  - `DigitalSignature` (string, required)
    HMAC-SHA256 hash of the JWT token + your CryptoToken. Required for sensitive operations.
See the Authentication Guide for the exact computation steps.
    Example: "{{DigitalSignature}}"

  - `X-Idempotency-Key` (string)
    A client-generated UUID v4 to guarantee idempotency. If the same key is sent twice, the second request returns the original response without creating a duplicate transaction.
Strongly recommended for all POST operations.
    Example: "550e8400-e29b-41d4-a716-446655440000"

## Path parameters:

  - `id` (string, required)
    Transaction identifier — TxId, InternalCode, or EndToEndId.
    Example: "US7B1JQ"

## Request fields (application/json):

  - `reason` (string, required)
    Reason for the refund.
    Enum: "FRAUD", "DUPLICATED_PAYMENT", "CUSTOMER_REQUEST", "MERCHANT_ERROR"

  - `description` (string)
    Optional internal note for audit purposes (not sent to payer).
    Example: "Customer requested refund via support ticket #1234."

## Response 202 fields (application/json):

  - `transactionId` (string)
    Example: "kk6g232xel65a0daee4dd13kk2912714964"

  - `internalCode` (string)
    Example: "US7B1JQ"

  - `externalReference` (string)
    Example: "order_abc123"

  - `endToEndId` (string)
    New E2E ID for this devolution (starts with D).
    Example: "D00416968202603101827cemeFscF6AG"

  - `status` (string)
    Enum: "PROCESSING"

  - `amount` (number)
    Example: 150.5

  - `requestedAt` (string)
    Example: "2026-03-10T13:30:00-03:00"

  - `message` (string)
    Example: "The refund for cash-in US7B1JQ has been successfully initiated."

## Response 401 fields (application/problem+json):

  - `type` (string)
    URI identifying the error type.
    Example: "https://connect-psp.redocly.app/errors/insufficient-funds"

  - `title` (string)
    Short, human-readable summary.
    Example: "Insufficient Funds"

  - `status` (integer)
    HTTP status code.
    Example: 422

  - `code` (string)
    Machine-readable error code for programmatic handling.
    Example: "INSUFFICIENT_FUNDS"

  - `detail` (string)
    Human-readable explanation of this specific occurrence.
    Example: "The requested amount of R$ 500.00 exceeds available balance of R$ 100.00."

## Response 404 fields (application/problem+json):

  - `type` (string)
    URI identifying the error type.
    Example: "https://connect-psp.redocly.app/errors/insufficient-funds"

  - `title` (string)
    Short, human-readable summary.
    Example: "Insufficient Funds"

  - `status` (integer)
    HTTP status code.
    Example: 422

  - `code` (string)
    Machine-readable error code for programmatic handling.
    Example: "INSUFFICIENT_FUNDS"

  - `detail` (string)
    Human-readable explanation of this specific occurrence.
    Example: "The requested amount of R$ 500.00 exceeds available balance of R$ 100.00."

## Response 422 fields (application/problem+json):

  - `type` (string)
    URI identifying the error type.
    Example: "https://connect-psp.redocly.app/errors/insufficient-funds"

  - `title` (string)
    Short, human-readable summary.
    Example: "Insufficient Funds"

  - `status` (integer)
    HTTP status code.
    Example: 422

  - `code` (string)
    Machine-readable error code for programmatic handling.
    Example: "INSUFFICIENT_FUNDS"

  - `detail` (string)
    Human-readable explanation of this specific occurrence.
    Example: "The requested amount of R$ 500.00 exceeds available balance of R$ 100.00."