---
title: "Checkout"
description: "Integra la API de Checkout de Fystack para crear experiencias de pago fluidas para tus usuarios."
url: https://docs.fystack.io/es/checkout
last_updated: 2026-11-13
---

> ## Documentation index
> Fetch the complete documentation index at: https://docs.fystack.io/llms.txt
> Use it to discover all available pages before exploring further.

# Checkout

La API de Checkout ofrece una forma potente de crear sesiones de pago, gestionar flujos de pago y procesar transacciones a través de la infraestructura segura de Fystack.

---

## Crear un checkout

**Endpoint:** `POST /checkouts`

Para crear un nuevo checkout, envía una solicitud POST al endpoint `/checkouts` con los parámetros requeridos.

### Parámetros

- `price` (string, required): El monto del pago como string (p. ej., "66").
- `currency` (string, required): Código de moneda ISO de tres letras (p. ej., USD, EUR). Actualmente solo se admite USD.
- `expiry_duration_seconds` (number, required): Número de segundos hasta que expire la sesión de checkout. Debe estar entre 0 y 31536000.
- `destination_wallet_id` (string, required): ID de la billetera a la que se enviará el pago.

  _Image: Copiar ID de billetera_

### Parámetros de activos

Proporciona `supported_assets` o `accepted_assets`.

- `supported_assets` (array): Lista de criptoactivos admitidos. Cada elemento puede ser un UUID de activo o un alias con el formato "SYMBOL:CHAIN_ID" (p. ej., "SOL:1399811149").

  | Cadena | ID de cadena | Ejemplo de formato |
  | --- | --- | --- |
  | Solana | 1399811149 | `SOL:1399811149` |
  | Ethereum | 1 | `ETH:1`, `USDC:1` |
  | BNB Chain | 56 | `BNB:56` |
  | Base | 8453 | `ETH:8453` |
  | Polygon | 137 | `POL:137` |
- `accepted_assets` (array): Lista de criptoactivos admitidos en formato legible. Cada elemento contiene `asset` y `network`, por ejemplo el activo `USDC` en la red `ETHEREUM_MAINNET`.
- `success_url` (string): URL a la que se redirige a los clientes tras un pago exitoso.
- `cancel_url` (string): URL a la que se redirige a los clientes si cancelan el proceso de checkout.
- `description` (string): Descripción de lo que compra el cliente.
- `product_id` (string): Identificador único del producto que se compra.
- `customer_id` (string): Vincula este checkout a un cliente existente en tu sistema.
- `order_id` (string): Identificador único del pedido.
- `enable_localization` (boolean): Indica si se habilita la localización en la página de checkout. El valor predeterminado es false.
- `from_address` (string): Dirección opcional del pagador. Si se proporciona, Fystack usa el flujo de pago de billetera única.
- `underpaid_cover_percent` (number): Porcentaje de tolerancia permitido para pagos insuficientes. Debe estar entre 0 y 100.

### Respuesta

- `id` (string): Identificador único de la sesión de checkout.
- `checkout_url` (string): URL de la página de checkout alojada. Redirige a los clientes a esta URL.
- `status` (string): Estado de la sesión de checkout. Puede ser `Pending`, `Confirming`, `Success`, `Expired`, `Unresolved`, `Resolved` o `Cancelled`.
- `created_at` (timestamp): Momento en que se creó la sesión de checkout.
- `updated_at` (timestamp): Momento de la última actualización de la sesión de checkout.
- `currency` (string): Código de moneda ISO de tres letras.
- `price` (string): El monto del pago como string.
- `product_id` (string): Identificador único del producto que se compra.
- `order_id` (string): Identificador único del pedido.
- `workspace_id` (string): Identificador del workspace al que pertenece este checkout.
- `description` (string): Descripción de lo que compra el cliente.
- `supported_assets` (array): Lista de criptoactivos admitidos para este checkout.
- `customer_id` (string): Identificador del cliente asociado a este checkout.
- `expiry_duration_seconds` (number): Número de segundos hasta que expire la sesión de checkout.
- `enable_localization` (boolean): Indica si la localización está habilitada en la página de checkout.
- `success_url` (string): URL a la que se redirige a los clientes tras un pago exitoso.
- `cancel_url` (string): URL a la que se redirige a los clientes si cancelan el proceso de checkout.
- `outcome` (object|null): Información sobre el resultado del pago, si está disponible.
- `from_address` (string|null): La dirección desde la que se realizó el pago, si está disponible.

