---
title: "Checkout"
description: "Integrate Fystack's Checkout API to create seamless payment experiences for your users."
url: https://docs.fystack.io/checkout
last_updated: 2026-10-15
---

> ## 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

The Checkout API provides a powerful way to create payment sessions, manage payment flows, and process transactions through Fystack's secure infrastructure.

---

## Create a checkout

**Endpoint:** `POST /checkouts`

To create a new checkout, send a POST request to the `/checkouts` endpoint with the required parameters.

### Parameters

- `price` (string, required): The payment amount as a string (e.g., "66").
- `currency` (string, required): Three-letter ISO currency code (e.g., USD, EUR). Currently only USD is supported.
- `expiry_duration_seconds` (number, required): Number of seconds until the checkout session expires. Must be between 0 and 31536000.
- `destination_wallet_id` (string, required): Wallet ID where the payment will be sent to.

  _Image: Copy Wallet ID_

### Asset parameters

Provide either `supported_assets` or `accepted_assets`.

- `supported_assets` (array): List of supported cryptocurrency assets. Each item can be an asset UUID or an alias in the format "SYMBOL:CHAIN_ID" (e.g., "SOL:1399811149").

  | Chain | Chain ID | Format Example |
  | --- | --- | --- |
  | 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): List of supported cryptocurrency assets in human-readable form. Each item contains `asset` and `network`, for example asset `USDC` on network `ETHEREUM_MAINNET`.
- `success_url` (string): URL to redirect customers to after successful payment.
- `cancel_url` (string): URL to redirect customers to if they cancel the checkout process.
- `description` (string): Description of what the customer is purchasing.
- `product_id` (string): Unique identifier for the product being purchased.
- `customer_id` (string): Link this checkout to an existing customer in your system.
- `order_id` (string): Unique identifier for the order.
- `enable_localization` (boolean): Whether to enable localization for the checkout page. Default is false.
- `from_address` (string): Optional payer address. If provided, Fystack uses the single wallet payment flow.
- `underpaid_cover_percent` (number): Allowed underpayment tolerance percentage. Must be between 0 and 100.

### Response

- `id` (string): Unique identifier for the checkout session.
- `checkout_url` (string): URL to the hosted checkout page. Redirect customers to this URL.
- `status` (string): Status of the checkout session. Can be `Pending`, `Confirming`, `Success`, `Expired`, `Unresolved`, `Resolved`, or `Cancelled`.
- `created_at` (timestamp): Time at which the checkout session was created.
- `updated_at` (timestamp): Time at which the checkout session was last updated.
- `currency` (string): Three-letter ISO currency code.
- `price` (string): The payment amount as a string.
- `product_id` (string): Unique identifier for the product being purchased.
- `order_id` (string): Unique identifier for the order.
- `workspace_id` (string): Identifier for the workspace this checkout belongs to.
- `description` (string): Description of what the customer is purchasing.
- `supported_assets` (array): List of cryptocurrency assets supported for this checkout.
- `customer_id` (string): Identifier for the customer associated with this checkout.
- `expiry_duration_seconds` (number): Number of seconds until the checkout session expires.
- `enable_localization` (boolean): Whether localization is enabled for the checkout page.
- `success_url` (string): URL to redirect customers to after successful payment.
- `cancel_url` (string): URL to redirect customers to if they cancel the checkout process.
- `outcome` (object|null): Information about the payment outcome, if available.
- `from_address` (string|null): The address from which the payment was made, if available.

