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

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# Quickstart: tu primer pago en sandbox

> Crea una conexión, envía un pago con una tarjeta de prueba en el sandbox de Yuno y míralo en el dashboard.

Primeros pasos

Tutorial · unos 10 minutos

Yuno es el sistema operativo de IA para pagos, y un pago es lo primero que ejecutas en él. Envías tu primer pago en sandbox en unos 10 minutos, una vez que tienes las credenciales de sandbox.

Crea una conexión
Envía un pago con una tarjeta de prueba
Míralo en el dashboard

<video src="https://docs.y.uno/videos/explainers/first-payment.mp4" poster="/videos/explainers/first-payment.jpg" controls preload="none" playsInline aria-label="Tu primer pago" />

Video: Tu primer pago (66 s, captions on screen, no voiceover)

## Antes de empezar

Necesitas estos datos para cada llamada de esta página.

| Dato | Valor |
| - | - |
| Código de cuenta | `account_id` en el dashboard, en **Developers** |
| Claves | `public-api-key` y `private-secret-key`, las dos empiezan con `sandbox_` |
| URL base | `https://api-sandbox.y.uno/v1` (mantén el `/v1`) |
| Montos | `amount.value` es un número junto a una `currency`. Esta página envía `25` con `USD` |
| Herramientas | Node 18 o posterior, o `curl` |

### 1. Obtén tus credenciales de sandbox

