> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hurrypayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Crear un checkout

> Crea un pedido en Hurry y obtén la URL del checkout a la que redirigir al comprador.

Este endpoint crea un pedido, elige la pasarela de cobro de tu tienda y te devuelve la URL del checkout. Tu web solo tiene que redirigir al comprador a esa URL.

* **Autenticación:** no hace falta. La tienda se identifica por `shopUrl`.
* **Importes:** en céntimos (la unidad mínima de la moneda). `2500` son 25,00 €.

> [!WARNING]
>
> Los errores se devuelven como **HTTP 200 con `redirectUrl: null`**. No basta con mirar el código HTTP: comprueba siempre que `redirectUrl` venga informado antes de redirigir.

***

## Cuerpo de la petición

**externalId** `string` *required*

Id del carrito o del pedido en tu sistema. Hace que la llamada sea idempotente: si la repites con el mismo valor, recibes el mismo pedido. Consulta [Idempotencia](#idempotencia).

**shopUrl** `string` *required*

URL de la tienda tal como está dada de alta en Hurry. Tiene que coincidir **exactamente**, carácter a carácter, con una tienda activa. Si falta o no coincide, no se crea el pedido.

**items** `Item[]` *required*

Líneas del carrito. No puede estar vacío.

**propiedades de Item**

**name** `string` *required*

Nombre del producto.

**unitAmount** `integer` *required*

Precio unitario en céntimos.

**quantity** `integer` *required*

Unidades.

**taxAmount** `integer`

Impuesto **total de la línea** en céntimos. No se multiplica por `quantity`.

**productId** `string`

Id del producto en tu sistema.

**sku** `string`

SKU del producto.

**imageUrl** `string`

Imagen del producto que se muestra en el checkout.

**currency** `string` (default: USD)

Moneda del cobro, en formato ISO 4217 (`EUR`, `USD`…).

**showCurrency** `string`

Moneda que se muestra al comprador. Solo es necesaria en tiendas multimoneda.

**shippingOptionId** `string`

Opción de envío de la tienda. Si no la envías, se usa la primera opción activa.

**sourceUrl** `string`

URL de la página donde estaba el comprador. Se usa como `event_source_url` en los eventos de servidor de los píxeles.

**notes** `string`

Notas del pedido.

**logoUrl** `string`

Logo del checkout. Solo se usa si la tienda no tiene uno configurado.

### Señales de seguimiento

Todas son opcionales. Envíalas para que los eventos de servidor de tus píxeles atribuyan bien la venta.

**fbc** `string`

Cookie `_fbc` de Meta.

**fbp** `string`

Cookie `_fbp` de Meta.

**visitorId** `string`

Id de visitante (`hy_vid`). Es el mismo `external_id` que manda el píxel desde el navegador.

**ttc** `string`

Click ID de TikTok.

**ttp** `string`

Cookie `_ttp` de TikTok.

**gclid** `string`

Click ID de Google Ads (`gclid`, `gcl_au` o `gcl_aw`).

**epik** `string`

Click ID de Pinterest (cookie `_epik`).

> [!NOTE]
>
> No hace falta enviar la IP ni el User-Agent del comprador: Hurry los toma de la propia petición. Los IDs de los píxeles y la opción de mostrar tus propios términos se leen de la configuración de la tienda.

***

## Respuesta

**redirectUrl** `string | null`

URL del checkout a la que debes redirigir al comprador. Es `null` si no se ha podido crear el pedido.

**orderId** `string`

Id del pedido en Hurry.

**gateway** `string`

Pasarela usada (`STRIPE`, `SHOPIFY`…). Solo aparece con algunas pasarelas, como Shopify Payments.

**status** `string`

Estado del pago: `pending`, `paid`, `cancelled`, `refunded` o `fulfilled`. Solo aparece con algunas pasarelas.

**checkoutUrl** `string`

Igual que `redirectUrl`. Solo aparece con algunas pasarelas.

**paymentSessionId** `string`

Id de la sesión de pago en Hurry. Solo aparece con algunas pasarelas.

**externalPaymentSessionId** `string`

Id de la sesión de pago en la pasarela. Solo aparece con algunas pasarelas.

***

## Errores

La petición responde **HTTP 200 con `redirectUrl: null`** cuando:

* `shopUrl` falta, no existe o la tienda está desactivada.
* La cuenta está suspendida.
* Los cobros están pausados porque se ha alcanzado el tope diario del [balanceo por volumen](https://docs.hurrypayments.com/balanceo-por-volumen.md). Se reanudan a las 00:00.
* La tienda no tiene ninguna pasarela de pago activa.
* El cuerpo no es válido, por ejemplo con `items` vacío.

La única petición que devuelve un error HTTP es la que llega **sin `externalId`**.

***

## Idempotencia

Si repites la llamada con el mismo `externalId` (recarga de página, doble clic, reintento), recibes **el mismo pedido** mientras se pueda seguir cobrando por su pasarela.

Si esa pasarela ya no está disponible (la has desactivado o la tienda ya no la usa), Hurry crea un pedido nuevo enrutado con tu configuración actual. Las siguientes llamadas con el mismo `externalId` reciben ese pedido nuevo.

***

## Cálculo del importe

```text Total theme={null}
total = Σ (unitAmount × quantity) + Σ taxAmount + envío
```

En tiendas multimoneda, el importe se convierte de `showCurrency` a `currency` con el tipo de cambio del día más el recargo que hayas configurado en la tienda.

***

## Estados del pedido

| Estado | Cuándo |
| :- | :- |
| `PENDING` | Al crearse el pedido. |
| `IN_PROGRESS` | Cuando el comprador abre la página de checkout. |

```bash cURL theme={null}
curl -X POST https://app.hurrypayments.com/api/orders \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "CART-abc123-9f1e",
    "shopUrl": "mitienda.com",
    "currency": "EUR",
    "sourceUrl": "https://mitienda.com/cart",
    "items": [
      {
        "productId": "p1",
        "name": "Camiseta",
        "unitAmount": 2500,
        "quantity": 2,
        "imageUrl": "https://mitienda.com/img/camiseta.jpg"
      }
    ]
  }'
```

```javascript JavaScript theme={null}
const res = await fetch("https://app.hurrypayments.com/api/orders", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    externalId: "CART-abc123-9f1e",
    shopUrl: "mitienda.com",
    currency: "EUR",
    items: [
      { productId: "p1", name: "Camiseta", unitAmount: 2500, quantity: 2 }
    ]
  })
});
const data = await res.json();

if (data.redirectUrl) {
  window.location.href = data.redirectUrl;
} else {
  // No se pudo crear el checkout: muestra un error o vuelve al carrito
}
```

```json Pedido creado theme={null}
{
  "redirectUrl": "https://app.hurrypayments.com/checkout/detail/v2?orderId=8f3c2a91-...",
  "orderId": "8f3c2a91-..."
}
```

```json Error theme={null}
{
  "redirectUrl": null,
  "orderId": null
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.