Close a Refund Request

Use this endpoint to provide the closure decision and outcome for a refund request.

Notes:

• This operation is typically triggered by BACEN’s analysis completion.
• Closing a request sets its status to CLOSED and records the analysis result.
• For accepted refunds, a refund transaction ID is recorded.
• Once closed, the request cannot be modified.

POST /v1/dict/refund-requests/{refund_id}/close

Close a Refund Request

cURL

curl --request POST \
  --url https://api.example.com/v1/dict/refund-requests/{refund_id}/close \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "effectiveRefundedAmount": "50.25",
  "refundAnalysisResult": "TOTALLY_ACCEPTED",
  "refundAnalysisDetails": "Analysis confirms fraud. Refund approved.",
  "refundRejectionReason": "NO_BALANCE",
  "refundTransactionId": "E98765432202411241500REFUNDTRANS"
}
'

200

{
  "accountId": "550e8400-e29b-41d4-a716-446655440000",
  "bacenRefundRequestId": "3d48532f-a1b2-4422-81c3-b7dc852e262b",
  "contestedParticipant": "12345678",
  "createdAt": "2024-01-15T10:30:00Z",
  "id": "550e8400-e29b-41d4-a716-44665544r001",
  "refundAmount": "100.50",
  "refundReason": "FRAUD",
  "requestingParticipant": "30306294",
  "status": "OPEN",
  "transactionId": "E12345678202411241430ABCDEFGHIJK",
  "updatedAt": "2024-01-15T10:30:00Z",
  "analysisDetails": "Analysis confirms fraud. Refund approved.",
  "analysisResult": "TOTALLY_ACCEPTED",
  "bacenFundsRecoveryId": "91d65e98-97c0-4b0f-b577-73625da1f9fc",
  "effectiveRefundedAmount": "100.00",
  "infractionReportId": "550e8400-e29b-41d4-a716-44665544f001",
  "monitorAccount": true,
  "refundAccount": {
    "accountNumber": "123456",
    "accountType": "CACC",
    "branch": "0001",
    "document": "12345678909",
    "participant": "99999011"
  },
  "refundDetails": "Customer reports unauthorized transaction",
  "refundRejectionReason": "NO_BALANCE",
  "refundTransactionId": "E98765432202411241500REFUNDTRANS"
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Parámetros de ruta

refund_id · string<uuid> · requerido

Refund Request ID (UUID format)

Cuerpo

application/json

effectiveRefundedAmount · string · requerido

Amount effectively refunded in BRL (format: 0.00 to 9999999999.99). May differ from the requested amount for PARTIALLY_ACCEPTED

Minimum string length: 1

Ejemplo:

"50.25"

refundAnalysisResult · enum<string> · requerido

Analysis result

Opciones disponibles: TOTALLY_ACCEPTED, PARTIALLY_ACCEPTED, REJECTED

Minimum string length: 1

Ejemplo:

"TOTALLY_ACCEPTED"

refundAnalysisDetails · string

Analysis comments. Max 2000 characters. Required if result is REJECTED and rejection reason is INVALID_REQUEST

Maximum string length: 2000

Ejemplo:

"Analysis confirms fraud. Refund approved."

refundRejectionReason · enum<string>

Rejection reason. Required if result is REJECTED

Opciones disponibles: NO_BALANCE, ACCOUNT_CLOSURE, INVALID_REQUEST, OTHER,

Ejemplo:

"NO_BALANCE"

refundTransactionId · string

Transaction ID for executing refund. Required if result is TOTALLY_ACCEPTED or PARTIALLY_ACCEPTED

Ejemplo:

"E98765432202411241500REFUNDTRANS"

Respuesta

200

application/json

OK

accountId · string · requerido

Account ID (UUID) of the contested Pix transfer when the request arrived through BTG; empty when it was opened through this API or the plugin could not resolve the contested transfer

Ejemplo:

"550e8400-e29b-41d4-a716-446655440000"

bacenRefundRequestId · string · requerido

BACEN/BTG refund request external identifier

Ejemplo:

"3d48532f-a1b2-4422-81c3-b7dc852e262b"

contestedParticipant · string · requerido

ISPB of the contested participant (8 uppercase alphanumeric characters)

Ejemplo:

"12345678"

createdAt · string<date-time> · requerido

Creation timestamp (ISO 8601 UTC)

Ejemplo:

"2024-01-15T10:30:00Z"

id · string · requerido

Unique identifier of the refund request (UUID)

Ejemplo:

"550e8400-e29b-41d4-a716-44665544r001"

refundAmount · string · requerido

Refund amount in BRL (format: 0.00)

Ejemplo:

"100.50"

refundReason · enum<string> · requerido

Reason for the refund

Opciones disponibles: FRAUD, OPERATIONAL_FLAW, REFUND_CANCELLED

Ejemplo:

"FRAUD"

requestingParticipant · string · requerido

ISPB of the requesting participant (8 uppercase alphanumeric characters)

Ejemplo:

"30306294"

status · enum<string> · requerido

Current status of the refund request

Opciones disponibles: OPEN, CLOSED, CANCELLED

Ejemplo:

"OPEN"

transactionId · string · requerido

Pix End-to-End transaction ID (32 characters)

Ejemplo:

"E12345678202411241430ABCDEFGHIJK"

updatedAt · string<date-time> · requerido

Last update timestamp (ISO 8601 UTC)

Ejemplo:

"2024-01-15T10:30:00Z"

analysisDetails · string

Analysis comments (max 2000 characters)

Ejemplo:

"Analysis confirms fraud. Refund approved."

analysisResult · enum<string>

Analysis result (if closed)

Opciones disponibles: TOTALLY_ACCEPTED, PARTIALLY_ACCEPTED, REJECTED

Ejemplo:

"TOTALLY_ACCEPTED"

bacenFundsRecoveryId · string

BACEN/BTG funds-recovery identifier resolved via the associated infraction report (read-only, JOIN-derived)

Ejemplo:

"91d65e98-97c0-4b0f-b577-73625da1f9fc"

effectiveRefundedAmount · string

Amount effectively refunded in BRL

Ejemplo:

"100.00"

infractionReportId · string

Related infraction report ID (UUID)

Ejemplo:

"550e8400-e29b-41d4-a716-44665544f001"

monitorAccount · boolean

BACEN flag for account monitoring

Ejemplo:

true

refundAccount · object

Refund destination account details

Show child attributes

refundDetails · string

Detailed justification (max 2000 characters)

Ejemplo:

"Customer reports unauthorized transaction"

refundRejectionReason · enum<string>

Rejection reason (if rejected)

Opciones disponibles: NO_BALANCE, ACCOUNT_CLOSURE, INVALID_REQUEST, OTHER

Ejemplo:

"NO_BALANCE"

refundTransactionId · string

Refund transaction ID (if accepted, 32 characters)

Ejemplo:

"E98765432202411241500REFUNDTRANS"