Inicia sesión en el [dashboard de Yuno](https://dashboard.y.uno/) y abre **Developers** para encontrar tres valores:

* **Código de cuenta**, que aparece como `account_id` en el dashboard
* **`public-api-key`**
* **`private-secret-key`**

Las claves de sandbox empiezan con `sandbox_`. Las claves de producción son distintas y empiezan con `prod_`.

![Página de inicio de sesión del dashboard de Yuno](https://mintcdn.com/yuno-3979e326/mqKc4056TZzyLssc/images/reference/step-1-set-up-your-account/image1.png?fit=max\&auto=format\&n=mqKc4056TZzyLssc\&q=85\&s=09be08d430f7f2e7af07821dd84f146f)

Si todavía no tienes una cuenta, pídela a tu contacto en Yuno o escribe a [sales@y.uno](mailto:sales@y.uno). Por ahora no hay registro autogestionado.

Define tus credenciales como variables de entorno:

```bash Shell theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
export YUNO_PUBLIC_API_KEY="sandbox_..."
export YUNO_PRIVATE_SECRET_KEY="sandbox_..."
export YUNO_ACCOUNT_ID="your-account-code"
```

Comprueba las claves creando un cliente. La URL base es `https://api-sandbox.y.uno/v1`.

```bash cURL theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
curl --request POST \
  --url https://api-sandbox.y.uno/v1/customers \
  --header "public-api-key: $YUNO_PUBLIC_API_KEY" \
  --header "private-secret-key: $YUNO_PRIVATE_SECRET_KEY" \
  --header "content-type: application/json" \
  --data '{
    "merchant_customer_id": "customer-0001",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  }'
```

```javascript Node.js theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
const res = await fetch("https://api-sandbox.y.uno/v1/customers", {
  method: "POST",
  headers: {
    "public-api-key": process.env.YUNO_PUBLIC_API_KEY,
    "private-secret-key": process.env.YUNO_PRIVATE_SECRET_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    merchant_customer_id: "customer-0001",
    first_name: "John",
    last_name: "Doe",
    email: "john.doe@example.com",
  }),
});
const customer = await res.json();
console.log(customer.id);
```

```python Python theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
import os
import requests

res = requests.post(
    "https://api-sandbox.y.uno/v1/customers",
    headers={
        "public-api-key": os.environ["YUNO_PUBLIC_API_KEY"],
        "private-secret-key": os.environ["YUNO_PRIVATE_SECRET_KEY"],
    },
    json={
        "merchant_customer_id": "customer-0001",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
    },
)
print(res.json()["id"])
```

La respuesta incluye un `id`. Guárdalo como `YUNO_CUSTOMER_ID`: los pasos de pago lo usan.

> [!TIP]
>
> **Paso completado cuando** `POST /v1/customers` responde `201`.
>
> * `401` significa que el par de claves es incorrecto. Vuelve a copiar las dos claves de sandbox desde **Developers**.
> * `404` con el cuerpo vacío significa que falta `/v1` en la URL base.

### 2. Conecta el Yuno Test Payment Gateway y publica una ruta

El Yuno Test Payment Gateway simula un proveedor de tarjetas. Funciona solo en sandbox y no necesita credenciales.

1. Abre [Connections](https://dashboard.y.uno/connections), busca **Yuno Test Payment Gateway**, haz clic en **Connect**, ponle un nombre a la conexión y haz clic en **Save**.
2. Abre [Routing](https://dashboard.y.uno/routing), abre la pestaña **Not published**, busca **Card** y haz clic en **Set Up**.
3. Haz clic en **+ Create new route**, ponle un nombre y haz clic en **Save**.
4. Haz clic en la flecha, elige **Add step**, selecciona **Yuno Test Payment Gateway** y haz clic en **Publish**.
5. Abre [Checkout builder](https://dashboard.y.uno/checkout-builder), activa **Card** y publica la configuración.

> [!TIP]
>
> **Paso completado cuando** una nueva sesión de checkout incluye `CARD`. Crea una sesión como en el paso 4 y guarda su `checkout_session` como `YUNO_CHECKOUT_SESSION`. Luego llama a [`GET /v1/checkout/sessions/{checkout_session}/payment-methods`](https://docs.y.uno/reference/checkout-sessions/retrieve-payment-methods-for-checkout) y busca `"type": "CARD"` en la lista.
>
> Si falta `CARD`, revisa las tres configuraciones: el Test Payment Gateway está conectado, la ruta de Card está en **Published** y Card está activado en el Checkout builder.

### 3. Elige cómo se crea el pago

El campo `workflow` le indica a Yuno quién crea el pago. Elige uno y usa la pestaña correspondiente en el paso 4.

| Workflow | Quién crea el pago | Cuándo usarlo |
| - | - | - |
| `SDK_SEAMLESS` | El SDK crea el pago | Quieres la menor cantidad de piezas posible. Recomendado |
| `SDK_CHECKOUT` más un callback `createPayment` | Tu backend lo crea, a partir del token de un solo uso que te entrega el SDK | Agregas datos del pedido, controles de fraude o idempotencia en tu servidor |
| `DIRECT` | Tu backend envía los datos de la tarjeta sin procesar | Tienes alcance PCI DSS. Si no, úsalo solo para pruebas en sandbox |

Una sesión y una integración que no coinciden terminan en `INTERNAL_ERROR`. Consulta [Primeros pasos con el Yuno SDK](https://docs.y.uno/docs/yuno-sdk/get-started.md) y [Flujo directo](https://docs.y.uno/docs/direct-integration-use-cases/direct-flow.md) para ver cada camino completo.

> [!TIP]
>
> **Paso completado cuando** puedes decir qué workflow vas a enviar: `SDK_SEAMLESS`, `SDK_CHECKOUT` o `DIRECT`. La sesión de checkout (caminos con SDK) o el pago (`DIRECT`) lo lleva en el campo `workflow`.

### 4. Envía el pago

> [tab] DIRECT
>
> > [!WARNING]
> >
> > Enviar números de tarjeta sin procesar desde tu servidor es para pruebas en sandbox. En producción requiere alcance PCI DSS. Si no lo tienes, usa el Yuno SDK o Secure Fields para recopilar los datos de la tarjeta.
>
> El workflow `DIRECT` es un pago directo en el que tu servidor envía los datos de la tarjeta. Usa el `id` del cliente que guardaste como `YUNO_CUSTOMER_ID` en el paso 1.
>
> Crea el pago con una tarjeta de prueba. Envía un `X-Idempotency-Key` nuevo con cada pago.
>
> ```bash cURL theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> curl --request POST \
>   --url https://api-sandbox.y.uno/v1/payments \
>   --header "public-api-key: $YUNO_PUBLIC_API_KEY" \
>   --header "private-secret-key: $YUNO_PRIVATE_SECRET_KEY" \
>   --header "X-Idempotency-Key: $(uuidgen)" \
>   --header "content-type: application/json" \
>   --data '{
>     "account_id": "'"$YUNO_ACCOUNT_ID"'",
>     "merchant_order_id": "order-0001",
>     "description": "First test payment",
>     "country": "US",
>     "amount": { "currency": "USD", "value": 25 },
>     "workflow": "DIRECT",
>     "customer_payer": { "id": "'"$YUNO_CUSTOMER_ID"'" },
>     "payment_method": {
>       "type": "CARD",
>       "detail": { "card": { "card_data": {
>         "number": "4507990000000002",
>         "expiration_month": 11,
>         "expiration_year": 28,
>         "security_code": "123",
>         "holder_name": "John Doe"
>       } } }
>     }
>   }'
> ```
>
> ```javascript Node.js theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> const res = await fetch("https://api-sandbox.y.uno/v1/payments", {
>   method: "POST",
>   headers: {
>     "public-api-key": process.env.YUNO_PUBLIC_API_KEY,
>     "private-secret-key": process.env.YUNO_PRIVATE_SECRET_KEY,
>     "X-Idempotency-Key": crypto.randomUUID(),
>     "content-type": "application/json",
>   },
>   body: JSON.stringify({
>     account_id: process.env.YUNO_ACCOUNT_ID,
>     merchant_order_id: "order-0001",
>     description: "First test payment",
>     country: "US",
>     amount: { currency: "USD", value: 25 },
>     workflow: "DIRECT",
>     customer_payer: { id: process.env.YUNO_CUSTOMER_ID },
>     payment_method: {
>       type: "CARD",
>       detail: { card: { card_data: {
>         number: "4507990000000002",
>         expiration_month: 11,
>         expiration_year: 28,
>         security_code: "123",
>         holder_name: "John Doe",
>       } } },
>     },
>   }),
> });
> const payment = await res.json();
> console.log(payment.status, payment.sub_status);
> ```
>
> ```python Python theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> import os
> import uuid
> import requests
>
> res = requests.post(
>     "https://api-sandbox.y.uno/v1/payments",
>     headers={
>         "public-api-key": os.environ["YUNO_PUBLIC_API_KEY"],
>         "private-secret-key": os.environ["YUNO_PRIVATE_SECRET_KEY"],
>         "X-Idempotency-Key": str(uuid.uuid4()),
>     },
>     json={
>         "account_id": os.environ["YUNO_ACCOUNT_ID"],
>         "merchant_order_id": "order-0001",
>         "description": "First test payment",
>         "country": "US",
>         "amount": {"currency": "USD", "value": 25},
>         "workflow": "DIRECT",
>         "customer_payer": {"id": os.environ["YUNO_CUSTOMER_ID"]},
>         "payment_method": {
>             "type": "CARD",
>             "detail": {"card": {"card_data": {
>                 "number": "4507990000000002",
>                 "expiration_month": 11,
>                 "expiration_year": 28,
>                 "security_code": "123",
>                 "holder_name": "John Doe",
>             }}},
>         },
>     },
> )
> payment = res.json()
> print(payment["status"], payment["sub_status"])
> ```
>
> El pago es exitoso cuando la respuesta se ve así:
>
> ```json Response (trimmed) theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> {
>   "id": "6c44ed29-cc51-4479-a5eb-108afdaadd50",
>   "status": "SUCCEEDED",
>   "sub_status": "APPROVED",
>   "amount": { "currency": "USD", "value": 25 }
> }
> ```

> [tab] SDK\_SEAMLESS
>
> La pestaña `SDK_SEAMLESS` divide el trabajo. Tu servidor crea una sesión de checkout, y el navegador carga el SDK e inicia la transacción.
>
> **En tu servidor**, crea la sesión de checkout. Usa `workflow: "SDK_SEAMLESS"` para que el SDK cree el pago por ti. Sin ese valor, la transacción termina en `INTERNAL_ERROR`.
>
> ```bash cURL theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> curl --request POST \
>   --url https://api-sandbox.y.uno/v1/checkout/sessions \
>   --header "public-api-key: $YUNO_PUBLIC_API_KEY" \
>   --header "private-secret-key: $YUNO_PRIVATE_SECRET_KEY" \
>   --header "content-type: application/json" \
>   --data '{
>     "account_id": "'"$YUNO_ACCOUNT_ID"'",
>     "merchant_order_id": "order-0001",
>     "payment_description": "First test payment",
>     "country": "US",
>     "amount": { "currency": "USD", "value": 25 },
>     "workflow": "SDK_SEAMLESS"
>   }'
> ```
>
> ```javascript Node.js theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> const res = await fetch("https://api-sandbox.y.uno/v1/checkout/sessions", {
>   method: "POST",
>   headers: {
>     "public-api-key": process.env.YUNO_PUBLIC_API_KEY,
>     "private-secret-key": process.env.YUNO_PRIVATE_SECRET_KEY,
>     "content-type": "application/json",
>   },
>   body: JSON.stringify({
>     account_id: process.env.YUNO_ACCOUNT_ID,
>     merchant_order_id: "order-0001",
>     payment_description: "First test payment",
>     country: "US",
>     amount: { currency: "USD", value: 25 },
>     workflow: "SDK_SEAMLESS",
>   }),
> });
> const session = await res.json();
> console.log(session.checkout_session);
> ```
>
> ```python Python theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> import os
> import requests
>
> res = requests.post(
>     "https://api-sandbox.y.uno/v1/checkout/sessions",
>     headers={
>         "public-api-key": os.environ["YUNO_PUBLIC_API_KEY"],
>         "private-secret-key": os.environ["YUNO_PRIVATE_SECRET_KEY"],
>     },
>     json={
>         "account_id": os.environ["YUNO_ACCOUNT_ID"],
>         "merchant_order_id": "order-0001",
>         "payment_description": "First test payment",
>         "country": "US",
>         "amount": {"currency": "USD", "value": 25},
>         "workflow": "SDK_SEAMLESS",
>     },
> )
> print(res.json()["checkout_session"])
> ```
>
> **En el navegador**, carga el SDK desde el CDN y luego inicia una transacción con el valor `checkout_session` que te devuelve tu servidor.
>
> ```html Browser theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> <div id="payment-form"></div>
> <script src="https://sdk-web.y.uno/v2.5.1/main.js"></script>
> <script>
>   async function startYuno() {
>     const sdkPayments = await SdkPayments.initialize("your-public-api-key");
>     const transaction = sdkPayments.transaction({
>       checkoutSession: "checkout-session-from-your-server",
>       countryCode: "US",
>       elementSelector: "#payment-form",
>       onStatus: (result) => console.log("Final status:", result.status),
>     });
>     await transaction.start({ paymentMethod: { type: "CARD" } });
>   }
>
>   if (window.SdkPayments) {
>     startYuno();
>   } else {
>     window.addEventListener("sdk-payments-ready", startYuno);
>   }
> </script>
> ```
>
> El formulario se muestra en `#payment-form`. Ingresa la tarjeta de prueba **4507 9900 0000 0002**, vencimiento **11/28**, CVV **123**, nombre **John Doe**, y haz clic en Pay. El resultado llega en `onStatus` con el estado `SUCCEEDED`.
>
> Para iOS, Android y todas las opciones, consulta [Primeros pasos con el SDK](https://docs.y.uno/docs/yuno-sdk/get-started.md).

> [tab] SDK\_CHECKOUT
>
> Tu servidor crea la sesión de checkout con `workflow: "SDK_CHECKOUT"`. El navegador inicia la transacción y pasa un callback `createPayment`. El SDK le entrega al callback un token de un solo uso, y tu backend crea el pago a partir de ese token.
>
> **En tu servidor**, crea la sesión de checkout con el cliente del paso 1:
>
> ```bash cURL theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> curl --request POST \
>   --url https://api-sandbox.y.uno/v1/checkout/sessions \
>   --header "public-api-key: $YUNO_PUBLIC_API_KEY" \
>   --header "private-secret-key: $YUNO_PRIVATE_SECRET_KEY" \
>   --header "content-type: application/json" \
>   --data '{
>     "account_id": "'"$YUNO_ACCOUNT_ID"'",
>     "merchant_order_id": "order-0001",
>     "payment_description": "First test payment",
>     "country": "US",
>     "customer_id": "'"$YUNO_CUSTOMER_ID"'",
>     "amount": { "currency": "USD", "value": 25 },
>     "workflow": "SDK_CHECKOUT"
>   }'
> ```
>
> **En el navegador**, inicia la transacción y sobrescribe `createPayment`. Envía `token.token` y `token.checkout_session` a tu backend:
>
> ```html Browser theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> <div id="payment-form"></div>
> <script src="https://sdk-web.y.uno/v2.5.1/main.js"></script>
> <script>
>   async function startYuno() {
>     const sdkPayments = await SdkPayments.initialize("your-public-api-key");
>     const transaction = sdkPayments.transaction({
>       checkoutSession: "checkout-session-from-your-server",
>       countryCode: "US",
>       elementSelector: "#payment-form",
>       createPayment: async (token) => {
>         await fetch("/api/pay", {
>           method: "POST",
>           headers: { "content-type": "application/json" },
>           body: JSON.stringify({
>             token: token.token,
>             checkout_session: token.checkout_session,
>           }),
>         });
>       },
>       onStatus: (result) => console.log("Final status:", result.status),
>     });
>     await transaction.start({ paymentMethod: { type: "CARD" } });
>   }
>
>   if (window.SdkPayments) {
>     startYuno();
>   } else {
>     window.addEventListener("sdk-payments-ready", startYuno);
>   }
> </script>
> ```
>
> Resuelve la promesa en todos los casos, incluida una falla de red, o la transacción se queda en curso. Consulta [`createPayment`](https://docs.y.uno/docs/yuno-sdk/controllers/create-payment).
>
> **De nuevo en tu servidor**, tu handler `/api/pay` crea el pago con `POST /v1/payments`. Envía el token en `payment_method.token` y la sesión en `checkout.session`:
>
> ```javascript Node.js theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> // token and checkoutSession come from the browser request body
> async function createPayment({ token, checkoutSession }) {
>   const res = await fetch("https://api-sandbox.y.uno/v1/payments", {
>     method: "POST",
>     headers: {
>       "public-api-key": process.env.YUNO_PUBLIC_API_KEY,
>       "private-secret-key": process.env.YUNO_PRIVATE_SECRET_KEY,
>       "X-Idempotency-Key": crypto.randomUUID(),
>       "content-type": "application/json",
>     },
>     body: JSON.stringify({
>       account_id: process.env.YUNO_ACCOUNT_ID,
>       merchant_order_id: "order-0001",
>       description: "First test payment",
>       country: "US",
>       amount: { currency: "USD", value: 25 },
>       customer_payer: { id: process.env.YUNO_CUSTOMER_ID },
>       payment_method: { token },
>       checkout: { session: checkoutSession },
>     }),
>   });
>   return res.json();
> }
> ```
>
> Ingresa la tarjeta de prueba **4507 9900 0000 0002**, vencimiento **11/28**, CVV **123**, nombre **John Doe**, y haz clic en Pay. La respuesta tiene la misma forma que la respuesta de `DIRECT` de arriba.

> [!TIP]
>
> **Paso completado cuando** el `status` del pago es `SUCCEEDED` con la tarjeta de prueba **4507 9900 0000 0002** (11/28, CVV 123, John Doe).

### 5. Mira el resultado

* Revisa `status` y `sub_status` en la respuesta. `SUCCEEDED` con `APPROVED` significa que el gateway aprobó el pago.
* Abre [Payments](https://dashboard.y.uno/payments) en el dashboard, busca tu pago y ábrelo para ver sus detalles.
* Para recibir el resultado en tu servidor, [configura un webhook](https://docs.y.uno/docs/webhooks/configure-webhooks.md) y [verifica su firma](https://docs.y.uno/docs/webhooks/verify-webhook-signatures-hmac.md) (HMAC).

Los estados de pago aparecen en [Estados de pago](https://docs.y.uno/reference/payments/status-and-response-codes/payment.md).

> [!TIP]
>
> **Paso completado cuando** el pago aparece como `SUCCEEDED` en la lista **Payments** del dashboard y en el campo `status` de tu respuesta.

## Siguientes pasos

> [card] [Salir a producción](https://docs.y.uno/es/docs/go-live.md)
>
> Guía
> Claves de producción, una ruta publicada, webhooks verificados y un primer pago real.

## Solución de problemas

> [accordion] La API devuelve 401
>
> Falta el encabezado `public-api-key` o `private-secret-key`, o es incorrecto. Sandbox y producción usan claves distintas, así que verifica que copiaste las claves de sandbox desde el dashboard en Test Mode. Consulta [Autenticación](https://docs.y.uno/reference/getting-started/authentication.md).

> [accordion] El pago termina en INTERNAL\_ERROR
>
> El `workflow` no coincide con tu integración. Usa `DIRECT` cuando tu servidor envía la tarjeta, y `SDK_SEAMLESS` en la sesión de checkout cuando el Web SDK crea el pago.

> [accordion] Ningún proveedor procesa el pago
>
> Card no tiene una ruta publicada. Abre [Routing](https://dashboard.y.uno/routing) y verifica que la ruta de Card con el Yuno Test Payment Gateway esté en la pestaña **Published**, y que Card esté activado en el [Checkout builder](https://dashboard.y.uno/checkout-builder).

> [accordion] La tarjeta es rechazada
>
> Las tarjetas de prueba son específicas de cada proveedor. Las tarjetas de este Quickstart solo funcionan cuando tu sandbox enruta Card al Yuno Test Payment Gateway. Los otros resultados aparecen en la página del [Yuno Test Payment Gateway](https://docs.y.uno/docs/direct-integration-use-cases/yuno-testing-gateway.md).

¿Un término no está claro? Consulta el [Glosario](https://docs.y.uno/docs/glossary.md). Para URLs, claves y specs, consulta [Developers](https://docs.y.uno/docs/developers.md).


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