Solicitar Devolución

Visión General

El endpoint PUT /api/pix/:e2eid/devolucao/:id solicita la devolución de un PIX recibido. Usted informa el End to End ID (e2eid) del PIX original y un identificador de devolución generado por su sistema.

La devolución puede ser total o parcial. La suma de todas las devoluciones no puede superar el valor del PIX original.

Endpoint

PUT https://api.fypay.me/api/pix/{e2eid}/devolucao/{id}

Autenticación

stringobrigatorio

Token Bearer obtenido en POST https://api.fypay.me/api/auth/token. Esta ruta no usa certificado de cliente.

Parámetros de URL

e2eidstringobrigatorio

Identificador del PIX recibido que se va a devolver. Acepta el End to End ID (data.endToEndId del webhook RECEIVE) o el ID numérico de la transacción en FyPay (loc.id del cobro o data.id del webhook).

Ejemplo: E12345678202401151030abcdefghijk

idstringobrigatorio

Identificación generada por su sistema para representar la devolución. Hasta 100 caracteres y única por cuenta: repetir un id ya usado devuelve 400 con el código PIX_DUPLICATE_EXTERNAL_ID.

Ejemplo: D123456789

Request Body

stringobrigatorio

Valor solicitado para devolución. String en formato decimal con exactamente 2 decimales (^\d{1,10}\.\d{2}$).

La suma de los valores de todas las devoluciones no puede superar el valor del PIX original.

Ejemplo: "7.89"

string

Naturaleza de la devolución: ORIGINAL o RETIRADA. Se acepta por compatibilidad con el estándar del Banco Central y se devuelve en la respuesta. Hoy toda devolución se procesa como devolución común, independientemente de este campo.

string

Texto que se mostrará al pagador con información sobre la devolución.

Máximo: 140 caracteres.

Request

curl -X PUT https://api.fypay.me/api/pix/E12345678202401151030abcdefghijk/devolucao/D123456789 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "valor": "7.89",
    "descricao": "Devolución solicitada por el receptor"
  }'

const e2eid = 'E12345678202401151030abcdefghijk';
const devolucionId = 'D123456789';

const response = await fetch(
  `https://api.fypay.me/api/pix/${e2eid}/devolucao/${devolucionId}`,
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      valor: '7.89',
      descricao: 'Devolución solicitada por el receptor',
    }),
  }
);

const devolucion = await response.json();

import requests

e2eid = 'E12345678202401151030abcdefghijk'
devolucion_id = 'D123456789'

response = requests.put(
    f'https://api.fypay.me/api/pix/{e2eid}/devolucao/{devolucion_id}',
    headers={
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json',
    },
    json={
        'valor': '7.89',
        'descricao': 'Devolución solicitada por el receptor',
    }
)

devolucion = response.json()

Response

{
  "id": "D123456789",
  "rtrId": "00000000000000000000000000000789",
  "valor": "7.89",
  "natureza": "ORIGINAL",
  "descricao": "Devolución solicitada por el receptor",
  "horario": {
    "solicitacao": "2024-01-15T10:30:00.000Z"
  },
  "status": "EM_PROCESSAMENTO"
}

{
  "statusCode": 400,
  "code": "PIX_REFUND_EXCEEDS_AVAILABLE",
  "message": "Refund value (R$ 25.00) exceeds available amount to refund (R$ 20.00)",
  "userMessage": "Valor do reembolso excede o valor disponível.",
  "errorId": "c0a8012e-7b1f-4c55-9d1e-2f9a8c3b4d5e"
}

{
  "statusCode": 404,
  "code": "PIX_TRANSACTION_NOT_FOUND",
  "message": "Transaction with e2eId E12345678202401151030abcdefghijk not found",
  "userMessage": "Transação não encontrada.",
  "errorId": "c0a8012e-7b1f-4c55-9d1e-2f9a8c3b4d5e"
}

Campos de la Respuesta