**Request** `POST /checkouts`

```typescript
import { PaymentService, Environment } from '@fystack/sdk'

const paymentService = new PaymentService({
  apiKey: apiCredentials.APIKey,
  environment: Environment.Production
})

await paymentService.createCheckout({
  price: '66',
  currency: 'USD',
  supported_assets: ['SOL:1399811149', 'USDC:1399811149', 'ETH:8453', 'ETH:1', 'USDC:1'],
  description: 'Access to premium features and exclusive content.',
  success_url: 'https://example.com/payment/success',
  cancel_url: 'https://example.com/payment/cancel',
  product_id: '4c57fae9-1a54-4a1b-9d94-00d5b4a3e1d2',
  customer_id: 'bc5bd50d-265e-4ea9-b312-bd8de5118683',
  order_id: 'bc5bd50d-265e-4ea9-b312-bd8de5118683',
  enable_localization: false,
  destination_wallet_id: 'ca6b5c4d-753f-4c2d-af18-520f66a42bd4',
  expiry_duration_seconds: 3600
})
```

```bash
curl -X POST https://api.fystack.io/api/v1/checkouts \
  -H "ACCESS-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "price": "66",
    "currency": "USD",
    "supported_assets": ["SOL:1399811149", "USDC:1399811149", "ETH:8453"],
    "description": "Access to premium features and exclusive content.",
    "success_url": "https://example.com/payment/success",
    "cancel_url": "https://example.com/payment/cancel",
    "product_id": "4c57fae9-1a54-4a1b-9d94-00d5b4a3e1d2",
    "customer_id": "bc5bd50d-265e-4ea9-b312-bd8de5118683",
    "order_id": "order_123",
    "enable_localization": false,
    "destination_wallet_id": "ca6b5c4d-753f-4c2d-af18-520f66a42bd4",
    "expiry_duration_seconds": 3600
  }'
```

```json
{
  "success": true,
  "message": "success",
  "code": 0,
  "data": {
    "id": "17976d0a-e4ff-44a6-a47e-c7e2bbab3db2",
    "created_at": "2025-05-17T12:39:27.308105515+07:00",
    "updated_at": "2025-05-17T12:39:27.308105515+07:00",
    "currency": "USD",
    "product_id": "4c57fae9-1a54-4a1b-9d94-00d5b4a3e1d2",
    "order_id": "bc5bd50d-265e-4ea9-b312-bd8de5118683",
    "workspace_id": "ffb8c9d1-0bd2-4c30-bf4f-2a8fe7710d51",
    "underpaid_cover_percent": 0,
    "description": "Access to premium features and exclusive content.",
    "price": "66",
    "supported_assets": [
      {
        "id": "6f4b5818-967f-4132-a475-20fe766c6c0e",
        "created_at": "0001-01-01T00:00:00Z",
        "updated_at": "0001-01-01T00:00:00Z",
        "is_native": false,
        "is_whitelisted": false
      },
      {
        "id": "c0b89aea-08b1-4a10-a754-17f3b133be24",
        "created_at": "0001-01-01T00:00:00Z",
        "updated_at": "0001-01-01T00:00:00Z",
        "is_native": false,
        "is_whitelisted": false
      }
    ],
    "customer_id": "bc5bd50d-265e-4ea9-b312-bd8de5118683",
    "expiry_duration_seconds": 3600,
    "enable_localization": false,
    "success_url": "https://example.com/payment/success",
    "cancel_url": "https://example.com/payment/cancel",
    "status": "Pending",
    "outcome": null,
    "from_address": null,
    "checkout_url": "https://app.fystack.io/checkout/17976d0a-e4ff-44a6-a47e-c7e2bbab3db2"
  }
}
```

---

## Obtener un checkout

**Endpoint:** `GET /checkouts/:id`

Obtén los detalles de un checkout por su ID.

### Respuesta

