# 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. |
| `monto` | entero | sí | El monto, entero y sin decimales. En COP son PESOS: $ 89.000 se manda como 89000. Se llamaba montoMinor hasta el 4-oct-2026; el nombre venía de «unidad mínima de la moneda» y se entendía al revés, porque quien viene de otras pasarelas lee «minor» y entiende centavos. |
| `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

```json
{
  "id": "44444444-4444-4444-8444-444444444444",
  "merchantId": "33333333-3333-4333-8333-333333333333",
  "monto": 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.

## Con qué puede pagar tu cliente

No eliges el método al crear el cobro: el comprador lo elige en la pantalla de pago. Hoy están disponibles:

| Método       | Cómo es                                                                                     |
| ------------ | ------------------------------------------------------------------------------------------- |
| **PSE**      | Débito desde la cuenta bancaria. Es el más usado en Colombia.                               |
| **Tarjeta**  | Crédito y débito. El número de la tarjeta **nunca pasa por tu servidor ni por el nuestro**. |
| **Efectivo** | El comprador recibe un volante y paga en una red física. Puede tardar días.                 |

El efectivo cambia una cosa de tu lado: el cobro se queda `pendiente` hasta que la persona vaya a pagar. No asumas que un cobro sin aprobar en diez minutos está perdido.

> Si necesitas que el comprador no salga de tu web —elegir el banco de PSE en tu propio formulario— eso existe y se llama checkout propio. Escríbenos: necesita que te habilitemos el modo y que mandes los datos del pagador en el cobro.

## 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](/webhooks).