Saltar al contenido principal

Consultar Retiro

Utilice este endpoint para consultar un retiro específico por su id.

Entornos Disponibles​

https://api.gateway.com.br/core

Endpoint​

  • Método: GET
  • Endpoint: /withdrawal/{id}
  • Autenticación: Bearer token

Path Params​

NombreTipoObligatorioDescripciónValidaciones
idstring (UUID)SíIdentificador del retiroDebe ser un UUID válido

Ejemplo de Solicitud​

curl --request GET \
--url https://api.gateway.com.br/core/withdrawal/553e8400-e29b-41d4-a716-436251480000 \
--header 'Authorization: Bearer su-token-jwt'

Respuesta Exitosa​

CampoTipoObligatorioDescripción
idstring (UUID)SíIdentificador único del retiro
acquirerCodestringNoCódigo del adquirente
acquirerstringSíAdquirente del retiro
amountnumberSíMonto del retiro (entero, en centavos)
methodstring (enum) - PIXSíMétodo del retiro
webhookUrlstringNoURL de webhook configurada
externalCodestringNoSu código de referencia
paymentReceiptobjectNoComprobante de pago (ver Sub-Objeto PaymentReceiptUrl)
refundReceiptobjectNoComprobante de reembolso (ver Sub-Objeto PaymentReceiptUrl)
createdAtstring (ISO)SíFecha de creación
statusstring (enum) - PENDING, PROCESSING, PROCESSED, FAILED, CANCELED, REFUNDED, REJECTED, PENDING_COMPLIANCESí
  • PENDING: Retiro creado, en espera de procesamiento
  • PROCESSING: Retiro en procesamiento
  • PROCESSED: Retiro procesado con éxito
  • FAILED: Error en el procesamiento
  • CANCELED: Retiro cancelado
  • REFUNDED: Retiro reembolsado
  • REJECTED: Retiro rechazado por el gateway
  • PENDING_COMPLIANCE: Retiro pendiente de revisión de compliance
statusHistoryarraySíHistorial de estados (ver Sub-Objetos StatusHistory)
updatedAtstring (ISO)SíFecha de la última actualización
amountWithdrawnnumberNoMonto efectivamente retirado
processedDatestring (ISO)NoFecha de procesamiento
errorMessagestringNoMensaje de error
endToEndstringNoIdentificador end-to-end del retiro
endToEndRefundstringNoIdentificador end-to-end del reembolso
refundDatestring (ISO)NoFecha del reembolso
refundAmountnumberNoMonto del reembolso (entero, en centavos)
payerobjectNoDatos del pagador (ver Sub-Objetos AccountHolder)
receiverobjectNoDatos del receptor (ver Sub-Objetos AccountHolder)
pixKeyobjectNoDatos de la clave PIX (ver Sub-Objetos PixKeyVo)
trackingKeystringNoClave de rastreo del SPEI. En retiros PIX siempre viene null
feeAmountnumberNoMonto de la comisión

Sub-Objetos​

StatusHistory (elemento)​

CampoTipoObligatorioDescripción
statusstring (enum) - PENDING, PROCESSING, PROCESSED, FAILED, CANCELED, REFUNDED, REJECTED, PENDING_COMPLIANCESíEstado del retiro
datestring (ISO)SíFecha del estado
durationInMillisecondsnumberSíDuración del estado en milisegundos

AccountHolder​

CampoTipoObligatorioDescripción
typestring (enum) - PF, PJSíTipo de titular
namestringSíNombre del titular
documentstringSíDocumento del titular
bankAccountobjectSíDatos bancarios (ver Sub-Objetos BankAccount)
pixobjectSíClave PIX del titular (ver Sub-Objetos PixKeyVo)

BankAccount​

CampoTipoObligatorioDescripción
typestringSíTipo de cuenta
digitstringSíDígito de la cuenta
ispbstringSíISPB del banco

PixKeyVo​

CampoTipoObligatorioDescripción
keystringSíClave PIX
typestring (enum) - CPF, CNPJ, EMAIL, PHONE, EVPSíTipo de la clave PIX

PaymentReceiptUrl​

CampoTipoObligatorioDescripción
urlstringSíURL del comprobante
expirationDatestring (ISO)SíFecha de expiración del comprobante

Ejemplo de Respuesta​

Datos enmascarados

Los valores sensibles pueden estar enmascarados con ***.

{
  "id": "553e8400-e29b-41d4-a716-436251480000",
  "acquirerCode": "ACQ-123",
  "acquirer": "ACQUIRER_EXEMPLO",
  "amount": 10000,
  "method": "PIX",
  "webhookUrl": "https://sua-api.com/webhooks/withdrawal",
  "externalCode": "SAQUE-123",
  "paymentReceipt": {
    "url": "https://files.exemplo.com.br/receipts/withdrawal-553e8400-e29b-41d4-a716-436251480000.pdf",
    "expirationDate": "2026-04-01T00:00:00.000Z"
  },
  "refundReceipt": {
    "url": "https://files.exemplo.com.br/receipts/withdrawal-refund-553e8400-e29b-41d4-a716-436251480000.pdf",
    "expirationDate": "2026-04-01T00:00:00.000Z"
  },
  "createdAt": "2026-03-06T12:49:04.681Z",
  "status": "REFUNDED",
  "statusHistory": [
    {
      "status": "PENDING",
      "date": "2026-03-06T12:49:04.681Z",
      "durationInMilliseconds": 1000
    },
    {
      "status": "PROCESSING",
      "date": "2026-03-06T12:49:04.681Z",
      "durationInMilliseconds": 10000
    },
    {
      "status": "PROCESSED",
      "date": "2026-03-06T12:49:04.681Z",
      "durationInMilliseconds": 10000
    },
    {
      "status": "REFUNDED",
      "date": "2026-03-06T12:49:04.681Z",
      "durationInMilliseconds": 5000
    }
  ],
  "updatedAt": "2026-03-06T12:49:04.681Z",
  "amountWithdrawn": 10000,
  "processedDate":  "2026-03-06T12:49:04.681Z",
  "errorMessage": "Falha ao registrar o estorno no PSP",
  "endToEnd": "0123456789",
  "endToEndRefund": "0123456789-REFUND",
  "refundDate": "2026-03-06T14:49:04.681Z",
  "refundAmount": 10000,
  "payer": {
    "type": "PF",
    "name": "Fulano de Tal",
    "document": "***456789**",
    "bankAccount": {
      "type": "CHECKING",
      "digit": "7",
      "ispb": "12345678"
    },
    "pix": {
      "key": "12345678910",
      "type": "CPF"
    }
  },
  "receiver": {
    "type": "PJ",
    "name": "Empresa Exemplo LTDA",
    "document": "12345678000199",
    "bankAccount": {
      "type": "CHECKING",
      "digit": "0",
      "ispb": "12345678"
    },
    "pix": {
      "key": "contato@exemplo.com",
      "type": "EMAIL"
    }
  },
  "pixKey": {
    "key": "12345678910",
    "type": "CPF"
  },
  "feeAmount": 150
}

Errores Posibles​

CódigoDescripciónSolución
401Credenciales inválidasVerifique sus credenciales
403Sin permiso/autorizaciónContacte al soporte
404Registro no encontradoVerifique el id informado
422Datos inválidos o faltantesVerifique el formato de los datos
422ValidacionesContacte al soporte
500Error internoContacte al soporte