- `id` (string): Identificador único del checkout.
- `status` (string): Estado del checkout. Puede ser `Pending`, `Confirming`, `Success`, `Expired`, `Unresolved`, `Resolved` o `Cancelled`.
- `price` (string): El monto del pago como string.
- `currency` (string): Código de moneda ISO de tres letras.
- `created_at` (timestamp): Momento en que se creó el checkout.
- `updated_at` (timestamp): Momento de la última actualización del checkout.
- `product_id` (string): Identificador único del producto que se compra.
- `order_id` (string): Identificador único del pedido.
- `workspace_id` (string): Identificador del workspace al que pertenece este checkout.
- `description` (string): Descripción de lo que compra el cliente.
- `supported_assets` (array): Lista de criptoactivos admitidos para este checkout.
- `customer_id` (string): Identificador del cliente asociado a este checkout.
- `expiry_duration_seconds` (number): Número de segundos hasta que expire el checkout.
- `success_url` (string): URL a la que se redirige a los clientes tras un pago exitoso.
- `cancel_url` (string): URL a la que se redirige a los clientes si cancelan el proceso de checkout.
- `checkout_url` (string): URL de la página de checkout alojada.
- `outcome` (object|null): Información sobre el resultado del pago, si está disponible.
- `from_address` (string|null): La dirección desde la que se realizó el pago, si está disponible.

**Request** `GET /checkouts/:id`

```typescript
import { PaymentService, Environment } from '@fystack/sdk'

const paymentService = new PaymentService({
  apiKey: apiCredentials.APIKey,
  environment: Environment.Production
})

const checkout = await paymentService.getCheckout('17976d0a-e4ff-44a6-a47e-c7e2bbab3db2')
```

```bash
curl -X GET https://api.fystack.io/api/v1/checkouts/17976d0a-e4ff-44a6-a47e-c7e2bbab3db2
```

```json
{
  "success": true,
  "message": "success",
  "code": 0,
  "data": {
    "id": "2912168a-6bb6-4b5c-88bb-723706718e4a",
    "created_at": "2025-05-17T12:50:57.807741+07:00",
    "updated_at": "2025-05-17T12:50:57.807741+07:00",
    "currency": "USD",
    "product_id": "4c57fae9-1a54-4a1b-9d94-00d5b4a3e1d2",
    "order_id": "bc5bd50d-265e-4ea9-b312-bd8de5118683",
    "workspace_id": "ffb8c9d1-0bd2-4c30-bf4f-2a8fe7710d51",
    "underpaid_cover_percent": 0,
    "description": "Access to premium features and exclusive content.",
    "price": "66",
    "supported_assets": [
      {
        "id": "e9337429-a741-4e92-afbb-c1b1fc1ad8a4",
        "created_at": "2024-09-21T17:48:12.718886+07:00",
        "updated_at": "2024-09-21T17:48:12.718886+07:00",
        "name": "USD Coin",
        "symbol": "USDC",
        "decimals": 6,
        "logo_url": "https://assets-cdn.trustwallet.com/blockchains/ethereum/assets/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48/logo.png",
        "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
        "asset_type": "erc20",
        "is_native": false,
        "address_type": "evm",
        "is_whitelisted": true,
        "network_id": "dd21bfb5-f809-4070-a789-18ec8abbee1b"
      },
      {
        "id": "6f4b5818-967f-4132-a475-20fe766c6c0e",
        "created_at": "2024-12-05T20:32:42.14387+07:00",
        "updated_at": "2024-12-05T20:32:42.14387+07:00",
        "name": "Solana token",
        "symbol": "SOL",
        "decimals": 9,
        "logo_url": "https://upload.wikimedia.org/wikipedia/en/b/b9/Solana_logo.png",
        "is_native": true,
        "address_type": "sol",
        "is_whitelisted": true,
        "network_id": "8ae1f43f-d428-484d-8ad4-ee9ccc65a9ac"
      }
    ],
    "customer_id": "bc5bd50d-265e-4ea9-b312-bd8de5118683",
    "expiry_duration_seconds": 3600,
    "enable_localization": false,
    "success_url": "https://example.com/payment/success",
    "cancel_url": "https://example.com/payment/cancel",
    "status": "Pending",
    "outcome": null,
    "from_address": null,
    "checkout_url": "https://app.fystack.io/checkout/2912168a-6bb6-4b5c-88bb-723706718e4a"
  }
}
```