idstring

Identificación de la devolución (el mismo valor enviado en la URL).

rtrIdstring

Identificador de la devolución en FyPay: el ID interno de la transacción de devolución, completado con ceros a la izquierda hasta 32 caracteres. No es el End to End ID de la devolución; ese llega en data.refunds[0].endToEndId en el webhook REFUND.

valorstring

Valor de la devolución, string con 2 decimales.

naturezastring

El valor de natureza enviado (ORIGINAL o RETIRADA), u ORIGINAL si se omitió.

descricaostring

El texto de descricao enviado, cuando exista.

horarioobject

statusstring

Estado de la devolución en el momento de la respuesta:

EM_PROCESSAMENTO: devolución en procesamiento (caso normal)
DEVOLVIDO: devolución ya liquidada
NAO_REALIZADO: la devolución falló

motivostring

Presente solo cuando status = NAO_REALIZADO, con el texto Erro ao processar devolução.

El resultado final de la devolución llega por el webhook REFUND, en las URLs registradas para el evento refund_in con el formato PIX BACEN.

Webhook de Devolución

Cuando se procesa la devolución, usted recibe un webhook del tipo REFUND (fragmento):

{
  "data": {
    "id": 12345,
    "txId": "7978c0c97ea847e78e8849634473c1f1",
    "status": "REFUNDED",
    "payment": {
      "amount": "100",
      "currency": "BRL"
    },
    "refunds": [
      {
        "status": "LIQUIDATED",
        "payment": {
          "amount": 7.89,
          "currency": "BRL"
        },
        "errorCode": null,
        "eventDate": "2024-01-15T10:30:00.000Z",
        "endToEndId": "D12345678202401151030abcdefghijk",
        "information": "Devolución solicitada por el receptor"
      }
    ],
    "endToEndId": "E12345678202401151030abcdefghijk",
    "creditDebitType": "DEBIT"
  },
  "type": "REFUND"
}

await solicitarDevolucion(e2eid, 'DEV001', '30.00');

await solicitarDevolucion(e2eid, 'DEV002', '50.00');

await solicitarDevolucion(e2eid, 'DEV003', '25.00');

Si el PIX original fue de R$ 100,00, las dos primeras suman R$ 80,00 y la tercera falla con 400 PIX_REFUND_EXCEEDS_AVAILABLE, porque solo quedan R$ 20,00 por devolver.

Errores Comunes

Código HTTP	`code`	Causa
400	`PUB_REQUEST_BODY_INVALID`	`valor` fuera de formato, `natureza` inválida o `descricao` con más de 140 caracteres
400	`PIX_DUPLICATE_EXTERNAL_ID`	`id` de devolución ya usado en esta cuenta
400	`PIX_REFUND_EXCEEDS_AVAILABLE`	Valor superior al saldo aún disponible para devolución
400	`PIX_REFUND_DEADLINE_EXCEEDED`	Más de 89 días desde el PIX original
400	`PIX_INVALID_TRANSACTION_TYPE_FOR_REFUND`	La transacción no es un PIX recibido
400	`PIX_INVALID_TRANSACTION_STATE`	La transacción original no está en un estado que permita devolución
400	`PIX_TRANSACTION_ACCOUNT_MISMATCH`	La transacción pertenece a otra cuenta
401		Token ausente, inválido o expirado
404	`PIX_TRANSACTION_NOT_FOUND`	No se encontró ningún PIX para el `e2eid` informado

Solicitar Devolución

Visión General

Endpoint

Autenticación

Parámetros de URL

Request Body

Request

Response

Campos de la Respuesta

Webhook de Devolución

Webhook REFUND

Plazo para Devolución

Devoluciones Parciales

Errores Comunes

Próximos Pasos

Transferencia PIX

Webhook REFUND

En esta página

Solicitar Devolución

Propiedades

Webhook REFUND

Transferencia PIX

Webhook REFUND

En esta página