**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"
  }
}
```

---

## Retrieve a checkout

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

Retrieve the details of a checkout by its ID.

### Response

- `id` (string): Unique identifier for the checkout.
- `status` (string): Status of the checkout. Can be `Pending`, `Confirming`, `Success`, `Expired`, `Unresolved`, `Resolved`, or `Cancelled`.
- `price` (string): The payment amount as a string.
- `currency` (string): Three-letter ISO currency code.
- `created_at` (timestamp): Time at which the checkout was created.
- `updated_at` (timestamp): Time at which the checkout was last updated.
- `product_id` (string): Unique identifier for the product being purchased.
- `order_id` (string): Unique identifier for the order.
- `workspace_id` (string): Identifier for the workspace this checkout belongs to.
- `description` (string): Description of what the customer is purchasing.
- `supported_assets` (array): List of cryptocurrency assets supported for this checkout.
- `customer_id` (string): Identifier for the customer associated with this checkout.
- `expiry_duration_seconds` (number): Number of seconds until the checkout expires.
- `success_url` (string): URL to redirect customers to after successful payment.
- `cancel_url` (string): URL to redirect customers to if they cancel the checkout process.
- `checkout_url` (string): URL to the hosted checkout page.
- `outcome` (object|null): Information about the payment outcome, if available.
- `from_address` (string|null): The address from which the payment was made, if available.

**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"
  }
}
```

---

## Create a checkout payment

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

Create a payment for an existing checkout session by specifying which supported asset to use for payment.

### Parameters

- `pay_asset_id` (string, required): The ID of the asset to use for payment. Must be one of the supported assets in the checkout session.
- `customer_email` (string): Email address of the customer making the payment.

### Response

- `id` (string): Unique identifier for the payment.
- `checkout_id` (string): ID of the associated checkout session.
- `customer_email` (string|null): Email of the customer, if provided.
- `pay_asset_id` (string): ID of the asset being used for payment.
- `network_id` (string): ID of the blockchain network for the transaction.
- `expired_at` (timestamp): Time at which the payment will expire.
- `payer_address` (string|null): Address from which the payment was sent, if available.
- `tx_hash` (string|null): Transaction hash, if available.
- `converted_crypto_price` (string): The payment amount converted to the selected cryptocurrency.
- `deposit_address` (string): Address where payment should be sent.
- `deposit_qr` (string): URL to a QR code containing the deposit address.
- `created_at` (timestamp): Time at which the payment was created.
- `updated_at` (timestamp): Time at which the payment was last updated.

**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"
  }
}
```

---

## Retrieve a checkout payment

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

Retrieve detailed information about a checkout payment by its ID.

### Response

- `id` (string): Unique identifier for the payment.
- `checkout_id` (string): ID of the associated checkout session.
- `checkout` (object): The complete checkout session object.
- `customer_email` (string|null): Email of the customer, if provided.
- `pay_asset_id` (string): ID of the asset being used for payment.
- `pay_asset` (object): Details of the asset being used for payment.
- `network_id` (string): ID of the blockchain network for the transaction.
- `network` (object): Details of the blockchain network.
- `expired_at` (timestamp): Time at which the payment will expire.
- `payer_address` (string|null): Address from which the payment was sent, if available.
- `tx_hash` (string|null): Transaction hash, if available.
- `converted_crypto_price` (string): The payment amount converted to the selected cryptocurrency.
- `deposit_address` (string): Address where payment should be sent.
- `deposit_qr` (string): URL to a QR code containing the deposit address.
- `created_at` (timestamp): Time at which the payment was created.
- `updated_at` (timestamp): Time at which the payment was last updated.

**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"
  }
}
```

## Checkout Webhooks

Fystack's Checkout API uses webhooks to notify your application when important events occur, such as when a checkout session is completed or a payment succeeds or fails.

### Common webhook events

- `payment.received`: Triggered when a payment is received.
- `payment.success`: Triggered when a payment is successful.

### Verifying webhook events

For security reasons, you should always verify webhook events to ensure they were actually sent by Fystack. Each webhook request includes a signature in the `X-Webhook-Signature` header that you can use to verify the authenticity of the webhook payload. The event type is also included in the `X-Webhook-Event` header.

To verify a webhook event, you'll need:

1. The webhook event payload
2. The signature from the `X-Webhook-Signature` header

Using the SDK's `verifyEvent` method, you can easily check if the webhook is valid before processing it.

### Event payload structure

- `webhook_id` (string): Unique identifier for the webhook configuration.
- `resource_id` (string): Identifier for the resource associated with the event.
- `url` (string): The URL where the webhook was sent.
- `payload` (object): The actual event data, containing details about the checkout or payment.
- `event` (string): The type of event (e.g., "payment.received", "payment.success").

**Verifying a webhook event**

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

### Example webhook payload