---

## Crear un pago de checkout

**Endpoint:** `POST /checkouts/:id/payment`

Crea un pago para una sesión de checkout existente especificando qué activo admitido se usará para pagar.

### Parámetros

- `pay_asset_id` (string, required): El ID del activo que se usará para el pago. Debe ser uno de los activos admitidos en la sesión de checkout.
- `customer_email` (string): Dirección de correo electrónico del cliente que realiza el pago.

### Respuesta

- `id` (string): Identificador único del pago.
- `checkout_id` (string): ID de la sesión de checkout asociada.
- `customer_email` (string|null): Correo electrónico del cliente, si se proporcionó.
- `pay_asset_id` (string): ID del activo utilizado para el pago.
- `network_id` (string): ID de la red blockchain de la transacción.
- `expired_at` (timestamp): Momento en que expirará el pago.
- `payer_address` (string|null): Dirección desde la que se envió el pago, si está disponible.
- `tx_hash` (string|null): Hash de la transacción, si está disponible.
- `converted_crypto_price` (string): El monto del pago convertido a la criptomoneda seleccionada.
- `deposit_address` (string): Dirección a la que debe enviarse el pago.
- `deposit_qr` (string): URL de un código QR que contiene la dirección de depósito.
- `created_at` (timestamp): Momento en que se creó el pago.
- `updated_at` (timestamp): Momento de la última actualización del pago.

**Request** `POST /checkouts/:id/payment`

```typescript
import { PaymentService, Environment } from '@fystack/sdk'

const paymentService = new PaymentService({
  apiKey: apiCredentials.APIKey,
  environment: Environment.Production
})

// First get the checkout to see available assets
const checkout = await paymentService.getCheckout('2912168a-6bb6-4b5c-88bb-723706718e4a')

// Then create a payment using one of the supported assets
const payment = await paymentService.createCheckoutPayment(checkout.id, {
  pay_asset_id: checkout.supported_assets[0].id
})
```

```bash
curl -X POST https://api.fystack.io/api/v1/checkouts/2912168a-6bb6-4b5c-88bb-723706718e4a/payment \
  -H "Content-Type: application/json" \
  -d '{
    "pay_asset_id": "e9337429-a741-4e92-afbb-c1b1fc1ad8a4"
  }'
```

```json
{
  "success": true,
  "message": "success",
  "code": 0,
  "data": {
    "id": "06d92c50-e6f1-4637-8c20-72cf7e7d7b8a",
    "created_at": "2025-05-17T12:50:57.925269212+07:00",
    "updated_at": "2025-05-17T12:50:57.925269212+07:00",
    "checkout_id": "2912168a-6bb6-4b5c-88bb-723706718e4a",
    "checkout": null,
    "customer_email": null,
    "pay_asset_id": "e9337429-a741-4e92-afbb-c1b1fc1ad8a4",
    "network_id": "dd21bfb5-f809-4070-a789-18ec8abbee1b",
    "network": null,
    "expired_at": "2025-05-17T13:50:57.853990519+07:00",
    "payer_address": null,
    "tx_hash": null,
    "converted_crypto_price": "66",
    "deposit_address": "0xAbE72E79729e7463cd0822700255eD03bc6BD37C",
    "deposit_qr": "https://quickchart.io/qr?size=300&margin=2&text=0xAbE72E79729e7463cd0822700255eD03bc6BD37C"
  }
}
```

---

## Obtener un pago de checkout

**Endpoint:** `GET /checkouts/payment/:id`

Obtén información detallada sobre un pago de checkout por su ID.

### Respuesta

