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.
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
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
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.
El cliente pide un reembolso
El endToEndId del pago
Pix de vuelta a quien pagó
Leído por su id
Al cliente, en el chat
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.
El código, y lo que supone.
// 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.
POST /v1/consumers/{consumerId}/pix/devolutionsDevuelve 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.
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.