Crear un cobro

POST https://api.evetev.com/v1/pagos

Lo que mandas

Campo	Tipo	¿Obligatorio?	Para qué
`merchantId`	uuid	sí	Tu comercio. Sale del id de GET /v1/merchants/me y no cambia.
`montoMinor`	entero	sí	El monto en la unidad mínima de la moneda. En COP son pesos: $ 89.000 es 89000.
`moneda`	"COP" \| "USD"	sí	Hoy solo se transa en COP; USD existe en el contrato pero ninguna pasarela lo procesa todavía.
`referencia`	texto (1–120)	sí	Tu propio identificador del pedido. Es con lo que vas a conciliar de tu lado.
`descripcion`	texto (máx. 255)	no	Lo que el comprador ve en la pantalla de pago.
`urlRetorno`	url https	no	A dónde vuelve este comprador. Tiene que ser de tu sitio registrado o de un subdominio suyo. Si no la mandas, se usa la que registraste en Ajustes.
`pagador`	objeto	no	Datos de quien paga, para cobrar sin que salga de tu web. Si no lo mandas —el caso normal— el cobro devuelve la página de pago alojada.

En pesos colombianos no hay centavos. $ 89.000 se manda como 89000, no como 8900000. Es el error que más plata mueve de sitio al integrar.

La clave de idempotencia

El header Idempotency-Key es obligatorio. Si tu servidor reintenta porque se cayó la red, con la misma clave te devolvemos el cobro que ya existía en vez de crear otro. Usa algo estable y propio del pedido — el número de pedido sirve.

Si reutilizas la misma clave con un cuerpo distinto, responde 409: es la señal de que dos pedidos diferentes están compartiendo clave.

Llevar a cada comprador a su pedido

urlRetorno es opcional. Si no la mandas, el comprador vuelve a la página que registraste en Ajustes. Si la mandas, puedes llevarlo a su propio pedido — y tiene que ser de tu mismo sitio.

Con tu sitio registrado en https://tutienda.co:

urlRetorno	¿Se acepta?
`https://tutienda.co/pedido/4417/gracias`	Sí
`https://pagos.tutienda.co/gracias`	Sí, es un subdominio tuyo
`http://tutienda.co/gracias`	No: tiene que ser https
`https://otro-sitio.co/gracias`	No: no es tu dominio

Lo que te devolvemos

{
  "id": "44444444-4444-4444-8444-444444444444",
  "merchantId": "33333333-3333-4333-8333-333333333333",
  "montoMinor": 89000,
  "moneda": "COP",
  "referencia": "pedido-4417",
  "estado": "pendiente",
  "checkoutUrl": "https://...",
  "creadoEn": "2026-10-04T00:07:51.000Z"
}

Guarda el id contra tu pedido: es con lo que vas a reconocer el aviso cuando llegue. Después redirige al comprador a checkoutUrl.

No hay pasarela en la respuesta, y es a propósito. Tu código no nombra nunca con quién procesamos: así podemos cambiar de proveedor, o sumar otro, sin que toques una línea.

Estados de un cobro

Estado	Qué significa
`creado`, `pendiente`	Todavía nadie ha pagado.
`aprobado`	El banco aprobó. Aquí es cuando despachas.
`fallido`	El pago no se completó.
`conciliado`	Además del pago, la plata ya cuadró con la liquidación.
`reembolsado`	Se le devolvió al pagador.

Puedes consultarlo cuando quieras con GET /v1/pagos/:id, pero no hace falta estar preguntando: para eso está el aviso.