- `id` (string): Identificador único del pago.
- `checkout_id` (string): ID de la sesión de checkout asociada.
- `checkout` (object): El objeto completo de la sesión de checkout.
- `customer_email` (string|null): Correo electrónico del cliente, si se proporcionó.
- `pay_asset_id` (string): ID del activo utilizado para el pago.
- `pay_asset` (object): Detalles del activo utilizado para el pago.
- `network_id` (string): ID de la red blockchain de la transacción.
- `network` (object): Detalles de la red blockchain.
- `expired_at` (timestamp): Momento en que expirará el pago.
- `payer_address` (string|null): Dirección desde la que se envió el pago, si está disponible.
- `tx_hash` (string|null): Hash de la transacción, si está disponible.
- `converted_crypto_price` (string): El monto del pago convertido a la criptomoneda seleccionada.
- `deposit_address` (string): Dirección a la que debe enviarse el pago.
- `deposit_qr` (string): URL de un código QR que contiene la dirección de depósito.
- `created_at` (timestamp): Momento en que se creó el pago.
- `updated_at` (timestamp): Momento de la última actualización del pago.

**Request** `GET /checkouts/payment/:id`

```typescript
import { PaymentService, Environment } from '@fystack/sdk'

const paymentService = new PaymentService({
  apiKey: apiCredentials.APIKey,
  environment: Environment.Production
})

const checkoutPayment = await paymentService.getCheckoutPayment('06d92c50-e6f1-4637-8c20-72cf7e7d7b8a')
console.log('checkout payment', checkoutPayment)
```

```bash
curl -X GET https://api.fystack.io/api/v1/checkouts/payment/06d92c50-e6f1-4637-8c20-72cf7e7d7b8a
```

```json
{
  "success": true,
  "message": "success",
  "code": 0,
  "data": {
    "id": "06d92c50-e6f1-4637-8c20-72cf7e7d7b8a",
    "created_at": "2025-05-17T12:50:57.925269+07:00",
    "updated_at": "2025-05-17T12:50:57.925269+07:00",
    "checkout_id": "2912168a-6bb6-4b5c-88bb-723706718e4a",
    "checkout": {
      "id": "2912168a-6bb6-4b5c-88bb-723706718e4a",
      "created_at": "2025-05-17T12:50:57.807741+07:00",
      "updated_at": "2025-05-17T12:50:57.807741+07:00",
      "currency": "USD",
      "product_id": "4c57fae9-1a54-4a1b-9d94-00d5b4a3e1d2",
      "order_id": "bc5bd50d-265e-4ea9-b312-bd8de5118683",
      "workspace_id": "ffb8c9d1-0bd2-4c30-bf4f-2a8fe7710d51",
      "underpaid_cover_percent": 0,
      "description": "Access to premium features and exclusive content.",
      "price": "66",
      "supported_assets": [],
      "customer_id": "bc5bd50d-265e-4ea9-b312-bd8de5118683",
      "expiry_duration_seconds": 3600,
      "enable_localization": false,
      "success_url": "https://example.com/payment/success",
      "cancel_url": "https://example.com/payment/cancel",
      "status": "Pending",
      "outcome": null,
      "from_address": null
    },
    "customer_email": null,
    "pay_asset_id": "e9337429-a741-4e92-afbb-c1b1fc1ad8a4",
    "pay_asset": {
      "id": "e9337429-a741-4e92-afbb-c1b1fc1ad8a4",
      "symbol": "USDC",
      "name": "USD Coin",
      "logo_url": "https://assets-cdn.trustwallet.com/blockchains/ethereum/assets/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48/logo.png"
    },
    "network_id": "dd21bfb5-f809-4070-a789-18ec8abbee1b",
    "network": {
      "id": "dd21bfb5-f809-4070-a789-18ec8abbee1b",
      "name": "Ethereum",
      "logo_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRyVyCtMa_rKwrl1y0hyWcqPda3eG0vssJBAX5xQznEPw&s"
    },
    "expired_at": "2025-05-17T13:50:57.85399+07:00",
    "payer_address": null,
    "tx_hash": null,
    "converted_crypto_price": "66",
    "deposit_address": "0xAbE72E79729e7463cd0822700255eD03bc6BD37C",
    "deposit_qr": "https://quickchart.io/qr?size=300&margin=2&text=0xAbE72E79729e7463cd0822700255eD03bc6BD37C"
  }
}
```

## Webhooks de checkout

