Skip to main content
Todos los casos de uso
PosventaOperations

Un reembolso que solo puede volver de donde vino el dinero.

El cliente reclama en el chat de soporte. El agente encuentra el endToEndId del pago y le pide a CodeSpar devolver el Pix: el dinero vuelve a quien pagó, y el reembolso nunca puede superar lo que queda por devolver de ese pago. Cada reembolso lleva una clave de idempotencia, así un reintento es el mismo reembolso. El reembolso no se verifica contra un mandato ni un tope; el pago original es su límite. Emitir una nota de crédito y consultar el pedido en tu ERP son tu integración.

AntesTicket → alguien con acceso al banco → transferencia manual
DespuésEl agente devuelve el Pix a quien pagó, limitado al pago
Pix ↩
de vuelta a quien pagó, como máximo el monto original
Pruébalo en el Sandbox
MD06
Motivo de la devolución
Devolución a pedido del usuario, el código por defecto
≤
Límite
Nunca más de lo que queda por devolver del crédito original
idempotency_key
Mismo reembolso en un reintento
La clave de idempotencia hace del reintento el mismo reembolso
Pix ↩
Pagador original
El dinero vuelve a quien pagó, por el mismo riel
Ejemplo ilustrativo · datos de demostración

El reembolso, desde el chat.

Un ejemplo con datos de demostración: el cliente pide un reembolso en el chat de soporte; el agente encuentra el pago Pix y le pide a CodeSpar devolverlo a quien pagó. La conversación está en portugués, como la escribió el cliente.

  • El reembolso vuelve a quien pagó, por el mismo riel
  • Nunca más de lo que queda por devolver del pago
  • No se verifica contra un mandato ni un tope: el pago es el límite
Marina · pedido #8421
Suporte · Pix
Agente
Oi! O pedido #8421 veio errado, quero o estorno.
Encontrei o pagamento Pix de R$ 186,00 do pedido #8421. Devolvo para a mesma conta que pagou, ok?
Pode sim.
Devolução solicitada.
DevoluçãoR$ 186,00 · Pix
MotivoMD06
Idempotênciarefund-8421
via pix/devolutions · Celcoin
✓ devolução solicitada · exemplorefund-8421
El problema

La conversación es la parte fácil.

Los reembolsos son donde soporte se encuentra con el dinero: el ticket espera a alguien con acceso al banco, la transferencia manual no coincide con el pago original y después nadie puede decir qué se devolvió.

Escalar cada reembolso a quien tiene el acceso al banco

El agente devuelve el Pix por la API, con su propia clave de API

Una transferencia manual que no coincide con el pago original

El reembolso cita el endToEndId del pago y vuelve a quien pagó

Reembolsar dos veces después de un timeout

La clave de idempotencia hace del reintento el mismo reembolso

Devolver más de lo que se pagó

El reembolso no puede superar lo que queda por devolver del pago

Cómo lo hace el agente

Un reembolso limitado por el pago.

El agente llama a POST /v1/consumers/{consumerId}/pix/devolutions con el end_to_end_id del pago, el monto en centavos y una clave de idempotencia; un GET sobre la devolución lee su estado. El reembolso vuelve a quien pagó y queda limitado por lo que queda por devolver de ese crédito. No consume un mandato. Consultar el pedido, emitir una nota de crédito y avisarle al cliente son tu integración.

01
Ticket
Chat de soporte

El cliente pide un reembolso

02
Encontrar
Tu sistema de pedidos

El endToEndId del pago

03
Devolver
pix/devolutions

Pix de vuelta a quien pagó

04
Estado
pix/devolutions

Leído por su id

05
Avisar
Tu integración

Al cliente, en el chat

Arquitectura

El ticket entra por tu canal de soporte. El agente resuelve el pedido y su pago Pix en tus sistemas y llama a la ruta de devolución con el endToEndId. CodeSpar verifica el pago contra el extracto del propio consumidor, rechaza una segunda devolución del mismo dinero, revierte el asiento de la billetera y envía la devolución por Celcoin; su estado se lee en la misma ruta. No se consume un mandato: la devolución queda atada a quien pagó y limitada por el crédito original.

En código

El código, y lo que supone.

support-refund.ts
// Prerequisites: CODESPAR_API_KEY set to a test key (csk_test_…), a consumer
// (user_0000) whose wallet received the Pix, and that payment's endToEndId.
import { CodeSpar } from "@codespar/sdk";

const cs = new CodeSpar();

// return R$ 186.00 of the payment to its payer; never more than what is left to return
const res = await cs.api.response("post", "/v1/consumers/{consumerId}/pix/devolutions", {
  path: { consumerId: "user_0000" },
  body: { end_to_end_id: "E00000000202610081200abcdef123456", amount_minor: 18_600, idempotency_key: "refund-8421" },
});
console.log(res.status, res.ok ? res.data : null);

Ejemplo con el SDK publicado (@codespar/sdk 0.16.11). Los requisitos están en los comentarios. Compilar no prueba la integración: ejecútalo primero en modo de prueba.

Herramientas destacadas
POST /v1/consumers/{consumerId}/pix/devolutions

Devuelve un Pix recibido a quien pagó, por endToEndId, limitado al crédito original, con clave de idempotencia obligatoria.

GET /v1/consumers/{consumerId}/pix/devolutions/{devolutionId}

Lee el estado de la devolución.

Ver la referencia de meta-tools
Servidores MCP conectados

Empieza con una clave de prueba.

Las claves de prueba son gratuitas. Abre el sandbox, conecta los proveedores que usa tu proyecto y mira qué herramientas puede llamar antes de construir.

Agente de reembolsos de soporte — CodeSpar | CodeSpar