Hosted Checkout

Hosted Checkout is the easiest and most secure way to accept payments. Customers are redirected to a Fyber-hosted page that handles card input, validation, and 3D Secure authentication.

Benefits

• PCI Compliant - Card data never touches your servers
• 3D Secure - Automatic 3DS authentication when required
• Optimized UI - Mobile-responsive, conversion-optimized design
• Localized - Supports multiple currencies and languages

How It Works

1. Create a checkout session on your server
2. Redirect the customer to the session URL
3. Customer completes payment on Fyber's hosted page
4. Customer is redirected back to your success/cancel URL
5. Receive webhook notification to fulfill the order

Create a Session

JavaScript

const session = await fyber.checkout.sessions.create({
  mode: 'payment',
  amount: 5000, // $50.00 in cents
  currency: 'JMD',
  successUrl: 'https://yoursite.com/success?session_id={SESSION_ID}',
  cancelUrl: 'https://yoursite.com/cancel',
  lineItems: [
    { name: 'Pro Plan', quantity: 1, unitAmount: 5000 }
  ],
  customerEmail: 'customer@example.com',
  metadata: {
    orderId: '1234'
  }
});

// Redirect to checkout
res.redirect(session.url);

PHP

$session = $fyber->checkout->sessions->create([
    'mode' => 'payment',
    'amount' => 5000,
    'currency' => 'JMD',
    'successUrl' => 'https://yoursite.com/success?session_id={SESSION_ID}',
    'cancelUrl' => 'https://yoursite.com/cancel',
    'lineItems' => [
        ['name' => 'Pro Plan', 'quantity' => 1, 'unitAmount' => 5000]
    ],
    'customerEmail' => 'customer@example.com',
]);

header('Location: ' . $session['url']);

C#

var session = await fyber.Checkout.Sessions.CreateAsync(new CreateCheckoutSessionRequest
{
    Mode = "payment",
    Amount = 5000,
    Currency = "JMD",
    SuccessUrl = "https://yoursite.com/success?session_id={SESSION_ID}",
    CancelUrl = "https://yoursite.com/cancel",
    LineItems = new List<LineItem>
    {
        new LineItem { Name = "Pro Plan", Quantity = 1, UnitAmount = 5000 }
    },
    CustomerEmail = "customer@example.com"
});

return Redirect(session.Url);

Flutter

final session = await fyber.checkout.create(CreateCheckoutRequest(
  mode: CheckoutMode.payment,
  currency: 'JMD',
  lineItems: [
    CheckoutLineItem(name: 'Pro Plan', amount: 5000, quantity: 1),
  ],
  successUrl: 'https://yoursite.com/success?session_id={SESSION_ID}',
  cancelUrl: 'https://yoursite.com/cancel',
));

// Open session.url in browser

Session Parameters

Parameter	Type	Required	Description
mode	string	No	payment (default), setup, or subscription
amount	integer	Yes*	Amount in cents (* not required for setup mode)
currency	string	Yes*	Three-letter currency code (e.g., JMD, USD)
successUrl	string	Yes	URL to redirect after successful payment
cancelUrl	string	Yes	URL to redirect if customer cancels
lineItems	array	No	Array of items being purchased
customerEmail	string	No	Pre-fill customer email
customerId	string	No	Link to existing customer
metadata	object	No	Custom key-value data
intent	string	No	sale (default), authorize, or verify

Checkout Modes

Payment Mode (Default)

Collect a one-time payment.

const session = await fyber.checkout.sessions.create({
  mode: 'payment',
  amount: 5000,
  currency: 'JMD',
  // ...
});

Setup Mode

Save a card for future use without charging it.

const session = await fyber.checkout.sessions.create({
  mode: 'setup',
  customerId: 'cus_123',
  successUrl: 'https://yoursite.com/card-saved?session_id={SESSION_ID}',
  cancelUrl: 'https://yoursite.com/cancel',
});

// After completion, the tokenId is available in the session
const completed = await fyber.checkout.sessions.getBySessionId('cs_...');
console.log(completed.tokenId); // tok_xxx

Subscription Mode

Start a recurring subscription.

const session = await fyber.checkout.sessions.create({
  mode: 'subscription',
  customerId: 'cus_123',
  subscriptionData: {
    amount: 999,
    interval: 'month',
    trialDays: 14,
  },
  // ...
});

Payment Intents

Sale (Default)

Charge the card immediately.

{ intent: 'sale' }

Authorize

Authorize the amount without capturing. Capture later with the Payments API.

{ intent: 'authorize' }

Verify

Validate the card with a $0 authorization. Useful before saving cards.

{ intent: 'verify' }

URL Placeholders

Use these placeholders in your success/cancel URLs:

Placeholder	Description
{SESSION_ID}	The checkout session ID
{PAYMENT_ID}	The payment ID (payment mode only)
{AMOUNT}	The amount in dollars (e.g., "50.00")
{CURRENCY}	The currency code (e.g., "JMD")

successUrl: 'https://yoursite.com/success?session={SESSION_ID}&payment={PAYMENT_ID}'

Verify Payment

After the customer is redirected to your success URL, verify the payment:

// Using the session_id from the URL
const session = await fyber.checkout.sessions.getBySessionId(sessionId);

if (session.status === 'complete') {
  console.log('Payment successful!');
  console.log('Payment ID:', session.paymentId);
  // Fulfill the order
}

Webhooks

Always use webhooks to confirm payment completion. Don't rely solely on the redirect.

app.post('/webhooks/fyber', (req, res) => {
  const event = Fyber.webhooks.verify(
    req.body,
    req.headers['fyber-signature'],
    webhookSecret
  );

  if (event.type === 'checkout.session.completed') {
    const session = event.data.object;
    // Fulfill the order using session.paymentId
  }

  res.json({ received: true });
});

Session Lifecycle

Status	Description
open	Session created, awaiting customer
complete	Payment successful
expired	Session expired (24 hours default)

Expire a Session

Cancel a session before the customer completes it:

await fyber.checkout.sessions.expire(session.id);

List Sessions

const sessions = await fyber.checkout.sessions.list({
  status: 'complete',
  limit: 20,
  customerId: 'cus_123', // Optional filter
});