La API de Checkout de Fystack usa webhooks para notificar a tu aplicación cuando ocurren eventos importantes, por ejemplo cuando se completa una sesión de checkout o cuando un pago se realiza con éxito o falla.

### Eventos de webhook comunes

- `payment.received`: se activa cuando se recibe un pago.
- `payment.success`: se activa cuando un pago se completa con éxito.

### Verificar eventos de webhook

Por razones de seguridad, siempre debes verificar los eventos de webhook para asegurarte de que realmente los envió Fystack. Cada solicitud de webhook incluye una firma en el header `X-Webhook-Signature` que puedes usar para verificar la autenticidad del payload del webhook. El tipo de evento también se incluye en el header `X-Webhook-Event`.

Para verificar un evento de webhook, necesitarás:

1. El payload del evento de webhook
2. La firma del header `X-Webhook-Signature`

Con el método `verifyEvent` del SDK, puedes comprobar fácilmente si el webhook es válido antes de procesarlo.

### Estructura del payload del evento

- `webhook_id` (string): Identificador único de la configuración del webhook.
- `resource_id` (string): Identificador del recurso asociado al evento.
- `url` (string): La URL a la que se envió el webhook.
- `payload` (object): Los datos reales del evento, con detalles sobre el checkout o el pago.
- `event` (string): El tipo de evento (p. ej., "payment.received", "payment.success").

**Verificar un evento de webhook**

```typescript
import { APIService, Environment } from '@fystack/sdk'

// Express.js example
app.post('/webhook', express.raw({type: 'application/json'}), async (req, res) => {
  const signature = req.headers['x-webhook-signature'] as string;
  const eventType = req.headers['x-webhook-event'] as string;
  const event = req.body;

  const apiService = new APIService(apiCredentials, Environment.Production);

  try {
    const isValid = await apiService.Webhook.verifyEvent(event, signature);

    if (isValid) {
      // Process the webhook event
      if (eventType === 'payment.received') {
        const { checkout_id, tx_hash, status } = event.payload;
        console.log(`Payment received for checkout ${checkout_id}: ${tx_hash}`);
        // Update your database, notify your user, etc.
      }

      res.status(200).send('Webhook received and verified');
    } else {
      console.warn('Invalid webhook signature');
      res.status(400).send('Invalid signature');
    }
  } catch (error) {
    console.error('Webhook verification failed', error);
    res.status(400).send('Webhook verification failed');
  }
});
```

```javascript
import { APIService, Environment } from '@fystack/sdk'

// Example of manually verifying a webhook
const apiService = new APIService(apiCredentials, Environment.Production)
const event = {
  webhook_id: 'add3a1be-fc91-413c-9b4a-028f0011954a',
  resource_id: 'checkout:b065623b-dc9c-4399-964a-99850d78d289:Pending',
  url: 'https://webhook.site/3a782a92-0d1b-4848-8c57-cc0837cba513',
  payload: {
    amount: '10',
    chain_id: 11155111,
    checkout_id: '664f5839-2b5a-4b8b-8507-3b9b4815b9c1',
    checkout_payment_id: 'b2f7d8b6-4e90-43b4-be6d-a5910ef53fdd',
    deposit_address: '0x06A388F07F0EB0605D57947A7F1856a5e091940b',
    from_address: 'ACCLHbGJYGy1vSL6RjHvaraT3XZn1bXMxz5fPVRA112G',
    network_code: 'ETHER_SEPOLIA_TESTNET',
    network_id: '23d13c03-1f3c-4e2a-9aef-1771a244b7f6',
    status: 'Pending',
    timestamp: '2025-02-09T23:42:24.83521+07:00',
    tx_hash: '0x928af7fee293a501fbbe847025a19d2f42ceaf4cd000112fbba63e053c6d02ea'
  },
  event: 'payment.received'
}
const signature = '735d2bdca20d3414eb2dba1e2de54a262ca11e9fc80f6c0a05b5196fec18cce3'

const isValid = await apiService.Webhook.verifyEvent(event, signature)

if (isValid) {
  console.log('Webhook verified successfully')
  // Process the webhook
} else {
  console.warn('Invalid webhook signature')
}
```

### Ejemplo de payload de webhook