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

POST

/checkouts

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

Parámetros

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

Parámetros de activos

Proporciona supported_assets o accepted_assets.

Name
supported_assets
Type
array
Description
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
Name
accepted_assets
Type
array
Description
Lista de criptoactivos admitidos en formato legible. Cada elemento contiene asset y network, por ejemplo el activo USDC en la red ETHEREUM_MAINNET.
Name
success_url
Type
string
Description
URL a la que se redirige a los clientes tras un pago exitoso.
Name
cancel_url
Type
string
Description
URL a la que se redirige a los clientes si cancelan el proceso de checkout.
Name
description
Type
string
Description
Descripción de lo que compra el cliente.
Name
product_id
Type
string
Description
Identificador único del producto que se compra.
Name
customer_id
Type
string
Description
Vincula este checkout a un cliente existente en tu sistema.
Name
order_id
Type
string
Description
Identificador único del pedido.
Name
enable_localization
Type
boolean
Description
Indica si se habilita la localización en la página de checkout. El valor predeterminado es false.
Name
from_address
Type
string
Description
Dirección opcional del pagador. Si se proporciona, Fystack usa el flujo de pago de billetera única.
Name
underpaid_cover_percent
Type
number
Description
Porcentaje de tolerancia permitido para pagos insuficientes. Debe estar entre 0 y 100.

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`

Respuesta

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

Request

POST

/checkouts

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
})

Response

200

{
  "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

GET

/checkouts/{id}

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

Respuesta

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

Request

GET

/checkouts/:id

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')

Response

200

{
  "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

POST

/checkouts/{id}/payment

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

Parámetros

Name
pay_asset_id
Type
string
Required
required
Description
El ID del activo que se usará para el pago. Debe ser uno de los activos admitidos en la sesión de checkout.
Name
customer_email
Type
string
Description
Dirección de correo electrónico del cliente que realiza el pago.

Respuesta

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

Request

POST

/checkouts/:id/payment

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
})

Response

200

{
  "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

GET

/checkouts/payment/{id}

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

Respuesta

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

Request

GET

/checkouts/payment/:id

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)

Response

200

{
  "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"
  }
}

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:

El payload del evento de webhook
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

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

Verificar un evento de webhook

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');
  }
});

Checkout

Crear un checkout

Parámetros

Parámetros de activos

Respuesta

Request

Response

Obtener un checkout

Respuesta

Request

Response

Crear un pago de checkout

Parámetros

Respuesta

Request

Response

Obtener un pago de checkout

Respuesta

Request

Response

Webhooks de checkout

Eventos de webhook comunes

Verificar eventos de webhook

Estructura del payload del evento

Verificar un evento de webhook

Ejemplo de payload de webhook