---
updatedAt: 2026-04-23T18:12:51.000Z
agentTools:
siteIndex: https://developers.pismo.io/llms.txt
projectIndex: https://developers.pismo.io/pismo-docs/llms.txt
---
# 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 Pix reversal (refund) status changed event.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "Instant payments - Pix management",
"description": "API responsible for providing Pix operations (related to DICT) via integrating with external providers",
"contact": {
"name": "API Support",
"url": "https://developers.pismo.io/support/"
},
"license": {
"name": "Copyright Pismo"
},
"version": "0.0.1"
},
"servers": [
{
"url": "https://sandbox.pismolabs.io/pix-dict",
"description": "Sandbox API server for testing."
}
],
"tags": [
{
"name": "Refunds",
"description": "Manage DICT refunds endpoints"
}
],
"components": {
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
},
"parameters": {
"CIDheader": {
"name": "x-cid",
"in": "header",
"schema": {
"type": "string"
},
"description": "The Correlation IDentifier 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.\n",
"example": "B20220921145635222303062944CA66F"
},
"IdempotencyKeyHeader": {
"name": "Idempotency-Key",
"in": "header",
"description": "A unique UUID identifier 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.\n",
"required": true,
"schema": {
"type": "string"
},
"example": "550e8400-e29b-41d4-a716-446655440000"
},
"OrgIDheader": {
"name": "x-tenant",
"in": "header",
"schema": {
"type": "string"
},
"description": "Organization/tenant ID",
"required": true,
"example": "TN-34778262-f4f0-464d-b4c6-a14e2dc6f4be"
}
},
"headers": {
"XCidResponseHeader": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"schemas": {
"AccountNumber": {
"type": "string",
"description": "Account number.",
"maxLength": 20,
"example": "98765432"
},
"AccountType": {
"type": "string",
"enum": [
"CACC",
"SLRY",
"SVGS",
"TRAN"
],
"maxLength": 4,
"description": "Account type: \n `CACC` - Checking account\n `SVGS` - Savings account\n `TRAN` - Transactional account (Brazil only). Also known as \"conta corrente\" in Portuguese, this is a bank account type designed for everyday financial transactions and is the most common type individuals and businesses use for day-to-day banking. \n `SLRY` - Salary account. Employer deposits a fixed amount every month.\n",
"example": "TRAN"
},
"Branch": {
"type": "string",
"description": "Bank-assigned branch ID or ISPB (Identifcador do Sistema de Pagamento Brazil) number - the Brazilian Payment System identifier, an 8-digit value.",
"example": "011"
},
"ContestedParticipant": {
"type": "string",
"maxLength": 8,
"description": "Challenged participant's ISPB (Identifcador do Sistema de Pagamento Brazil) number - the Brazilian Payment System identifier, an 8-digit value.",
"example": "99999011"
},
"CorrelationID": {
"type": "string",
"format": "uuid",
"description": "The correlation identifier is used to link related API requests and events. The Pismo engineering team can use this to track everything related to a call. If one is not passed, it is automatically generated and returned to the client in a response header.\n",
"example": "ea8bc045-9ff7-439f-a318-2e6f974707a5"
},
"EffectiveRefundedAmount": {
"type": "number",
"description": "Actual amount refunded to the user.",
"example": 20.1
},
"FundsRecoveryId": {
"type": "string",
"description": "Funds recovery identifier. \n\nReturned from the [Create funds recovery](https://developers.pismo.io/pismo-docs/reference/post-create-funds-recovery) endpoint.\n",
"example": "53D0F66A-BAB0-49D7-B7DC-807B82AABD8D"
},
"InfractionReportID": {
"type": "string",
"format": "uuid",
"maxLength": 36,
"description": "Infraction report ID (UUID)",
"example": "cfdff46e-5d58-45b8-b7aa-591a65f74444"
},
"message.DetailMessage": {
"type": "object",
"properties": {
"external": {
"type": "array",
"items": {
"$ref": "#/components/schemas/message.ExternalMessage"
}
},
"parameters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/message.ParameterMessage"
}
},
"payload": {
"type": "array",
"items": {
"$ref": "#/components/schemas/message.PayloadMessage"
}
}
}
},
"message.ExternalMessage": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "PBE315"
},
"message": {
"type": "string",
"description": "Error message",
"example": "Generic error"
}
}
},
"message.Message": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "EPDA0001"
},
"details": {
"$ref": "#/components/schemas/message.DetailMessage"
},
"message": {
"type": "string",
"description": "Error message",
"example": "User not found"
}
}
},
"message.ParameterMessage": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "Parameter in error",
"example": "query parameter"
},
"message": {
"type": "string",
"description": "Error message",
"example": "Generic error"
}
}
},
"message.PayloadMessage": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "Field in error",
"example": "Entity.field"
},
"message": {
"type": "string",
"description": "Error messsage",
"example": "Generic error"
}
}
},
"MonitorAccount": {
"type": "boolean",
"description": "Should the account be monitored for suspicious activity?",
"example": false
},
"Participant": {
"type": "string",
"description": "Participant's ISPB (Identifcador do Sistema de Pagamento Brazil) number - the Brazilian Payment System identifier, an 8-digit value.",
"maxLength": 8,
"example": "00115678"
},
"Refund": {
"type": "object",
"required": [
"contested_participant",
"creation_date_time",
"last_modified",
"refund_amount",
"refund_id",
"refund_reason",
"requesting_participant",
"status",
"transaction_id"
],
"properties": {
"contested_participant": {
"$ref": "#/components/schemas/ContestedParticipant"
},
"creation_date_time": {
"type": "string",
"format": "date-time",
"description": "Creation date time. RFC 3339 date-time value.",
"example": "2020-08-13T13:49:03Z"
},
"last_modified": {
"type": "string",
"format": "date-time",
"description": "Last modified date time. RFC 3339 date-time value.",
"example": "2020-08-13T13:49:03Z"
},
"refund_amount": {
"$ref": "#/components/schemas/RefundAmount"
},
"refund_id": {
"type": "string",
"description": "Refund ID",
"example": "12345645-9ff7-439f-a318-2e6f974707a5"
},
"refund_reason": {
"$ref": "#/components/schemas/RefundReason"
},
"requesting_participant": {
"$ref": "#/components/schemas/RequestingParticipant"
},
"status": {
"$ref": "#/components/schemas/RefundStatus"
},
"transaction_id": {
"$ref": "#/components/schemas/RefundTransactionID"
},
"correlation_id": {
"$ref": "#/components/schemas/CorrelationID"
},
"infraction_report_id": {
"$ref": "#/components/schemas/InfractionReportID"
},
"refund_analysis_details": {
"$ref": "#/components/schemas/RefundAnalysisDetails"
},
"refund_analysis_result": {
"$ref": "#/components/schemas/RefundAnalysis"
},
"refund_details": {
"$ref": "#/components/schemas/RefundDetails"
},
"refund_rejection_reason": {
"$ref": "#/components/schemas/RefundRejectionReason"
},
"refund_account": {
"$ref": "#/components/schemas/RefundAccount"
},
"refund_transaction_id": {
"$ref": "#/components/schemas/RefundTransactionID"
},
"funds_recovery_id": {
"$ref": "#/components/schemas/FundsRecoveryId"
},
"monitor_account": {
"$ref": "#/components/schemas/MonitorAccount"
},
"effective_refunded_amount": {
"$ref": "#/components/schemas/EffectiveRefundedAmount"
}
}
},
"RefundAccount": {
"type": "object",
"properties": {
"tax_id_number": {
"$ref": "#/components/schemas/TaxIdNumber"
},
"participant": {
"$ref": "#/components/schemas/Participant"
},
"branch": {
"$ref": "#/components/schemas/Branch"
},
"account_number": {
"$ref": "#/components/schemas/AccountNumber"
},
"account_type": {
"$ref": "#/components/schemas/AccountType"
}
}
},
"RefundAmount": {
"type": "string",
"description": "Refund amount",
"example": "20.10"
},
"RefundAnalysis": {
"type": "string",
"description": "Respondent's refund request analysis result.",
"example": "PARTIALLY_ACCEPTED",
"enum": [
"TOTALLY_ACCEPTED",
"PARTIALLY_ACCEPTED",
"REJECTED"
]
},
"RefundAnalysisDetails": {
"type": "string",
"description": "Refund analysis details",
"example": "Details about the refund analysis."
},
"RefundDetails": {
"type": "string",
"description": "Details about refund",
"maxLength": 2000,
"example": "Details about the refund request"
},
"RefundReason": {
"type": "string",
"description": "Refund reason. \n\n`PIX_AUTOMATICO` means a refund was requested due to failed Automatic Pix operation.\n",
"enum": [
"FRAUD",
"OPERATIONAL_FLAW",
"PIX_AUTOMATICO",
"REFUND_CANCELLED"
],
"example": "OPERATIONAL_FLAW"
},
"RefundRegisterRequest": {
"type": "object",
"required": [
"refund_amount",
"refund_reason",
"transaction_id"
],
"properties": {
"refund_amount": {
"$ref": "#/components/schemas/RefundAmount"
},
"refund_reason": {
"$ref": "#/components/schemas/RefundReason"
},
"transaction_id": {
"$ref": "#/components/schemas/RefundTransactionID"
},
"refund_details": {
"$ref": "#/components/schemas/RefundDetails"
}
}
},
"RefundRejectionReason": {
"type": "string",
"description": "Refund rejecton reason. \n\n**REQUIRED** when `refund_analysis_result` is `REJECTED`.\n",
"enum": [
"NO_BALANCE",
"ACCOUNT_CLOSURE",
"INVALID_REQUEST",
"OTHER"
],
"example": "NO_BALANCE"
},
"RefundStatus": {
"type": "string",
"description": "Refund status",
"enum": [
"OPEN",
"CLOSED",
"CANCELLED"
],
"example": "CLOSED"
},
"RefundTransactionID": {
"type": "string",
"description": "Refund transaction ID",
"example": "E9999901012341234123412345678900"
},
"RequestingParticipant": {
"type": "string",
"maxLength": 8,
"description": "Requesting participant's ISPB (Identifcador do Sistema de Pagamento Brazil) number - the Brazilian Payment System identifier, an 8-digit value.",
"example": "99999011"
},
"TaxIdNumber": {
"type": "string",
"description": "A government document number, such as a Social Security number (US) or Cadastro de Pessoas Físicas number (Brazil). Must be numeric with 11-14 digits.",
"minLength": 11,
"maxLength": 14,
"example": "123412341234"
}
},
"responses": {
"202RefundAccepted": {
"description": "Accepted",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
},
"examples": {
"Request accepted and will processed async": {
"value": {
"code": "EPDA0174",
"message": "Refund flow will continue asynchronously"
}
}
}
}
}
},
"400BadRequest": {
"description": "Bad Request",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
}
}
}
},
"403Forbidden": {
"description": "Forbidden",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
},
"examples": {
"EPDA0009": {
"summary": "Missing required header 'x-tenant'",
"value": {
"code": "EPDA0009",
"message": "Missing required header 'x-tenant'"
}
},
"EPDA0010": {
"summary": "Missing required header 'x-account-id'",
"value": {
"code": "EPDA0010",
"message": "Missing required header 'x-account-id'"
}
},
"EPDA0152": {
"summary": "Missing required param 'id'",
"value": {
"code": "EPDA0152",
"message": "Missing required param 'id'"
}
}
}
}
}
},
"404NotFound": {
"description": "Not Found",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
}
}
}
},
"500InternalServerError": {
"description": "Internal server errpr",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
}
}
}
},
"502BadGateway": {
"description": "Bad Gateway",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
},
"examples": {
"Provider authentication service error": {
"value": {
"code": "EPDG0020",
"message": "Provider authentication service is unable to complete the request"
}
}
}
}
}
},
"504GatewayTimeout2": {
"description": "Gateway Timeout",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
},
"examples": {
"Service timeout": {
"value": {
"code": "EPDA0000",
"message": "Timeout while executing the request"
}
},
"Provider timeout": {
"value": {
"code": "EPDG0000",
"message": "Timeout while executing the request"
}
}
}
}
}
}
}
},
"security": [
{
"BearerAuth": []
}
],
"x-readme": {
"explorer-enabled": true,
"proxy-enabled": true,
"samples-enabled": true
},
"paths": {
"/v2/pix/refunds": {
"post": {
"summary": "Create refund request",
"description": "Create a DICT refund request.\n\nOn PSP timeout, a `202 Accepted` response is returned and the process continues asynchronously, eventually emitting an event if it succeeds. \n\nThis endpoint generates a Pix reversal (refund) status changed event. \n",
"operationId": "post-register-dict-refund",
"tags": [
"Refunds"
],
"parameters": [
{
"$ref": "#/components/parameters/OrgIDheader"
},
{
"$ref": "#/components/parameters/IdempotencyKeyHeader"
},
{
"$ref": "#/components/parameters/CIDheader"
}
],
"requestBody": {
"description": "Request body",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RefundRegisterRequest"
}
}
}
},
"responses": {
"200": {
"description": "Refund registered",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Refund"
}
}
}
},
"202": {
"$ref": "#/components/responses/202RefundAccepted"
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
},
"404": {
"$ref": "#/components/responses/404NotFound"
},
"500": {
"$ref": "#/components/responses/500InternalServerError"
},
"502": {
"$ref": "#/components/responses/502BadGateway"
},
"504": {
"$ref": "#/components/responses/504GatewayTimeout2"
}
},
"security": [
{
"BearerAuth": []
}
]
}
}
}
}
```