Checkout

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

POST/checkouts

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`

Retrieve a checkout payment

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)

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

Required parameters

Optional parameters

Response

Request

Retrieve a checkout

Response

Request

Create a checkout payment

Required parameters

Optional parameters

Response

Request

Retrieve a checkout payment

Response

Request

Checkout Webhooks

Common webhook events

Verifying webhook events

Event payload structure

Verifying a webhook event

Example webhook payload