Skip to main content

Create transaction refund

POST 
/v1/payin/:id/refunds
Tag: api-payments-gateway-post-payin-refundDescription: Creates a partial or total refund for an already authorized or settled transactionAuthentication: Required via JWT Bearer tokenProcess: 1. Validate user authentication and input parameters 2. Verify transaction exists and belongs to the user 3. Validate transaction status (AUTHORIZED or SETTLED) 4. Confirm minimum waiting period (1 day after authorization) 5. Check if within maximum refund deadline 6. Calculate available refund amount considering previous refunds 7. Create refund request with PENDING status 8. Send for asynchronous processing to payment gatewayBusiness Rules: - Accepted statuses: AUTHORIZED (after 1 day), SETTLED - Rejected statuses: WAITING, PENDING, CANCELLED, DECLINED - Minimum period: 1 day after authorization - Maximum period: Before cancellation deadline - Maximum amount: Cannot exceed remaining available amount - Multiple refunds: Allowed until original amount is exhaustedImportant: For recent transactions (less than 1 day), use the cancellation endpoint which allows immediate reversal.

Request​

Path Parameters

    id uuidrequired

    Unique identifier of the transaction to be refunded

      <b>Format</b>: UUID v7
      <b>Validation</b>: Must exist and belong to the authenticated user

Header Parameters

    x-wallet-uuid string

    Sender Wallet UUID (if empty, your default Wallet UUID will be settled)

    x-transaction-uuid stringrequired

    The transaction ID is a UUID (v7) used to uniquely identify the object that will be created. All objects must have an identifier.

    nonce stringrequired

    The nonce ID is a UUID (v4) used to uniquely identify the request. All requests must have an identifier.

    x-lang string

    Possible values: [pt-BR, en-US]

    Indicates the preferred language. Defaults to Brazilian Portuguese if unspecified.

    x-product-uuid string

    The product ID is a UUID (v4) used to identify the Z.ro product configuration.

    x-product-target-user-uuid string

    The product target user ID is a UUID (v4) used to identify what user account this request must be executed. Require: x-product-uuid.

Body

required
    amount_total integerrequired

    Possible values: <= 9007199254740991

    Refund amount in cents

      <b>Format</b>: Positive integer
      <b>Example</b>: 10000 (equals $ 100.00)
      <b>Validation</b>: Must be positive and not exceed available amount
      <b>Restrictions</b>:
      - Maximum: Remaining amount available for refund
      - Multiple refunds: Sum cannot exceed original amount
      <b>Available calculation</b>: Original amount - sum of all previous refunds

Responses​

✅ Refund request created successfully

  <b>Returns</b>: Created refund request object
  <b>Initial status</b>: PENDING (awaiting asynchronous processing)
  <b>Next steps</b>: Monitor status via webhook or subsequent query
Schema
    id uuidrequired

    Unique identifier of the refund request Format: UUID v7 Usage: For tracking refund status Important: This is the refund ID, not the original transaction ID

    status stringrequired

    Possible values: [PENDING, WAITING, ACCEPTED, DECLINED, FAILED, ERROR]

    Current status of the refund request

      <b>Initial value</b>: PENDING (awaiting processing)
      <b>Updates</b>: Via webhook or subsequent query
      <b>Flow</b>: PENDING → WAITING → ACCEPTED/DECLINED
    created_at date-timerequired

    Creation date of the refund request

    updated_at date-timerequired

    Last update date of the request

Loading...