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

POST

/checkouts

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

Parameters

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

Asset parameters

Provide either supported_assets or accepted_assets.

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

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`

Response

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

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

Retrieve a checkout

GET

/checkouts/{id}

Retrieve the details of a checkout by its ID.

Response

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

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

Create a checkout payment

POST

/checkouts/{id}/payment

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

Parameters

Name
pay_asset_id
Type
string
Required
required
Description
The ID of the asset to use for payment. Must be one of the supported assets in the checkout session.
Name
customer_email
Type
string
Description
Email address of the customer making the payment.

Response

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

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

Retrieve a checkout payment

GET

/checkouts/payment/{id}

Retrieve detailed information about a checkout payment by its ID.

Response

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

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

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:

The webhook event payload
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

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

Verifying a webhook event

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

Create a checkout

Parameters

Asset parameters

Response

Request

Response

Retrieve a checkout

Response

Request

Response

Create a checkout payment

Parameters

Response

Request

Response

Retrieve a checkout payment

Response

Request

Response

Checkout Webhooks

Common webhook events

Verifying webhook events

Event payload structure

Verifying a webhook event

Example webhook payload