v1

latestOpenAPI 3.1.0Copyright Pismo2026-07-247702,7523.1 MB

Refunds

Create refund request

Create a DICT refund request.

On PSP timeout, a 202 Accepted response is returned and the process continues asynchronously, eventually emitting an event if it succeeds.

This endpoint generates a <a href="https://developers.pismo.io/events/docs/pix-dict-refund-status-change-1">Pix reversal (refund) status changed</a> event.

post/v2/pix/refunds

Headers

x-tenantstring required

Organization/tenant ID

Idempotency-Keystring required

A unique ID to ensure the operation remains idempotent, allowing for operation repitition without causing unintended effects or duplication. An idempotent operation is one that can be applied multiple times, yet the outcome remains the same. it ensures that network errors, retries, or failures can occur without introducing inconsistencies.

x-cidstring

The Correlation ID UUID field links related API requests and events. The x-cid can help the Pismo engineering team track everything related to a call. If not passed, this field is automatically generated.

Request body

refund_amountstring required

Refund amount

refund_reason'FRAUD' | 'OPERATIONAL_FLAW' | 'PIX_AUTOMATICO' | 'REFUND_CANCELLED' required

Refund reason.

PIX_AUTOMATICO means a refund was requested due to failed Automatic Pix operation.

transaction_idstring required

Refund transaction ID

refund_detailsstring

Details about refund

Example request

{
  "refund_amount": "20.10",
  "refund_reason": "OPERATIONAL_FLAW",
  "transaction_id": "E9999901012341234123412345678900",
  "refund_details": "Details about the refund request"
}

Response

Refund registered

contested_participantstring required

Challenged participant's ISPB (Identifcador do Sistema de Pagamento Brazil) number - the Brazilian Payment System identifier, an 8-digit value.

creation_date_timestring date-time required

Creation date time. RFC 3339 date-time value.

last_modifiedstring date-time required

Last modified date time. RFC 3339 date-time value.

refund_amountstring required

Refund amount

refund_idstring required

Refund ID

refund_reason'FRAUD' | 'OPERATIONAL_FLAW' | 'PIX_AUTOMATICO' | 'REFUND_CANCELLED' required

Refund reason.

PIX_AUTOMATICO means a refund was requested due to failed Automatic Pix operation.

requesting_participantstring required

Requesting participant's ISPB (Identifcador do Sistema de Pagamento Brazil) number - the Brazilian Payment System identifier, an 8-digit value.

status'OPEN' | 'CLOSED' | 'CANCELLED' required

Refund status

transaction_idstring required

Refund transaction ID

correlation_idstring

The Correlation identifier field is used to link related API requests and events. The CID can help the Pismo engineering team track everything related to a call. If not passed, a random one is generated. You can find the CID in the response header.

infraction_report_idstring uuid

Infraction report ID (UUID)

refund_analysis_detailsstring

Refund analysis details

refund_analysis_result'TOTALLY_ACCEPTED' | 'PARTIALLY_ACCEPTED' | 'REJECTED'

Respondent's refund request analysis result.

refund_detailsstring

Details about refund

refund_rejection_reason'NO_BALANCE' | 'ACCOUNT_CLOSURE' | 'INVALID_REQUEST' | 'OTHER'

Refund rejecton reason.

REQUIRED when refund_analysis_result is REJECTED.

refund_transaction_idstring

Refund transaction ID

funds_recovery_idstring

Funds recovery identifier.

Returned from the Create funds recovery endpoint.

monitor_accountboolean

Should the account be monitored for suspicious activity?

effective_refunded_amountnumber

Actual amount refunded to the user.

Example response

{
  "contested_participant": "99999011",
  "creation_date_time": "2020-08-13T13:49:03Z",
  "last_modified": "2020-08-13T13:49:03Z",
  "refund_amount": "20.10",
  "refund_id": "12345645-9ff7-439f-a318-2e6f974707a5",
  "refund_reason": "OPERATIONAL_FLAW",
  "requesting_participant": "99999011",
  "status": "CLOSED",
  "transaction_id": "E9999901012341234123412345678900",
  "correlation_id": "c737895c-8159-4c0c-a92a-a4f8600bff37",
  "infraction_report_id": "cfdff46e-5d58-45b8-b7aa-591a65f74444",
  "refund_analysis_details": "Details about the refund analysis.",
  "refund_analysis_result": "PARTIALLY_ACCEPTED",
  "refund_details": "Details about the refund request",
  "refund_rejection_reason": "NO_BALANCE",
  "refund_account": {
    "tax_id_number": "123412341234",
    "participant": "00115678",
    "branch": "011",
    "account_number": "98765432",
    "account_type": "TRAN"
  },
  "refund_transaction_id": "E9999901012341234123412345678900",
  "funds_recovery_id": "53D0F66A-BAB0-49D7-B7DC-807B82AABD8D",
  "effective_refunded_amount": 20.1
}